Session Tools

目标：提供一组小而不易误用的工具，让 agents 可以列出 sessions、拉取历史，并向另一条 session 发送消息。

工具名（Tool Names）

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

Key 模型

• 私聊主桶（main direct chat bucket）永远是字面量 key "main"（会解析为当前 agent 的 main key）。
• 群聊使用 agent:<agentId>:<channel>:group:<id> 或 agent:<agentId>:<channel>:channel:<id>（传入完整 key）。
• Cron jobs 使用 cron:<job.id>。
• Hooks 使用 hook:<uuid>（除非显式设置）。
• Node sessions 使用 node-<nodeId>（除非显式设置）。

global 与 unknown 是保留值，永远不会被列出。如果 session.scope = "global"，我们会在所有 tools 中把它 alias 到 main，让调用方永远看不到 global。

sessions_list

以“行数组”的形式列出 sessions。

参数：

• kinds?: string[]：过滤，可选值为 "main" | "group" | "cron" | "hook" | "node" | "other"
• limit?: number：最大行数（默认：server 默认值；会 clamp，例如 200）
• activeMinutes?: number：仅列出 N 分钟内更新过的 sessions
• messageLimit?: number：0 = 不包含消息（默认 0）；>0 = 包含最后 N 条消息

行为：

• messageLimit > 0 时，会对每个 session 拉取 chat.history，并包含最后 N 条消息。
• 在 list 输出中会过滤 tool results；需要 tool 消息请用 sessions_history。
• 在 sandboxed agent session 中运行时，session tools 默认只展示 spawned-only 可见范围（见下文）。

行结构（JSON）：

• key：session key（string）
• kind：main | group | cron | hook | node | other
• channel：whatsapp | telegram | discord | signal | imessage | webchat | internal | unknown
• displayName（群聊 display label，若可用）
• updatedAt（ms）
• sessionId
• model、contextTokens、totalTokens
• thinkingLevel、verboseLevel、systemSent、abortedLastRun
• sendPolicy（若设置了 session 覆盖）
• lastChannel、lastTo
• deliveryContext（可用时为规范化的 { channel, to, accountId }）
• transcriptPath（根据 store dir + sessionId 尽力推导的路径）
• messages?（仅当 messageLimit > 0 时）

sessions_history

拉取某一条 session 的 transcript。

参数：

• sessionKey（必填；接受 session key 或来自 sessions_list 的 sessionId）
• limit?: number：最大消息数（server 会 clamp）
• includeTools?: boolean（默认 false）

行为：

• includeTools=false 会过滤 role: "toolResult" 的消息。
• 以原始 transcript 格式返回 messages 数组。
• 传入 sessionId 时，Moltbot 会解析到对应的 session key（找不到 id 会报错）。

sessions_send

向另一条 session 注入一条消息。

参数：

• sessionKey（必填；接受 session key 或来自 sessions_list 的 sessionId）
• message（必填）
• timeoutSeconds?: number（默认 >0；0 = fire-and-forget）

行为：

• timeoutSeconds = 0：入队并返回 { runId, status: "accepted" }。
• timeoutSeconds > 0：最多等待 N 秒完成，然后返回 { runId, status: "ok", reply }。
• 等待超时：{ runId, status: "timeout", error }。run 会继续；之后可再调用 sessions_history。
• run 失败：{ runId, status: "error", error }。
• primary run 完成后的“投递宣告（announce delivery）”是 best-effort；status: "ok" 不保证 announce 一定送达。
• 通过 gateway 的 agent.wait（服务端）等待，因此断线重连不会丢失 wait。
• primary run 会注入 agent-to-agent 的消息上下文。
• primary run 完成后，Moltbot 会运行一个 reply-back loop：
  • Round 2+ 在请求方与目标 agent 之间交替。
  • 精确回复 REPLY_SKIP 可停止 ping‑pong。
  • 最大回合数由 session.agentToAgent.maxPingPongTurns 控制（0–5，默认 5）。
• loop 结束后，Moltbot 会运行 agent‑to‑agent announce step（仅 target agent）：
  • 精确回复 ANNOUNCE_SKIP 可保持静默。
  • 任何其他回复会发送到目标 channel。
  • announce step 会包含原始请求 + round‑1 回复 + 最新 ping‑pong 回复。

Channel 字段

• 对群聊，channel 来自 session 条目记录的 channel。
• 对私聊，channel 从 lastChannel 映射。
• 对 cron/hook/node，channel 为 internal。
• 若缺失，则 channel 为 unknown。

Security / Send Policy

基于策略按 channel/chat type 做阻塞（不是按 session id）。

{
  "session": {
    "sendPolicy": {
      "rules": [
        {
          "match": { "channel": "discord", "chatType": "group" },
          "action": "deny"
        }
      ],
      "default": "allow"
    }
  }
}

运行时覆盖（每个 session 条目）：

• sendPolicy: "allow" | "deny"（未设置 = 继承 config）
• 可通过 sessions.patch 或仅 owner 的 /send on|off|inherit（独立消息）设置

执行拦截点：

• chat.send / agent（gateway）
• auto-reply 投递逻辑

sessions_spawn

在一个隔离的 session 中启动子 agent run，并把结果回帖到请求方的聊天渠道。

参数：

• task（必填）
• label?（可选；用于 logs/UI）
• agentId?（可选；如果允许，可在另一个 agent id 下 spawn）
• model?（可选；覆盖子 agent 的模型；无效值会报错）
• runTimeoutSeconds?（默认 0；设置后会在 N 秒后 abort 子 agent run）
• cleanup?（delete|keep，默认 keep）

Allowlist：

• agents.list[].subagents.allowAgents：允许通过 agentId 指定的 agent id 列表（["*"] 表示允许任意）。默认仅允许请求方 agent。

Discovery：

• 使用 agents_list 发现哪些 agent ids 允许用于 sessions_spawn。

行为：

• 启动一个新的 agent:<agentId>:subagent:<uuid> session，并设置 deliver: false。
• 子 agents 默认拥有完整工具集，但不包含 session tools（可通过 tools.subagents.tools 配置）。
• 子 agents 不允许调用 sessions_spawn（禁止“子 agent 再 spawn 子 agent”）。
• 始终非阻塞：立即返回 { status: "accepted", runId, childSessionKey }。
• 完成后，Moltbot 会运行子 agent 的 announce step，并把结果发回请求方聊天渠道。
• announce step 中精确回复 ANNOUNCE_SKIP 可保持静默。
• announce 回复会被规范化为 Status/Result/Notes；其中 Status 来自运行时结果（不是模型文本）。
• 子 agent sessions 会在 agents.defaults.subagents.archiveAfterMinutes（默认：60）后自动归档。
• announce 回复会包含一行 stats（运行时长、tokens、sessionKey/sessionId、transcript path，以及可选 cost）。

Sandbox session 可见性

sandboxed sessions 可以使用 session tools，但默认只看到它们通过 sessions_spawn 自己派生出来的 sessions。

配置：

{
  agents: {
    defaults: {
      sandbox: {
        // default: "spawned"
        sessionToolsVisibility: "spawned" // or "all"
      }
    }
  }
}