From e108632e21779f5d3713c4fb6ebd1425a9b61237 Mon Sep 17 00:00:00 2001 From: Gustavo Madeira Santana Date: Wed, 25 Feb 2026 17:58:42 -0500 Subject: [PATCH] CLI: add explicit agents bind/unbind/bindings commands --- src/cli/program/register.agent.test.ts | 55 ++++ src/cli/program/register.agent.ts | 60 ++++ src/commands/agents.bind.commands.test.ts | 98 +++++++ src/commands/agents.bindings.ts | 66 +++++ src/commands/agents.commands.bind.ts | 316 ++++++++++++++++++++++ src/commands/agents.ts | 1 + 6 files changed, 596 insertions(+) create mode 100644 src/commands/agents.bind.commands.test.ts create mode 100644 src/commands/agents.commands.bind.ts diff --git a/src/cli/program/register.agent.test.ts b/src/cli/program/register.agent.test.ts index 9ad1fa19d52..09f7d6415e7 100644 --- a/src/cli/program/register.agent.test.ts +++ b/src/cli/program/register.agent.test.ts @@ -3,9 +3,12 @@ import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest"; const agentCliCommandMock = vi.fn(); const agentsAddCommandMock = vi.fn(); +const agentsBindingsCommandMock = vi.fn(); +const agentsBindCommandMock = vi.fn(); const agentsDeleteCommandMock = vi.fn(); const agentsListCommandMock = vi.fn(); const agentsSetIdentityCommandMock = vi.fn(); +const agentsUnbindCommandMock = vi.fn(); const setVerboseMock = vi.fn(); const createDefaultDepsMock = vi.fn(() => ({ deps: true })); @@ -21,9 +24,12 @@ vi.mock("../../commands/agent-via-gateway.js", () => ({ vi.mock("../../commands/agents.js", () => ({ agentsAddCommand: agentsAddCommandMock, + agentsBindingsCommand: agentsBindingsCommandMock, + agentsBindCommand: agentsBindCommandMock, agentsDeleteCommand: agentsDeleteCommandMock, agentsListCommand: agentsListCommandMock, agentsSetIdentityCommand: agentsSetIdentityCommandMock, + agentsUnbindCommand: agentsUnbindCommandMock, })); vi.mock("../../globals.js", () => ({ @@ -55,9 +61,12 @@ describe("registerAgentCommands", () => { vi.clearAllMocks(); agentCliCommandMock.mockResolvedValue(undefined); agentsAddCommandMock.mockResolvedValue(undefined); + agentsBindingsCommandMock.mockResolvedValue(undefined); + agentsBindCommandMock.mockResolvedValue(undefined); agentsDeleteCommandMock.mockResolvedValue(undefined); agentsListCommandMock.mockResolvedValue(undefined); agentsSetIdentityCommandMock.mockResolvedValue(undefined); + agentsUnbindCommandMock.mockResolvedValue(undefined); createDefaultDepsMock.mockReturnValue({ deps: true }); }); @@ -147,6 +156,52 @@ describe("registerAgentCommands", () => { ); }); + it("forwards agents bindings options", async () => { + await runCli(["agents", "bindings", "--agent", "ops", "--json"]); + expect(agentsBindingsCommandMock).toHaveBeenCalledWith( + { + agent: "ops", + json: true, + }, + runtime, + ); + }); + + it("forwards agents bind options", async () => { + await runCli([ + "agents", + "bind", + "--agent", + "ops", + "--bind", + "matrix-js:ops", + "--bind", + "telegram", + "--json", + ]); + expect(agentsBindCommandMock).toHaveBeenCalledWith( + { + agent: "ops", + bind: ["matrix-js:ops", "telegram"], + json: true, + }, + runtime, + ); + }); + + it("forwards agents unbind options", async () => { + await runCli(["agents", "unbind", "--agent", "ops", "--all", "--json"]); + expect(agentsUnbindCommandMock).toHaveBeenCalledWith( + { + agent: "ops", + bind: [], + all: true, + json: true, + }, + runtime, + ); + }); + it("forwards agents delete options", async () => { await runCli(["agents", "delete", "worker-a", "--force", "--json"]); expect(agentsDeleteCommandMock).toHaveBeenCalledWith( diff --git a/src/cli/program/register.agent.ts b/src/cli/program/register.agent.ts index 4f112403c14..84281c9e11b 100644 --- a/src/cli/program/register.agent.ts +++ b/src/cli/program/register.agent.ts @@ -2,9 +2,12 @@ import type { Command } from "commander"; import { agentCliCommand } from "../../commands/agent-via-gateway.js"; import { agentsAddCommand, + agentsBindingsCommand, + agentsBindCommand, agentsDeleteCommand, agentsListCommand, agentsSetIdentityCommand, + agentsUnbindCommand, } from "../../commands/agents.js"; import { setVerbose } from "../../globals.js"; import { defaultRuntime } from "../../runtime.js"; @@ -102,6 +105,63 @@ ${theme.muted("Docs:")} ${formatDocsLink("/cli/agent", "docs.openclaw.ai/cli/age }); }); + agents + .command("bindings") + .description("List routing bindings") + .option("--agent ", "Filter by agent id") + .option("--json", "Output JSON instead of text", false) + .action(async (opts) => { + await runCommandWithRuntime(defaultRuntime, async () => { + await agentsBindingsCommand( + { + agent: opts.agent as string | undefined, + json: Boolean(opts.json), + }, + defaultRuntime, + ); + }); + }); + + agents + .command("bind") + .description("Add routing bindings for an agent") + .option("--agent ", "Agent id (defaults to current default agent)") + .option("--bind ", "Binding to add (repeatable)", collectOption, []) + .option("--json", "Output JSON summary", false) + .action(async (opts) => { + await runCommandWithRuntime(defaultRuntime, async () => { + await agentsBindCommand( + { + agent: opts.agent as string | undefined, + bind: Array.isArray(opts.bind) ? (opts.bind as string[]) : undefined, + json: Boolean(opts.json), + }, + defaultRuntime, + ); + }); + }); + + agents + .command("unbind") + .description("Remove routing bindings for an agent") + .option("--agent ", "Agent id (defaults to current default agent)") + .option("--bind ", "Binding to remove (repeatable)", collectOption, []) + .option("--all", "Remove all bindings for this agent", false) + .option("--json", "Output JSON summary", false) + .action(async (opts) => { + await runCommandWithRuntime(defaultRuntime, async () => { + await agentsUnbindCommand( + { + agent: opts.agent as string | undefined, + bind: Array.isArray(opts.bind) ? (opts.bind as string[]) : undefined, + all: Boolean(opts.all), + json: Boolean(opts.json), + }, + defaultRuntime, + ); + }); + }); + agents .command("add [name]") .description("Add a new isolated agent") diff --git a/src/commands/agents.bind.commands.test.ts b/src/commands/agents.bind.commands.test.ts new file mode 100644 index 00000000000..456f9408138 --- /dev/null +++ b/src/commands/agents.bind.commands.test.ts @@ -0,0 +1,98 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; +import { baseConfigSnapshot, createTestRuntime } from "./test-runtime-config-helpers.js"; + +const readConfigFileSnapshotMock = vi.hoisted(() => vi.fn()); +const writeConfigFileMock = vi.hoisted(() => vi.fn().mockResolvedValue(undefined)); + +vi.mock("../config/config.js", async (importOriginal) => ({ + ...(await importOriginal()), + readConfigFileSnapshot: readConfigFileSnapshotMock, + writeConfigFile: writeConfigFileMock, +})); + +import { agentsBindCommand, agentsBindingsCommand, agentsUnbindCommand } from "./agents.js"; + +const runtime = createTestRuntime(); + +describe("agents bind/unbind commands", () => { + beforeEach(() => { + readConfigFileSnapshotMock.mockClear(); + writeConfigFileMock.mockClear(); + runtime.log.mockClear(); + runtime.error.mockClear(); + runtime.exit.mockClear(); + }); + + it("lists all bindings by default", async () => { + readConfigFileSnapshotMock.mockResolvedValue({ + ...baseConfigSnapshot, + config: { + bindings: [ + { agentId: "main", match: { channel: "matrix-js" } }, + { agentId: "ops", match: { channel: "telegram", accountId: "work" } }, + ], + }, + }); + + await agentsBindingsCommand({}, runtime); + + expect(runtime.log).toHaveBeenCalledWith(expect.stringContaining("main <- matrix-js")); + expect(runtime.log).toHaveBeenCalledWith( + expect.stringContaining("ops <- telegram accountId=work"), + ); + }); + + it("binds routes to default agent when --agent is omitted", async () => { + readConfigFileSnapshotMock.mockResolvedValue({ + ...baseConfigSnapshot, + config: {}, + }); + + await agentsBindCommand({ bind: ["telegram"] }, runtime); + + expect(writeConfigFileMock).toHaveBeenCalledWith( + expect.objectContaining({ + bindings: [{ agentId: "main", match: { channel: "telegram" } }], + }), + ); + expect(runtime.exit).not.toHaveBeenCalled(); + }); + + it("unbinds all routes for an agent", async () => { + readConfigFileSnapshotMock.mockResolvedValue({ + ...baseConfigSnapshot, + config: { + agents: { list: [{ id: "ops", workspace: "/tmp/ops" }] }, + bindings: [ + { agentId: "main", match: { channel: "matrix-js" } }, + { agentId: "ops", match: { channel: "telegram", accountId: "work" } }, + ], + }, + }); + + await agentsUnbindCommand({ agent: "ops", all: true }, runtime); + + expect(writeConfigFileMock).toHaveBeenCalledWith( + expect.objectContaining({ + bindings: [{ agentId: "main", match: { channel: "matrix-js" } }], + }), + ); + expect(runtime.exit).not.toHaveBeenCalled(); + }); + + it("reports ownership conflicts during unbind and exits 1", async () => { + readConfigFileSnapshotMock.mockResolvedValue({ + ...baseConfigSnapshot, + config: { + agents: { list: [{ id: "ops", workspace: "/tmp/ops" }] }, + bindings: [{ agentId: "main", match: { channel: "telegram", accountId: "ops" } }], + }, + }); + + await agentsUnbindCommand({ agent: "ops", bind: ["telegram:ops"] }, runtime); + + expect(writeConfigFileMock).not.toHaveBeenCalled(); + expect(runtime.error).toHaveBeenCalledWith("Bindings are owned by another agent:"); + expect(runtime.exit).toHaveBeenCalledWith(1); + }); +}); diff --git a/src/commands/agents.bindings.ts b/src/commands/agents.bindings.ts index f0eaf959e1e..b5edce30ecd 100644 --- a/src/commands/agents.bindings.ts +++ b/src/commands/agents.bindings.ts @@ -89,6 +89,72 @@ export function applyAgentBindings( }; } +export function removeAgentBindings( + cfg: OpenClawConfig, + bindings: AgentBinding[], +): { + config: OpenClawConfig; + removed: AgentBinding[]; + missing: AgentBinding[]; + conflicts: Array<{ binding: AgentBinding; existingAgentId: string }>; +} { + const existing = cfg.bindings ?? []; + const removeIndexes = new Set(); + const removed: AgentBinding[] = []; + const missing: AgentBinding[] = []; + const conflicts: Array<{ binding: AgentBinding; existingAgentId: string }> = []; + + for (const binding of bindings) { + const desiredAgentId = normalizeAgentId(binding.agentId); + const key = bindingMatchKey(binding.match); + let matchedIndex = -1; + let conflictingAgentId: string | null = null; + for (let i = 0; i < existing.length; i += 1) { + if (removeIndexes.has(i)) { + continue; + } + const current = existing[i]; + if (!current || bindingMatchKey(current.match) !== key) { + continue; + } + const currentAgentId = normalizeAgentId(current.agentId); + if (currentAgentId === desiredAgentId) { + matchedIndex = i; + break; + } + conflictingAgentId = currentAgentId; + } + if (matchedIndex >= 0) { + const matched = existing[matchedIndex]; + if (matched) { + removeIndexes.add(matchedIndex); + removed.push(matched); + } + continue; + } + if (conflictingAgentId) { + conflicts.push({ binding, existingAgentId: conflictingAgentId }); + continue; + } + missing.push(binding); + } + + if (removeIndexes.size === 0) { + return { config: cfg, removed, missing, conflicts }; + } + + const nextBindings = existing.filter((_, index) => !removeIndexes.has(index)); + return { + config: { + ...cfg, + bindings: nextBindings.length > 0 ? nextBindings : undefined, + }, + removed, + missing, + conflicts, + }; +} + function resolveDefaultAccountId(cfg: OpenClawConfig, provider: ChannelId): string { const plugin = getChannelPlugin(provider); if (!plugin) { diff --git a/src/commands/agents.commands.bind.ts b/src/commands/agents.commands.bind.ts new file mode 100644 index 00000000000..c48785be598 --- /dev/null +++ b/src/commands/agents.commands.bind.ts @@ -0,0 +1,316 @@ +import { resolveDefaultAgentId } from "../agents/agent-scope.js"; +import { writeConfigFile } from "../config/config.js"; +import { logConfigUpdated } from "../config/logging.js"; +import type { AgentBinding } from "../config/types.js"; +import { normalizeAgentId } from "../routing/session-key.js"; +import type { RuntimeEnv } from "../runtime.js"; +import { defaultRuntime } from "../runtime.js"; +import { + applyAgentBindings, + describeBinding, + parseBindingSpecs, + removeAgentBindings, +} from "./agents.bindings.js"; +import { requireValidConfig } from "./agents.command-shared.js"; +import { buildAgentSummaries } from "./agents.config.js"; + +type AgentsBindingsListOptions = { + agent?: string; + json?: boolean; +}; + +type AgentsBindOptions = { + agent?: string; + bind?: string[]; + json?: boolean; +}; + +type AgentsUnbindOptions = { + agent?: string; + bind?: string[]; + all?: boolean; + json?: boolean; +}; + +function resolveAgentId( + cfg: Awaited>, + agentInput: string | undefined, + params?: { fallbackToDefault?: boolean }, +): string | null { + if (!cfg) { + return null; + } + if (agentInput?.trim()) { + return normalizeAgentId(agentInput); + } + if (params?.fallbackToDefault) { + return resolveDefaultAgentId(cfg); + } + return null; +} + +function hasAgent(cfg: Awaited>, agentId: string): boolean { + if (!cfg) { + return false; + } + return buildAgentSummaries(cfg).some((summary) => summary.id === agentId); +} + +function formatBindingOwnerLine(binding: AgentBinding): string { + return `${normalizeAgentId(binding.agentId)} <- ${describeBinding(binding)}`; +} + +export async function agentsBindingsCommand( + opts: AgentsBindingsListOptions, + runtime: RuntimeEnv = defaultRuntime, +) { + const cfg = await requireValidConfig(runtime); + if (!cfg) { + return; + } + + const filterAgentId = resolveAgentId(cfg, opts.agent?.trim()); + if (opts.agent && !filterAgentId) { + runtime.error("Agent id is required."); + runtime.exit(1); + return; + } + if (filterAgentId && !hasAgent(cfg, filterAgentId)) { + runtime.error(`Agent "${filterAgentId}" not found.`); + runtime.exit(1); + return; + } + + const filtered = (cfg.bindings ?? []).filter( + (binding) => !filterAgentId || normalizeAgentId(binding.agentId) === filterAgentId, + ); + if (opts.json) { + runtime.log( + JSON.stringify( + filtered.map((binding) => ({ + agentId: normalizeAgentId(binding.agentId), + match: binding.match, + description: describeBinding(binding), + })), + null, + 2, + ), + ); + return; + } + + if (filtered.length === 0) { + runtime.log( + filterAgentId ? `No routing bindings for agent "${filterAgentId}".` : "No routing bindings.", + ); + return; + } + + runtime.log( + [ + "Routing bindings:", + ...filtered.map((binding) => `- ${formatBindingOwnerLine(binding)}`), + ].join("\n"), + ); +} + +export async function agentsBindCommand( + opts: AgentsBindOptions, + runtime: RuntimeEnv = defaultRuntime, +) { + const cfg = await requireValidConfig(runtime); + if (!cfg) { + return; + } + + const agentId = resolveAgentId(cfg, opts.agent?.trim(), { fallbackToDefault: true }); + if (!agentId) { + runtime.error("Unable to resolve agent id."); + runtime.exit(1); + return; + } + if (!hasAgent(cfg, agentId)) { + runtime.error(`Agent "${agentId}" not found.`); + runtime.exit(1); + return; + } + + const specs = (opts.bind ?? []).map((value) => value.trim()).filter(Boolean); + if (specs.length === 0) { + runtime.error("Provide at least one --bind ."); + runtime.exit(1); + return; + } + + const parsed = parseBindingSpecs({ agentId, specs, config: cfg }); + if (parsed.errors.length > 0) { + runtime.error(parsed.errors.join("\n")); + runtime.exit(1); + return; + } + + const result = applyAgentBindings(cfg, parsed.bindings); + if (result.added.length > 0) { + await writeConfigFile(result.config); + if (!opts.json) { + logConfigUpdated(runtime); + } + } + + const payload = { + agentId, + added: result.added.map(describeBinding), + skipped: result.skipped.map(describeBinding), + conflicts: result.conflicts.map( + (conflict) => `${describeBinding(conflict.binding)} (agent=${conflict.existingAgentId})`, + ), + }; + if (opts.json) { + runtime.log(JSON.stringify(payload, null, 2)); + if (result.conflicts.length > 0) { + runtime.exit(1); + } + return; + } + + if (result.added.length > 0) { + runtime.log("Added bindings:"); + for (const binding of result.added) { + runtime.log(`- ${describeBinding(binding)}`); + } + } else { + runtime.log("No new bindings added."); + } + + if (result.skipped.length > 0) { + runtime.log("Already present:"); + for (const binding of result.skipped) { + runtime.log(`- ${describeBinding(binding)}`); + } + } + + if (result.conflicts.length > 0) { + runtime.error("Skipped bindings already claimed by another agent:"); + for (const conflict of result.conflicts) { + runtime.error(`- ${describeBinding(conflict.binding)} (agent=${conflict.existingAgentId})`); + } + runtime.exit(1); + } +} + +export async function agentsUnbindCommand( + opts: AgentsUnbindOptions, + runtime: RuntimeEnv = defaultRuntime, +) { + const cfg = await requireValidConfig(runtime); + if (!cfg) { + return; + } + + const agentId = resolveAgentId(cfg, opts.agent?.trim(), { fallbackToDefault: true }); + if (!agentId) { + runtime.error("Unable to resolve agent id."); + runtime.exit(1); + return; + } + if (!hasAgent(cfg, agentId)) { + runtime.error(`Agent "${agentId}" not found.`); + runtime.exit(1); + return; + } + if (opts.all && (opts.bind?.length ?? 0) > 0) { + runtime.error("Use either --all or --bind, not both."); + runtime.exit(1); + return; + } + + if (opts.all) { + const existing = cfg.bindings ?? []; + const removed = existing.filter((binding) => normalizeAgentId(binding.agentId) === agentId); + const kept = existing.filter((binding) => normalizeAgentId(binding.agentId) !== agentId); + if (removed.length === 0) { + runtime.log(`No bindings to remove for agent "${agentId}".`); + return; + } + const next = { + ...cfg, + bindings: kept.length > 0 ? kept : undefined, + }; + await writeConfigFile(next); + if (!opts.json) { + logConfigUpdated(runtime); + } + const payload = { + agentId, + removed: removed.map(describeBinding), + missing: [] as string[], + conflicts: [] as string[], + }; + if (opts.json) { + runtime.log(JSON.stringify(payload, null, 2)); + return; + } + runtime.log(`Removed ${removed.length} binding(s) for "${agentId}".`); + return; + } + + const specs = (opts.bind ?? []).map((value) => value.trim()).filter(Boolean); + if (specs.length === 0) { + runtime.error("Provide at least one --bind or use --all."); + runtime.exit(1); + return; + } + + const parsed = parseBindingSpecs({ agentId, specs, config: cfg }); + if (parsed.errors.length > 0) { + runtime.error(parsed.errors.join("\n")); + runtime.exit(1); + return; + } + + const result = removeAgentBindings(cfg, parsed.bindings); + if (result.removed.length > 0) { + await writeConfigFile(result.config); + if (!opts.json) { + logConfigUpdated(runtime); + } + } + + const payload = { + agentId, + removed: result.removed.map(describeBinding), + missing: result.missing.map(describeBinding), + conflicts: result.conflicts.map( + (conflict) => `${describeBinding(conflict.binding)} (agent=${conflict.existingAgentId})`, + ), + }; + if (opts.json) { + runtime.log(JSON.stringify(payload, null, 2)); + if (result.conflicts.length > 0) { + runtime.exit(1); + } + return; + } + + if (result.removed.length > 0) { + runtime.log("Removed bindings:"); + for (const binding of result.removed) { + runtime.log(`- ${describeBinding(binding)}`); + } + } else { + runtime.log("No bindings removed."); + } + if (result.missing.length > 0) { + runtime.log("Not found:"); + for (const binding of result.missing) { + runtime.log(`- ${describeBinding(binding)}`); + } + } + if (result.conflicts.length > 0) { + runtime.error("Bindings are owned by another agent:"); + for (const conflict of result.conflicts) { + runtime.error(`- ${describeBinding(conflict.binding)} (agent=${conflict.existingAgentId})`); + } + runtime.exit(1); + } +} diff --git a/src/commands/agents.ts b/src/commands/agents.ts index 6679bb853da..5f5bdcd3c7b 100644 --- a/src/commands/agents.ts +++ b/src/commands/agents.ts @@ -1,4 +1,5 @@ export * from "./agents.bindings.js"; +export * from "./agents.commands.bind.js"; export * from "./agents.commands.add.js"; export * from "./agents.commands.delete.js"; export * from "./agents.commands.identity.js";