@chrysb/alphaclaw 0.6.0-beta.1 → 0.6.0-beta.2

package/lib/public/js/components/agents-tab/agent-bindings-section/use-channel-items.js

@@ -0,0 +1,211 @@
+import { h } from "https://esm.sh/preact";
+import { useEffect, useMemo, useState } from "https://esm.sh/preact/hooks";
+import htm from "https://esm.sh/htm";
+import {
+  canAgentBindAccount,
+  getChannelItemSortRank,
+  getResolvedAccountStatusInfo,
+  isImplicitDefaultAccount,
+  resolveChannelAccountLabel,
+} from "./helpers.js";
+
+const html = htm.bind(h);
+
+export const useChannelItems = ({
+  agentId = "",
+  agentNameMap = new Map(),
+  channelStatus = {},
+  configuredChannelMap = new Map(),
+  configuredChannels = [],
+  defaultAgentId = "",
+  isDefaultAgent = false,
+}) => {
+  const hasDiscordAccount = useMemo(() => {
+    const discordChannel = configuredChannelMap.get("discord");
+    return Array.isArray(discordChannel?.accounts) && discordChannel.accounts.length > 0;
+  }, [configuredChannelMap]);
+
+  const [showAssignedElsewhere, setShowAssignedElsewhere] = useState(false);
+
+  const channelItemData = useMemo(() => {
+    const channelOrderMap = new Map(
+      configuredChannels.map((entry, index) => [
+        String(entry?.channel || "").trim(),
+        index,
+      ]),
+    );
+    const accountOrderMap = new Map(
+      configuredChannels.flatMap((entry) =>
+        (Array.isArray(entry?.accounts) ? entry.accounts : []).map(
+          (account, accountIndex) => [
+            `${String(entry?.channel || "").trim()}:${String(account?.id || "").trim() || "default"}`,
+            accountIndex,
+          ],
+        ),
+      ),
+    );
+    const channelIds = Array.from(
+      new Set([
+        ...configuredChannels.map((entry) => String(entry.channel || "").trim()),
+      ]),
+    ).filter(Boolean);
+
+    return channelIds
+      .flatMap((channelId) => {
+        const configuredChannel = configuredChannelMap.get(channelId);
+        const statusInfo = channelStatus?.[channelId] || null;
+        const accounts = Array.isArray(configuredChannel?.accounts)
+          ? configuredChannel.accounts
+          : [];
+
+        if (!configuredChannel && !statusInfo) return [];
+
+        return accounts.map((account) => {
+          const accountId = String(account?.id || "").trim() || "default";
+          const boundAgentId = String(account?.boundAgentId || "").trim();
+          const accountStatusInfo = getResolvedAccountStatusInfo({
+            account,
+            statusInfo,
+            accountId,
+          });
+          const isImplicitDefaultOwned =
+            isDefaultAgent &&
+            isImplicitDefaultAccount({ accountId, boundAgentId });
+          const isOwned = boundAgentId === agentId || isImplicitDefaultOwned;
+          const isImplicitDefaultElsewhere =
+            !isDefaultAgent &&
+            isImplicitDefaultAccount({ accountId, boundAgentId });
+          const isAvailable = canAgentBindAccount({
+            accountId,
+            boundAgentId,
+            agentId,
+            isDefaultAgent,
+          });
+          const ownerAgentId =
+            boundAgentId ||
+            (isImplicitDefaultAccount({ accountId, boundAgentId })
+              ? defaultAgentId
+              : "");
+          const ownerAgentName = String(
+            agentNameMap.get(ownerAgentId) || ownerAgentId || "",
+          ).trim();
+          const canNavigateToOwnerAgent =
+            !!ownerAgentId && ownerAgentId !== agentId && !!ownerAgentName;
+          const canOpenWorkspace =
+            channelId === "telegram" &&
+            isOwned &&
+            accountStatusInfo?.status === "paired";
+
+          const accountData = {
+            id: accountId,
+            provider: channelId,
+            name: resolveChannelAccountLabel({ channelId, account }),
+            rawName: String(account?.name || "").trim(),
+            ownerAgentId,
+            ownerAgentName,
+            boundAgentId,
+            isOwned,
+            envKey: String(account?.envKey || "").trim(),
+            token: String(account?.token || "").trim(),
+            isAvailable,
+            isBoundElsewhere:
+              !isOwned &&
+              (!isAvailable || isImplicitDefaultElsewhere || !!ownerAgentId),
+          };
+
+          return {
+            id: `${channelId}:${accountId}`,
+            channel: channelId,
+            accountId,
+            channelOrder: Number(channelOrderMap.get(channelId) ?? 9999),
+            accountOrder: Number(
+              accountOrderMap.get(`${channelId}:${accountId}`) ?? 9999,
+            ),
+            label: resolveChannelAccountLabel({ channelId, account }),
+            isAwaitingPairing: accountStatusInfo?.status !== "paired",
+            canOpenWorkspace,
+            canNavigateToOwnerAgent,
+            ownerAgentId,
+            ownerAgentName,
+            accountStatusInfo,
+            accountData,
+            isOwned,
+            isAvailable,
+            dimmedLabel: accountData.isBoundElsewhere,
+            isBoundElsewhere: accountData.isBoundElsewhere,
+          };
+        });
+      })
+      .filter(Boolean)
+      .sort((a, b) => {
+        const rankDiff = getChannelItemSortRank(a) - getChannelItemSortRank(b);
+        if (rankDiff !== 0) return rankDiff;
+        const channelOrderDiff =
+          Number(a?.channelOrder ?? 9999) - Number(b?.channelOrder ?? 9999);
+        if (channelOrderDiff !== 0) return channelOrderDiff;
+        const accountOrderDiff =
+          Number(a?.accountOrder ?? 9999) - Number(b?.accountOrder ?? 9999);
+        if (accountOrderDiff !== 0) return accountOrderDiff;
+        return String(a?.label || "").localeCompare(String(b?.label || ""));
+      });
+  }, [
+    agentId,
+    agentNameMap,
+    channelStatus,
+    configuredChannelMap,
+    configuredChannels,
+    defaultAgentId,
+    isDefaultAgent,
+  ]);
+
+  const visibleChannelItems = channelItemData.filter(
+    (item) => !item?.isBoundElsewhere,
+  );
+  const assignedElsewhereItems = channelItemData.filter(
+    (item) => !!item?.isBoundElsewhere,
+  );
+
+  useEffect(() => {
+    if (assignedElsewhereItems.length === 0) {
+      setShowAssignedElsewhere(false);
+      return;
+    }
+    if (visibleChannelItems.length === 0) {
+      setShowAssignedElsewhere(true);
+    }
+  }, [agentId, assignedElsewhereItems.length, visibleChannelItems.length]);
+
+  const mergedChannelItems = useMemo(() => {
+    const baseItems = [...visibleChannelItems];
+    if (assignedElsewhereItems.length === 0) return baseItems;
+    baseItems.push({
+      id: "__assigned_elsewhere_toggle",
+      label: html`
+        <span class="inline-flex items-center gap-1.5">
+          <span class=${`arrow inline-block ${showAssignedElsewhere ? "" : "-rotate-90"}`}>▼</span>
+          <span>Assigned elsewhere</span>
+        </span>
+      `,
+      labelClassName: "text-xs",
+      clickable: true,
+      onClick: () => setShowAssignedElsewhere((current) => !current),
+      dimmedLabel: true,
+      trailing: html`
+        <span class="inline-flex items-center gap-1.5 text-gray-500">
+          <span class="text-[11px] px-2 py-0.5 rounded-full border border-border">
+            ${assignedElsewhereItems.length}
+          </span>
+        </span>
+      `,
+    });
+    if (showAssignedElsewhere) {
+      baseItems.push(...assignedElsewhereItems);
+    }
+    return baseItems;
+  }, [assignedElsewhereItems, showAssignedElsewhere, visibleChannelItems]);
+
+  return {
+    hasDiscordAccount,
+    mergedChannelItems,
+  };
+};

package/lib/public/js/components/agents-tab/agent-pairing-section.js

@@ -40,6 +40,7 @@ export const AgentPairingSection = ({ agent = {} }) => {
   const [loadingBindings, setLoadingBindings] = useState(true);
   const [pairingStatusRefreshing, setPairingStatusRefreshing] = useState(false);
   const pairingRefreshTimerRef = useRef(null);
+  const pairingDelayedRefreshTimerRefs = useRef([]);
   const agentId = String(agent?.id || "").trim();
   const isDefaultAgent = !!agent?.default;
 
@@ -82,6 +83,10 @@ export const AgentPairingSection = ({ agent = {} }) => {
       if (pairingRefreshTimerRef.current) {
         clearTimeout(pairingRefreshTimerRef.current);
       }
+      for (const timerId of pairingDelayedRefreshTimerRefs.current) {
+        clearTimeout(timerId);
+      }
+      pairingDelayedRefreshTimerRefs.current = [];
     },
     [],
   );
@@ -217,19 +222,27 @@ export const AgentPairingSection = ({ agent = {} }) => {
       setPairingStatusRefreshing(false);
       pairingRefreshTimerRef.current = null;
     }, 2800);
+    for (const timerId of pairingDelayedRefreshTimerRefs.current) {
+      clearTimeout(timerId);
+    }
+    pairingDelayedRefreshTimerRefs.current = [];
     const refresh = () => {
       pairingsPoll.refresh();
       loadBindings();
       announcePairingsChanged(agentId);
     };
     refresh();
-    setTimeout(refresh, 500);
-    setTimeout(refresh, 2000);
+    pairingDelayedRefreshTimerRefs.current.push(setTimeout(refresh, 500));
+    pairingDelayedRefreshTimerRefs.current.push(setTimeout(refresh, 2000));
   }, [agentId, loadBindings, pairingsPoll]);
 
   const handleApprove = async (id, channel, accountId = "") => {
-    await approvePairing(id, channel, accountId);
-    refreshAfterPairingAction();
+    try {
+      await approvePairing(id, channel, accountId);
+      refreshAfterPairingAction();
+    } catch (err) {
+      showToast(err.message || "Could not approve pairing", "error");
+    }
   };
 
   const handleReject = async (id, channel, accountId = "") => {

package/lib/public/js/components/agents-tab/create-channel-modal.js

@@ -63,9 +63,19 @@ export const CreateChannelModal = ({
         ? initialProvider
         : ALL_CHANNELS[0] || "telegram";
     const providerLabel = getChannelMeta(nextProvider).label || "Channel";
+    const nextSelectedChannel =
+      existingChannels.find(
+        (entry) =>
+          String(entry?.channel || "").trim() === String(nextProvider || "").trim(),
+      ) || null;
+    const nextProviderHasAccounts =
+      Array.isArray(nextSelectedChannel?.accounts)
+      && nextSelectedChannel.accounts.length > 0;
     const nextName = isEditMode
       ? String(account?.name || "").trim() || providerLabel
-      : providerLabel;
+      : nextProviderHasAccounts
+        ? ""
+        : providerLabel;
     const nextAgentId = isEditMode
       ? String(account?.ownerAgentId || "").trim()
         || String(initialAgentId || "").trim()
@@ -85,12 +95,16 @@ export const CreateChannelModal = ({
     setAgentId(nextAgentId);
     setError("");
     setNameEditedManually(isEditMode);
-  }, [visible, initialAgentId, initialProvider, agents, isEditMode, account]);
+  }, [
+    visible,
+    initialAgentId,
+    initialProvider,
+    agents,
+    existingChannels,
+    isEditMode,
+    account,
+  ]);
 
-  useEffect(() => {
-    if (nameEditedManually) return;
-    setName(getChannelMeta(provider).label || "Channel");
-  }, [provider, nameEditedManually]);
   const selectedChannel = useMemo(
     () =>
       existingChannels.find(
@@ -103,6 +117,15 @@ export const CreateChannelModal = ({
     () => Array.isArray(selectedChannel?.accounts) && selectedChannel.accounts.length > 0,
     [selectedChannel],
   );
+  useEffect(() => {
+    if (nameEditedManually) return;
+    const providerLabel = getChannelMeta(provider).label || "Channel";
+    if (!isEditMode && providerHasAccounts) {
+      setName("");
+      return;
+    }
+    setName(providerLabel);
+  }, [provider, providerHasAccounts, nameEditedManually, isEditMode]);
   const isSingleAccountProvider = String(provider || "").trim() === "discord";
 
   const accountId = useMemo(() => {

package/lib/public/js/components/channels.js

@@ -16,6 +16,10 @@ import {
   fetchChannelAccounts,
   updateChannelAccount,
 } from "../lib/api.js";
+import {
+  isImplicitDefaultAccount,
+  resolveChannelAccountLabel,
+} from "../lib/channel-accounts.js";
 import { createChannelAccountWithProgress } from "../lib/channel-create-operation.js";
 import { CreateChannelModal } from "./agents-tab/create-channel-modal.js";
 import { showToast } from "./toast.js";
@@ -40,18 +44,6 @@ const getChannelMeta = (channelId = "") => {
   );
 };
 
-const resolveChannelAccountLabel = ({ channelId, account = {} }) => {
-  const providerLabel = getChannelMeta(channelId).label || "Channel";
-  const configuredName = String(account?.name || "").trim();
-  if (configuredName) return configuredName;
-  const accountId = String(account?.id || "").trim();
-  if (!accountId || accountId === "default") return providerLabel;
-  return `${providerLabel} ${accountId}`;
-};
-
-const isImplicitDefaultAccount = ({ accountId, boundAgentId }) =>
-  String(accountId || "").trim() === "default" &&
-  !String(boundAgentId || "").trim();
 const announceRestartRequired = () =>
   window.dispatchEvent(new CustomEvent("alphaclaw:restart-required"));
 
@@ -60,6 +52,7 @@ export const ChannelsCard = ({
   items = [],
   loadingLabel = "Loading...",
   actions = null,
+  renderItem = null,
 }) => html`
   <div class="bg-surface border border-border rounded-xl p-4">
     <div class="flex items-center justify-between gap-3 mb-3">
@@ -71,6 +64,10 @@ export const ChannelsCard = ({
         ? items.map((item) => {
             const channelMeta = getChannelMeta(item.channel || item.id);
             const clickable = !!item.clickable;
+            const customItem = renderItem
+              ? renderItem({ item, channelMeta, clickable })
+              : null;
+            if (customItem) return customItem;
             return html`
               <div
                 key=${item.id || item.channel}
@@ -342,7 +339,11 @@ export const Channels = ({
                 const accountData = {
                   id: accountId,
                   provider: channelId,
-                  name: resolveChannelAccountLabel({ channelId, account }),
+                  name: resolveChannelAccountLabel({
+                    channelId,
+                    account,
+                    providerLabel: getChannelMeta(channelId).label || "Channel",
+                  }),
                   ownerAgentId,
                   envKey: String(account?.envKey || "").trim(),
                   token: String(account?.token || "").trim(),
@@ -422,7 +423,11 @@ export const Channels = ({
                   accountOrder: Number(
                     accountOrderMap.get(`${channelId}:${accountId}`) ?? 9999,
                   ),
-                  label: resolveChannelAccountLabel({ channelId, account }),
+                  label: resolveChannelAccountLabel({
+                    channelId,
+                    account,
+                    providerLabel: getChannelMeta(channelId).label || "Channel",
+                  }),
                   isAwaitingPairing: accountStatus !== "paired",
                   detailText: isClickable ? "Workspace" : "",
                   detailChevron: isClickable,

package/lib/public/js/lib/channel-accounts.js

@@ -0,0 +1,20 @@
+export const resolveChannelAccountLabel = ({
+  channelId,
+  account = {},
+  providerLabel = "",
+}) => {
+  const fallbackProviderLabel = channelId
+    ? channelId.charAt(0).toUpperCase() + channelId.slice(1)
+    : "Channel";
+  const resolvedProviderLabel = String(providerLabel || "").trim()
+    || fallbackProviderLabel;
+  const configuredName = String(account?.name || "").trim();
+  if (configuredName) return configuredName;
+  const accountId = String(account?.id || "").trim();
+  if (!accountId || accountId === "default") return resolvedProviderLabel;
+  return `${resolvedProviderLabel} ${accountId}`;
+};
+
+export const isImplicitDefaultAccount = ({ accountId, boundAgentId }) =>
+  String(accountId || "").trim() === "default" &&
+  !String(boundAgentId || "").trim();

package/lib/server/agents/agents.js

@@ -0,0 +1,207 @@
+const path = require("path");
+
+const {
+  kDefaultAgentId,
+  resolveAgentWorkspacePath,
+  loadConfig,
+  saveConfig,
+  cloneJson,
+  getSafeStat,
+  calculatePathSizeBytes,
+  withNormalizedAgentsConfig,
+  isValidAgentId,
+  resolveRequestedWorkspacePath,
+  ensureAgentScaffold,
+} = require("./shared");
+
+const createAgentsDomain = ({ fsImpl, OPENCLAW_DIR }) => {
+  const listAgents = () => {
+    const cfg = withNormalizedAgentsConfig({
+      OPENCLAW_DIR,
+      cfg: loadConfig({ fsImpl, OPENCLAW_DIR }),
+    });
+    return (cfg.agents?.list || []).map((entry) => ({
+      ...entry,
+      id: String(entry.id || "").trim(),
+      name: String(entry.name || "").trim() || String(entry.id || "").trim(),
+      default: !!entry.default,
+    }));
+  };
+
+  const getAgent = (agentId) => {
+    const normalized = String(agentId || "").trim();
+    return listAgents().find((entry) => entry.id === normalized) || null;
+  };
+
+  const getAgentWorkspaceSize = (agentId) => {
+    const normalized = String(agentId || "").trim();
+    const agent = getAgent(normalized);
+    if (!agent) throw new Error(`Agent "${normalized}" not found`);
+    const workspacePath = String(
+      agent.workspace ||
+        resolveAgentWorkspacePath({ OPENCLAW_DIR, agentId: normalized }),
+    ).trim();
+    if (!workspacePath) {
+      return { workspacePath: "", exists: false, sizeBytes: 0 };
+    }
+    const stat = getSafeStat({ fsImpl, targetPath: workspacePath });
+    if (!stat) {
+      return { workspacePath, exists: false, sizeBytes: 0 };
+    }
+    return {
+      workspacePath,
+      exists: true,
+      sizeBytes: calculatePathSizeBytes({ fsImpl, targetPath: workspacePath }),
+    };
+  };
+
+  const createAgent = (input = {}) => {
+    const agentId = String(input.id || "").trim();
+    if (!isValidAgentId(agentId)) {
+      throw new Error(
+        "Agent id must be lowercase letters, numbers, and hyphens only",
+      );
+    }
+
+    const cfg = withNormalizedAgentsConfig({
+      OPENCLAW_DIR,
+      cfg: loadConfig({ fsImpl, OPENCLAW_DIR }),
+    });
+    const existing = cfg.agents.list.find((entry) => entry.id === agentId);
+    if (existing) {
+      throw new Error(`Agent "${agentId}" already exists`);
+    }
+
+    const workspacePath = resolveRequestedWorkspacePath({
+      OPENCLAW_DIR,
+      agentId,
+      workspaceFolder: input.workspaceFolder,
+    });
+    const { workspacePath: scaffoldWorkspacePath, agentDirPath } =
+      ensureAgentScaffold({
+        fsImpl,
+        workspacePath,
+        OPENCLAW_DIR,
+        agentId,
+      });
+    const nextAgent = {
+      id: agentId,
+      name: String(input.name || "").trim() || agentId,
+      default: false,
+      workspace: scaffoldWorkspacePath,
+      agentDir: agentDirPath,
+      ...(input.model ? { model: input.model } : {}),
+      ...(input.identity && typeof input.identity === "object"
+        ? { identity: { ...input.identity } }
+        : {}),
+    };
+    cfg.agents.list = [...cfg.agents.list, nextAgent];
+    saveConfig({ fsImpl, OPENCLAW_DIR, config: cfg });
+    return nextAgent;
+  };
+
+  const updateAgent = (agentId, patch = {}) => {
+    const normalized = String(agentId || "").trim();
+    const cfg = withNormalizedAgentsConfig({
+      OPENCLAW_DIR,
+      cfg: loadConfig({ fsImpl, OPENCLAW_DIR }),
+    });
+    const index = cfg.agents.list.findIndex((entry) => entry.id === normalized);
+    if (index < 0) throw new Error(`Agent "${normalized}" not found`);
+    const current = cfg.agents.list[index];
+    const next = {
+      ...current,
+      ...(patch.name !== undefined
+        ? { name: String(patch.name || "").trim() }
+        : {}),
+      ...(patch.identity !== undefined
+        ? {
+            identity:
+              patch.identity && typeof patch.identity === "object"
+                ? { ...patch.identity }
+                : {},
+          }
+        : {}),
+    };
+    if (patch.model !== undefined) {
+      if (patch.model === null) {
+        delete next.model;
+      } else {
+        next.model = patch.model;
+      }
+    }
+    if (!String(next.name || "").trim()) next.name = normalized;
+    cfg.agents.list[index] = next;
+    saveConfig({ fsImpl, OPENCLAW_DIR, config: cfg });
+    return next;
+  };
+
+  const setDefaultAgent = (agentId) => {
+    const normalized = String(agentId || "").trim();
+    const cfg = withNormalizedAgentsConfig({
+      OPENCLAW_DIR,
+      cfg: loadConfig({ fsImpl, OPENCLAW_DIR }),
+    });
+    const exists = cfg.agents.list.some((entry) => entry.id === normalized);
+    if (!exists) throw new Error(`Agent "${normalized}" not found`);
+    cfg.agents.list = cfg.agents.list.map((entry) => ({
+      ...entry,
+      default: entry.id === normalized,
+    }));
+    saveConfig({ fsImpl, OPENCLAW_DIR, config: cfg });
+    return cfg.agents.list.find((entry) => entry.id === normalized) || null;
+  };
+
+  const deleteAgent = (agentId, { keepWorkspace = true } = {}) => {
+    const normalized = String(agentId || "").trim();
+    if (!normalized || normalized === kDefaultAgentId) {
+      throw new Error("The default main agent cannot be deleted");
+    }
+    const cfg = withNormalizedAgentsConfig({
+      OPENCLAW_DIR,
+      cfg: loadConfig({ fsImpl, OPENCLAW_DIR }),
+    });
+    const target = cfg.agents.list.find((entry) => entry.id === normalized);
+    if (!target) throw new Error(`Agent "${normalized}" not found`);
+    if (target.default) {
+      throw new Error("Default agent cannot be deleted");
+    }
+    cfg.agents.list = cfg.agents.list.filter(
+      (entry) => entry.id !== normalized,
+    );
+    if (Array.isArray(cfg.bindings)) {
+      cfg.bindings = cfg.bindings.filter(
+        (binding) => String(binding?.agentId || "") !== normalized,
+      );
+    }
+    saveConfig({ fsImpl, OPENCLAW_DIR, config: cfg });
+
+    if (!keepWorkspace) {
+      const workspacePath = String(
+        target.workspace ||
+          resolveAgentWorkspacePath({
+            OPENCLAW_DIR,
+            agentId: normalized,
+          }),
+      ).trim();
+      const agentDirPath = path.join(OPENCLAW_DIR, "agents", normalized);
+      if (workspacePath) {
+        fsImpl.rmSync(workspacePath, { recursive: true, force: true });
+      }
+      fsImpl.rmSync(agentDirPath, { recursive: true, force: true });
+    }
+    return { ok: true };
+  };
+
+  return {
+    listAgents,
+    getAgent,
+    getAgentWorkspaceSize,
+    createAgent,
+    updateAgent,
+    setDefaultAgent,
+    deleteAgent,
+  };
+};
+
+module.exports = { createAgentsDomain };

package/lib/server/agents/bindings.js

@@ -0,0 +1,74 @@
+const {
+  loadConfig,
+  saveConfig,
+  cloneJson,
+  normalizeBindingMatch,
+  matchesBinding,
+  appendBindingToConfig,
+  withNormalizedAgentsConfig,
+} = require("./shared");
+
+const createBindingsDomain = ({ fsImpl, OPENCLAW_DIR }) => {
+  const getBindingsForAgent = (agentId) => {
+    const normalized = String(agentId || "").trim();
+    const cfg = withNormalizedAgentsConfig({
+      OPENCLAW_DIR,
+      cfg: loadConfig({ fsImpl, OPENCLAW_DIR }),
+    });
+    const bindings = Array.isArray(cfg.bindings) ? cfg.bindings : [];
+    return bindings
+      .filter((binding) => String(binding?.agentId || "").trim() === normalized)
+      .map((binding) => cloneJson(binding));
+  };
+
+  const addBinding = (agentId, input = {}) => {
+    const normalizedAgentId = String(agentId || "").trim();
+    const cfg = withNormalizedAgentsConfig({
+      OPENCLAW_DIR,
+      cfg: loadConfig({ fsImpl, OPENCLAW_DIR }),
+    });
+    const agent = cfg.agents.list.find(
+      (entry) => entry.id === normalizedAgentId,
+    );
+    if (!agent) throw new Error(`Agent "${normalizedAgentId}" not found`);
+    const match = normalizeBindingMatch(input);
+    const nextBinding = appendBindingToConfig({
+      cfg,
+      agentId: normalizedAgentId,
+      match,
+    });
+    saveConfig({ fsImpl, OPENCLAW_DIR, config: cfg });
+    return nextBinding;
+  };
+
+  const removeBinding = (agentId, input = {}) => {
+    const normalizedAgentId = String(agentId || "").trim();
+    const cfg = withNormalizedAgentsConfig({
+      OPENCLAW_DIR,
+      cfg: loadConfig({ fsImpl, OPENCLAW_DIR }),
+    });
+    const bindings = Array.isArray(cfg.bindings) ? cfg.bindings : [];
+    const nextMatch = normalizeBindingMatch(input);
+    const nextBindings = bindings.filter(
+      (binding) =>
+        !(
+          String(binding?.agentId || "").trim() === normalizedAgentId &&
+          matchesBinding(binding?.match || {}, nextMatch)
+        ),
+    );
+    if (nextBindings.length === bindings.length) {
+      throw new Error("Binding not found");
+    }
+    cfg.bindings = nextBindings;
+    saveConfig({ fsImpl, OPENCLAW_DIR, config: cfg });
+    return { ok: true };
+  };
+
+  return {
+    getBindingsForAgent,
+    addBinding,
+    removeBinding,
+  };
+};
+
+module.exports = { createBindingsDomain };