diff --git a/CHANGELOG.md b/CHANGELOG.md index 347f6215f..8bc0047ae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -80,6 +80,7 @@ - Sub-agents: allow `sessions_spawn` model overrides and error on invalid models. Thanks @azade-c for PR #298. - Sub-agents: skip invalid model overrides with a warning and keep the run alive; tool exceptions now return tool errors instead of crashing the agent. - Sub-agents: allow `sessions_spawn` to target other agents via per-agent allowlists (`routing.agents..subagents.allowAgents`). +- Tools: add `agents_list` to reveal allowed `sessions_spawn` targets for the current agent. - Sessions: forward explicit sessionKey through gateway/chat/node bridge to avoid sub-agent sessionId mixups. - Heartbeat: default interval 30m; clarified default prompt usage and HEARTBEAT.md template behavior. - Onboarding: write auth profiles to the multi-agent path (`~/.clawdbot/agents/main/agent/`) so the gateway finds credentials on first startup. Thanks @minghinmatthewlam for PR #327. diff --git a/docs/concepts/session-tool.md b/docs/concepts/session-tool.md index d1ee35bd0..a92cda84e 100644 --- a/docs/concepts/session-tool.md +++ b/docs/concepts/session-tool.md @@ -134,6 +134,9 @@ Parameters: Allowlist: - `routing.agents..subagents.allowAgents`: list of agent ids allowed via `agentId` (`["*"]` to allow any). Default: only the requester agent. +Discovery: +- Use `agents_list` to discover which agent ids are allowed for `sessions_spawn`. + Behavior: - Starts a new `agent::subagent:` session with `deliver: false`. - Sub-agents default to the full tool set **minus session tools** (configurable via `agent.subagents.tools`). diff --git a/docs/tools/index.md b/docs/tools/index.md index 4507cde8f..b29712258 100644 --- a/docs/tools/index.md +++ b/docs/tools/index.md @@ -188,6 +188,13 @@ Notes: - `sessions_send` runs a reply‑back ping‑pong (reply `REPLY_SKIP` to stop; max turns via `session.agentToAgent.maxPingPongTurns`, 0–5). - After the ping‑pong, the target agent runs an **announce step**; reply `ANNOUNCE_SKIP` to suppress the announcement. +### `agents_list` +List agent ids that the current session may target with `sessions_spawn`. + +Notes: +- Result is restricted to per-agent allowlists (`routing.agents..subagents.allowAgents`). +- When `["*"]` is configured, the tool includes all configured agents and marks `allowAny: true`. + ### `discord` Send Discord reactions, stickers, or polls. diff --git a/docs/tools/subagents.md b/docs/tools/subagents.md index 427d04a20..9151d332a 100644 --- a/docs/tools/subagents.md +++ b/docs/tools/subagents.md @@ -32,6 +32,9 @@ Tool params: Allowlist: - `routing.agents..subagents.allowAgents`: list of agent ids that can be targeted via `agentId` (`["*"]` to allow any). Default: only the requester agent. +Discovery: +- Use `agents_list` to see which agent ids are currently allowed for `sessions_spawn`. + Auto-archive: - Sub-agent sessions are automatically archived after `agent.subagents.archiveAfterMinutes` (default: 60). - Archive uses `sessions.delete` and renames the transcript to `*.deleted.` (same folder). diff --git a/src/agents/clawdbot-tools.agents.test.ts b/src/agents/clawdbot-tools.agents.test.ts new file mode 100644 index 000000000..efb525007 --- /dev/null +++ b/src/agents/clawdbot-tools.agents.test.ts @@ -0,0 +1,123 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; + +let configOverride: ReturnType< + typeof import("../config/config.js")["loadConfig"] +> = { + session: { + mainKey: "main", + scope: "per-sender", + }, +}; + +vi.mock("../config/config.js", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + loadConfig: () => configOverride, + resolveGatewayPort: () => 18789, + }; +}); + +import { createClawdbotTools } from "./clawdbot-tools.js"; + +describe("agents_list", () => { + beforeEach(() => { + configOverride = { + session: { + mainKey: "main", + scope: "per-sender", + }, + }; + }); + + it("defaults to the requester agent only", async () => { + const tool = createClawdbotTools({ + agentSessionKey: "main", + }).find((candidate) => candidate.name === "agents_list"); + if (!tool) throw new Error("missing agents_list tool"); + + const result = await tool.execute("call1", {}); + expect(result.details).toMatchObject({ + requester: "main", + allowAny: false, + }); + const agents = (result.details as { agents?: Array<{ id: string }> }) + .agents; + expect(agents?.map((agent) => agent.id)).toEqual(["main"]); + }); + + it("includes allowlisted targets plus requester", async () => { + configOverride = { + session: { + mainKey: "main", + scope: "per-sender", + }, + routing: { + agents: { + main: { + name: "Main", + subagents: { + allowAgents: ["research"], + }, + }, + research: { + name: "Research", + }, + }, + }, + }; + + const tool = createClawdbotTools({ + agentSessionKey: "main", + }).find((candidate) => candidate.name === "agents_list"); + if (!tool) throw new Error("missing agents_list tool"); + + const result = await tool.execute("call2", {}); + const agents = (result.details as { + agents?: Array<{ id: string }>; + }).agents; + expect(agents?.map((agent) => agent.id)).toEqual(["main", "research"]); + }); + + it("returns configured agents when allowlist is *", async () => { + configOverride = { + session: { + mainKey: "main", + scope: "per-sender", + }, + routing: { + agents: { + main: { + subagents: { + allowAgents: ["*"], + }, + }, + research: { + name: "Research", + }, + coder: { + name: "Coder", + }, + }, + }, + }; + + const tool = createClawdbotTools({ + agentSessionKey: "main", + }).find((candidate) => candidate.name === "agents_list"); + if (!tool) throw new Error("missing agents_list tool"); + + const result = await tool.execute("call3", {}); + expect(result.details).toMatchObject({ + allowAny: true, + }); + const agents = (result.details as { + agents?: Array<{ id: string }>; + }).agents; + expect(agents?.map((agent) => agent.id)).toEqual([ + "main", + "coder", + "research", + ]); + }); +}); diff --git a/src/agents/clawdbot-tools.subagents.test.ts b/src/agents/clawdbot-tools.subagents.test.ts index 992ddf65e..8a26e92d1 100644 --- a/src/agents/clawdbot-tools.subagents.test.ts +++ b/src/agents/clawdbot-tools.subagents.test.ts @@ -286,6 +286,26 @@ describe("subagents", () => { expect(childSessionKey?.startsWith("agent:main:subagent:")).toBe(true); }); + it("sessions_spawn only allows same-agent by default", async () => { + resetSubagentRegistryForTests(); + callGatewayMock.mockReset(); + + const tool = createClawdbotTools({ + agentSessionKey: "main", + agentProvider: "whatsapp", + }).find((candidate) => candidate.name === "sessions_spawn"); + if (!tool) throw new Error("missing sessions_spawn tool"); + + const result = await tool.execute("call6", { + task: "do thing", + agentId: "beta", + }); + expect(result.details).toMatchObject({ + status: "forbidden", + }); + expect(callGatewayMock).not.toHaveBeenCalled(); + }); + it("sessions_spawn allows cross-agent spawning when configured", async () => { resetSubagentRegistryForTests(); callGatewayMock.mockReset(); @@ -325,7 +345,58 @@ describe("subagents", () => { }).find((candidate) => candidate.name === "sessions_spawn"); if (!tool) throw new Error("missing sessions_spawn tool"); - const result = await tool.execute("call6", { + const result = await tool.execute("call7", { + task: "do thing", + agentId: "beta", + }); + + expect(result.details).toMatchObject({ + status: "accepted", + runId: "run-1", + }); + expect(childSessionKey?.startsWith("agent:beta:subagent:")).toBe(true); + }); + + it("sessions_spawn allows any agent when allowlist is *", async () => { + resetSubagentRegistryForTests(); + callGatewayMock.mockReset(); + configOverride = { + session: { + mainKey: "main", + scope: "per-sender", + }, + routing: { + agents: { + main: { + subagents: { + allowAgents: ["*"], + }, + }, + }, + }, + }; + + let childSessionKey: string | undefined; + callGatewayMock.mockImplementation(async (opts: unknown) => { + const request = opts as { method?: string; params?: unknown }; + if (request.method === "agent") { + const params = request.params as { sessionKey?: string } | undefined; + childSessionKey = params?.sessionKey; + return { runId: "run-1", status: "accepted", acceptedAt: 5100 }; + } + if (request.method === "agent.wait") { + return { status: "timeout" }; + } + return {}; + }); + + const tool = createClawdbotTools({ + agentSessionKey: "main", + agentProvider: "whatsapp", + }).find((candidate) => candidate.name === "sessions_spawn"); + if (!tool) throw new Error("missing sessions_spawn tool"); + + const result = await tool.execute("call8", { task: "do thing", agentId: "beta", }); @@ -362,7 +433,7 @@ describe("subagents", () => { }).find((candidate) => candidate.name === "sessions_spawn"); if (!tool) throw new Error("missing sessions_spawn tool"); - const result = await tool.execute("call7", { + const result = await tool.execute("call9", { task: "do thing", agentId: "beta", }); diff --git a/src/agents/clawdbot-tools.ts b/src/agents/clawdbot-tools.ts index 5754609e8..6292dd67c 100644 --- a/src/agents/clawdbot-tools.ts +++ b/src/agents/clawdbot-tools.ts @@ -1,6 +1,7 @@ import type { ClawdbotConfig } from "../config/config.js"; import { createBrowserTool } from "./tools/browser-tool.js"; import { createCanvasTool } from "./tools/canvas-tool.js"; +import { createAgentsListTool } from "./tools/agents-list-tool.js"; import type { AnyAgentTool } from "./tools/common.js"; import { createCronTool } from "./tools/cron-tool.js"; import { createDiscordTool } from "./tools/discord-tool.js"; @@ -37,6 +38,7 @@ export function createClawdbotTools(options?: { createTelegramTool(), createWhatsAppTool(), createGatewayTool({ agentSessionKey: options?.agentSessionKey }), + createAgentsListTool({ agentSessionKey: options?.agentSessionKey }), createSessionsListTool({ agentSessionKey: options?.agentSessionKey, sandboxed: options?.sandboxed, diff --git a/src/agents/system-prompt.ts b/src/agents/system-prompt.ts index 3c96664a1..e007f966f 100644 --- a/src/agents/system-prompt.ts +++ b/src/agents/system-prompt.ts @@ -45,6 +45,7 @@ export function buildAgentSystemPrompt(params: { cron: "Manage cron jobs and wake events", gateway: "Restart, apply config, or run updates on the running ClaudeBot process", + agents_list: "List agent ids allowed for sessions_spawn", sessions_list: "List other sessions (incl. sub-agents) with filters/last", sessions_history: "Fetch history for another session/sub-agent", sessions_send: "Send a message to another session/sub-agent", @@ -71,6 +72,7 @@ export function buildAgentSystemPrompt(params: { "nodes", "cron", "gateway", + "agents_list", "sessions_list", "sessions_history", "sessions_send", diff --git a/src/agents/tool-display.json b/src/agents/tool-display.json index 87576fa8a..ef95c8595 100644 --- a/src/agents/tool-display.json +++ b/src/agents/tool-display.json @@ -150,6 +150,11 @@ "restart": { "label": "restart", "detailKeys": ["reason", "delayMs"] } } }, + "agents_list": { + "emoji": "🧭", + "title": "Agents", + "detailKeys": [] + }, "sessions_list": { "emoji": "🗂️", "title": "Sessions", diff --git a/src/agents/tools/agents-list-tool.ts b/src/agents/tools/agents-list-tool.ts new file mode 100644 index 000000000..561973994 --- /dev/null +++ b/src/agents/tools/agents-list-tool.ts @@ -0,0 +1,99 @@ +import { Type } from "@sinclair/typebox"; + +import { loadConfig } from "../../config/config.js"; +import { + DEFAULT_AGENT_ID, + normalizeAgentId, + parseAgentSessionKey, +} from "../../routing/session-key.js"; +import { resolveAgentConfig } from "../agent-scope.js"; +import type { AnyAgentTool } from "./common.js"; +import { jsonResult } from "./common.js"; +import { + resolveInternalSessionKey, + resolveMainSessionAlias, +} from "./sessions-helpers.js"; + +const AgentsListToolSchema = Type.Object({}); + +type AgentListEntry = { + id: string; + name?: string; + configured: boolean; +}; + +export function createAgentsListTool(opts?: { + agentSessionKey?: string; +}): AnyAgentTool { + return { + label: "Agents", + name: "agents_list", + description: + "List agent ids you can target with sessions_spawn (based on allowlists).", + parameters: AgentsListToolSchema, + execute: async () => { + const cfg = loadConfig(); + const { mainKey, alias } = resolveMainSessionAlias(cfg); + const requesterInternalKey = + typeof opts?.agentSessionKey === "string" && opts.agentSessionKey.trim() + ? resolveInternalSessionKey({ + key: opts.agentSessionKey, + alias, + mainKey, + }) + : alias; + const requesterAgentId = normalizeAgentId( + parseAgentSessionKey(requesterInternalKey)?.agentId ?? DEFAULT_AGENT_ID, + ); + + const allowAgents = + resolveAgentConfig(cfg, requesterAgentId)?.subagents?.allowAgents ?? []; + const allowAny = allowAgents.some((value) => value.trim() === "*"); + const allowSet = new Set( + allowAgents + .filter((value) => value.trim() && value.trim() !== "*") + .map((value) => normalizeAgentId(value)), + ); + + const configuredAgents = cfg.routing?.agents ?? {}; + const configuredIds = Object.keys(configuredAgents).map((key) => + normalizeAgentId(key), + ); + const configuredNameMap = new Map(); + for (const [key, value] of Object.entries(configuredAgents)) { + if (!value || typeof value !== "object") continue; + const name = + typeof (value as { name?: unknown }).name === "string" + ? ((value as { name?: string }).name?.trim() ?? "") + : ""; + if (!name) continue; + configuredNameMap.set(normalizeAgentId(key), name); + } + + const allowed = new Set(); + allowed.add(requesterAgentId); + if (allowAny) { + for (const id of configuredIds) allowed.add(id); + } else { + for (const id of allowSet) allowed.add(id); + } + + const all = Array.from(allowed); + const rest = all + .filter((id) => id !== requesterAgentId) + .sort((a, b) => a.localeCompare(b)); + const ordered = [requesterAgentId, ...rest]; + const agents: AgentListEntry[] = ordered.map((id) => ({ + id, + name: configuredNameMap.get(id), + configured: configuredIds.includes(id), + })); + + return jsonResult({ + requester: requesterAgentId, + allowAny, + agents, + }); + }, + }; +}