@agenthippo-ai/agenthippo 0.1.0

package/out/gateway/openclaw-channel-routing.js

@@ -0,0 +1,317 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) AgentHippo.ai. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchMeetAgentChannelContext = fetchMeetAgentChannelContext;
+exports.mapChannelsStatusToMeetAgentRows = mapChannelsStatusToMeetAgentRows;
+exports.parseChannelBindSpecs = parseChannelBindSpecs;
+exports.applyAgentChannelBindingsViaConfigPatch = applyAgentChannelBindingsViaConfigPatch;
+exports.fetchMeetAgentChannelRows = fetchMeetAgentChannelRows;
+exports.waitForChannelsLive = waitForChannelsLive;
+exports.resolvePublishedGatewayChannelIds = resolvePublishedGatewayChannelIds;
+const CHANNELS_STATUS_PARAMS = {
+    probe: false,
+    timeoutMs: 10_000,
+};
+/**
+ * Single `channels.status` round-trip for Meet Agent UI / CLI bind flows.
+ */
+async function fetchMeetAgentChannelContext(request) {
+    const statusPayload = await request("channels.status", CHANNELS_STATUS_PARAMS);
+    return {
+        rows: mapChannelsStatusToMeetAgentRows(statusPayload),
+        statusPayload,
+    };
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * Build the channel list shape the Meet Agent picker expects from a
+ * `channels.status` success payload.
+ */
+function mapChannelsStatusToMeetAgentRows(statusPayload) {
+    const root = asRecord(statusPayload);
+    if (!root) {
+        return [];
+    }
+    const channelOrder = Array.isArray(root.channelOrder)
+        ? root.channelOrder
+        : null;
+    const channelLabels = asRecord(root.channelLabels) ?? {};
+    const channels = asRecord(root.channels) ?? {};
+    const channelAccounts = asRecord(root.channelAccounts) ?? {};
+    const channelDefaultAccountId = asRecord(root.channelDefaultAccountId) ?? {};
+    const ids = channelOrder && channelOrder.length > 0
+        ? channelOrder
+        : [...Object.keys(channels)].sort((a, b) => a.localeCompare(b));
+    const rows = [];
+    for (const id of ids) {
+        const label = typeof channelLabels[id] === "string" ? channelLabels[id] : id;
+        const snapshots = channelAccounts[id];
+        const accountList = Array.isArray(snapshots)
+            ? snapshots
+            : [];
+        const accountIds = accountList.length > 0
+            ? accountList.map((a) => typeof a.accountId === "string" ? a.accountId : "default")
+            : [
+                typeof channelDefaultAccountId[id] === "string"
+                    ? channelDefaultAccountId[id]
+                    : "default",
+            ];
+        const summary = asRecord(channels[id]);
+        // OpenClaw's channels.status reports `running`; older gateways used `connected`. Treat either as live.
+        const summaryConnected = summary && typeof summary.connected === "boolean"
+            ? summary.connected
+            : summary?.running === true;
+        const anyAccountLive = accountList.some((a) => (typeof a.connected === "boolean" && a.connected) || a.running === true);
+        const connected = summaryConnected || anyAccountLive;
+        // Bindable while offline: a configured+enabled channel still gets an IDE route so flaky
+        // providers (e.g. Telegram polling) route correctly once they reconnect. Older gateways
+        // omit `configured`/`enabled`, so fall back to live state.
+        const enabled = summary?.configured === true ||
+            accountList.some((a) => a.configured === true && a.enabled !== false) ||
+            connected;
+        rows.push({
+            id,
+            label,
+            connected,
+            enabled,
+            accounts: accountIds,
+        });
+    }
+    return rows;
+}
+function channelDefaultAccountMapFromStatus(statusPayload) {
+    const root = asRecord(statusPayload);
+    if (!root) {
+        return {};
+    }
+    const channelDefaultAccountId = asRecord(root.channelDefaultAccountId) ?? {};
+    const out = {};
+    for (const [ch, v] of Object.entries(channelDefaultAccountId)) {
+        if (typeof v === "string" && v.trim()) {
+            out[ch] = v.trim();
+        }
+    }
+    return out;
+}
+function isChannelWideRouteBindingForAgent(binding, agentIdNormalized) {
+    if (!binding || typeof binding !== "object" || Array.isArray(binding)) {
+        return false;
+    }
+    const b = binding;
+    if (b.type === "acp") {
+        return false;
+    }
+    if (String(b.agentId ?? "")
+        .trim()
+        .toLowerCase() !== agentIdNormalized) {
+        return false;
+    }
+    const m = b.match;
+    if (!m || typeof m !== "object") {
+        return false;
+    }
+    if (m.peer) {
+        return false;
+    }
+    return typeof m.channel === "string" && m.channel.trim().length > 0;
+}
+function normalizeRouteBindingAccountId(raw) {
+    if (typeof raw !== "string" || !raw.trim()) {
+        return "default";
+    }
+    return raw.trim().toLowerCase();
+}
+/** Parse `serve --bind` / hippoclaw `--bind` specs: `slack`, `slack:default`, `telegram,whatsapp`. */
+function parseChannelBindSpecs(bindSpec) {
+    return bindSpec
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean)
+        .map((spec) => {
+        const colon = spec.indexOf(":");
+        if (colon === -1) {
+            return { channelId: spec };
+        }
+        const channelId = spec.slice(0, colon).trim();
+        const accountId = spec.slice(colon + 1).trim();
+        return accountId ? { channelId, accountId } : { channelId: spec };
+    });
+}
+function bindingChannelId(binding) {
+    if (!binding || typeof binding !== "object" || Array.isArray(binding)) {
+        return undefined;
+    }
+    const ch = binding.match?.channel;
+    return typeof ch === "string" && ch.trim() ? ch.trim() : undefined;
+}
+/** Drop legacy malformed bindings where account was folded into channel (e.g. `slack:default`). */
+function isMalformedChannelBinding(binding) {
+    const ch = bindingChannelId(binding);
+    return Boolean(ch && ch.includes(":"));
+}
+/** Channel-wide route (no peer): same slot as Meet Agent at / `serve --bind`. */
+function isChannelWideRouteBindingForChannelAccount(binding, channelId, accountId) {
+    if (!binding || typeof binding !== "object" || Array.isArray(binding)) {
+        return false;
+    }
+    const b = binding;
+    if (b.type === "acp") {
+        return false;
+    }
+    const routeType = String(b.type ?? "route").toLowerCase();
+    if (routeType !== "route") {
+        return false;
+    }
+    const m = b.match;
+    if (!m || typeof m !== "object") {
+        return false;
+    }
+    if (m.peer) {
+        return false;
+    }
+    const ch = typeof m.channel === "string" ? m.channel.trim().toLowerCase() : "";
+    const acc = normalizeRouteBindingAccountId(m.accountId);
+    return (ch === channelId.trim().toLowerCase() &&
+        acc === accountId.trim().toLowerCase());
+}
+function mergeBindingsForAgentChannels(params) {
+    const norm = params.agentId.trim().toLowerCase();
+    const resolveAccountId = (channelId) => params.channelAccountOverrides?.[channelId]
+        ?? params.channelDefaultAccountId[channelId]
+        ?? "default";
+    const kept = params.existingBindings.filter((b) => {
+        if (isMalformedChannelBinding(b)) {
+            return false;
+        }
+        if (isChannelWideRouteBindingForAgent(b, norm)) {
+            return false;
+        }
+        for (const channelId of params.selectedChannelIds) {
+            const accountId = resolveAccountId(channelId);
+            if (isChannelWideRouteBindingForChannelAccount(b, channelId, accountId)) {
+                return false;
+            }
+        }
+        return true;
+    });
+    const added = params.selectedChannelIds.map((channelId) => {
+        const accountId = resolveAccountId(channelId);
+        return {
+            type: "route",
+            agentId: params.agentId.trim(),
+            match: { channel: channelId, accountId },
+        };
+    });
+    return [...kept, ...added];
+}
+/**
+ * Replace channel-wide route bindings for `agentId` with one route per selected channel,
+ * preserving other bindings (other agents, ACP, peer-specific rules).
+ * Also drops **other** agents' channel-wide routes for the same channel + default account
+ * so `serve --bind telegram` wins the slot (OpenClaw uses the first matching route).
+ */
+async function applyAgentChannelBindingsViaConfigPatch(request, params) {
+    const statusPayload = params.statusPayload ??
+        (await request("channels.status", CHANNELS_STATUS_PARAMS));
+    const defaultAccounts = channelDefaultAccountMapFromStatus(statusPayload);
+    const snap = await request("config.get", {});
+    const baseHash = typeof snap.hash === "string" ? snap.hash.trim() : "";
+    if (!baseHash) {
+        throw new Error("config.get did not return hash; cannot config.patch bindings");
+    }
+    const existing = Array.isArray(snap.config?.bindings) ? snap.config.bindings : [];
+    const nextBindings = mergeBindingsForAgentChannels({
+        existingBindings: existing,
+        agentId: params.agentId,
+        selectedChannelIds: params.selectedChannelIds,
+        channelDefaultAccountId: defaultAccounts,
+        channelAccountOverrides: params.channelAccountOverrides,
+    });
+    if (JSON.stringify(existing) === JSON.stringify(nextBindings)) {
+        return false;
+    }
+    await request("config.patch", {
+        baseHash,
+        raw: JSON.stringify({ bindings: nextBindings }),
+    });
+    return true;
+}
+/**
+ * Fetch channels for Meet Agent UI or CLI `--bind '*'`.
+ */
+async function fetchMeetAgentChannelRows(request) {
+    const { rows } = await fetchMeetAgentChannelContext(request);
+    return rows;
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Poll `channels.status` until the given channels report connected (live), or the timeout elapses.
+ *
+ * Used after a binding `config.patch` to avoid reporting publish success while the gateway is still
+ * (re)starting the affected channel: a Slack/Telegram message arriving in that window is dropped or
+ * routed to the gateway's embedded agent instead of the freshly-bound IDE agent.
+ *
+ * Best-effort — returns `timedOut: true` rather than throwing so the publish flow never hangs. A
+ * failed `channels.status` poll is treated as "not yet connected" and retried until the deadline.
+ */
+async function waitForChannelsLive(request, channelIds, options = {}) {
+    const targets = [
+        ...new Set(channelIds.map((id) => id.trim().toLowerCase()).filter(Boolean)),
+    ];
+    if (targets.length === 0) {
+        return { ready: true, live: [], pending: [], polls: 0, timedOut: false };
+    }
+    const timeoutMs = options.timeoutMs ?? 8000;
+    const intervalMs = options.intervalMs ?? 400;
+    const sleep = options.sleep ?? defaultSleep;
+    const now = options.now ?? Date.now;
+    const start = now();
+    let polls = 0;
+    let live = [];
+    let pending = [...targets];
+    for (;;) {
+        polls++;
+        let rows;
+        try {
+            const statusPayload = await request("channels.status", CHANNELS_STATUS_PARAMS);
+            rows = mapChannelsStatusToMeetAgentRows(statusPayload);
+        }
+        catch {
+            rows = [];
+        }
+        const connected = new Set(rows.filter((r) => r.connected).map((r) => r.id.trim().toLowerCase()));
+        live = targets.filter((id) => connected.has(id));
+        pending = targets.filter((id) => !connected.has(id));
+        if (pending.length === 0) {
+            return { ready: true, live, pending, polls, timedOut: false };
+        }
+        if (now() - start >= timeoutMs) {
+            return { ready: false, live, pending, polls, timedOut: true };
+        }
+        await sleep(intervalMs);
+    }
+}
+/**
+ * Channels to bind when publishing a chat to the gateway.
+ * Peer publish binds only `preferredChannel`; default publish binds every enabled channel
+ * so new Telegram/Slack threads route to the IDE agent (not only channels already in config).
+ *
+ * Default publish keys off `enabled` (configured + not disabled) rather than `connected`: a flaky
+ * provider that is momentarily offline at publish time (e.g. Telegram long-polling stalled) must
+ * still get an IDE route, otherwise its messages fall through to the gateway's embedded agent.
+ */
+function resolvePublishedGatewayChannelIds(rows, preferredChannel) {
+    const preferred = preferredChannel?.trim();
+    if (preferred) {
+        return rows
+            .filter((row) => row.id.toLowerCase() === preferred.toLowerCase())
+            .map((row) => row.id);
+    }
+    return rows.filter((row) => row.enabled).map((row) => row.id);
+}

package/out/gateway/outboundHandles.js

@@ -0,0 +1,373 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) AgentHippo.ai. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._resetOutboundHandleStoreLockForTest = _resetOutboundHandleStoreLockForTest;
+exports._setOutboundHandleStorePathForTest = _setOutboundHandleStorePathForTest;
+exports.buildGatewayOutboundHandleKey = buildGatewayOutboundHandleKey;
+exports.upsertGatewayOutboundHandle = upsertGatewayOutboundHandle;
+exports.getLastGatewayOutboundHandle = getLastGatewayOutboundHandle;
+exports.listGatewayOutboundTargets = listGatewayOutboundTargets;
+exports.mergeGatewayOutboundHandles = mergeGatewayOutboundHandles;
+exports.resolveGatewayOutboundHandle = resolveGatewayOutboundHandle;
+exports.backupAndClearOutboundHandlesForAgent = backupAndClearOutboundHandlesForAgent;
+exports.getGatewayOutboundStoreSnapshot = getGatewayOutboundStoreSnapshot;
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const gatewayBackup_js_1 = require("./gatewayBackup.js");
+const STORE_VERSION = 1;
+const storePathOverride = { value: undefined };
+const storeCache = new Map();
+const storeMutationQueues = new Map();
+function withStoreMutationLock(storePath, fn) {
+    const prev = storeMutationQueues.get(storePath) ?? Promise.resolve();
+    const run = prev.then(() => fn());
+    storeMutationQueues.set(storePath, run.catch(() => undefined));
+    return run;
+}
+/** @internal Test hook */
+function _resetOutboundHandleStoreLockForTest() {
+    storeMutationQueues.clear();
+    storeCache.clear();
+}
+/** @internal Test hook */
+function _setOutboundHandleStorePathForTest(filePath) {
+    storePathOverride.value = filePath;
+    storeCache.clear();
+}
+function resolveStorePath(storePath) {
+    return storePathOverride.value ?? storePath;
+}
+/** Stable key for a route within an agent's target list. */
+function buildGatewayOutboundHandleKey(target, threadId) {
+    const tid = threadId?.trim();
+    return tid ? `${target}::thread:${tid}` : `${target}::`;
+}
+function emptyStore() {
+    return { version: STORE_VERSION, lastByAgent: {}, targetsByAgent: {} };
+}
+async function loadStore(storePath) {
+    const filePath = resolveStorePath(storePath);
+    const cached = storeCache.get(filePath);
+    if (cached) {
+        return cached;
+    }
+    try {
+        const raw = await fs_1.promises.readFile(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed.targetsByAgent && typeof parsed.targetsByAgent === 'object') {
+            const store = {
+                version: parsed.version ?? STORE_VERSION,
+                lastByAgent: parsed.lastByAgent ?? {},
+                targetsByAgent: parsed.targetsByAgent,
+            };
+            storeCache.set(filePath, store);
+            return store;
+        }
+    }
+    catch {
+        // Missing or invalid file — start fresh.
+    }
+    const store = emptyStore();
+    storeCache.set(filePath, store);
+    return store;
+}
+async function saveStore(storePath, store) {
+    const filePath = resolveStorePath(storePath);
+    await fs_1.promises.mkdir(path.dirname(filePath), { recursive: true });
+    const payload = {
+        version: STORE_VERSION,
+        lastByAgent: store.lastByAgent,
+        targetsByAgent: store.targetsByAgent,
+    };
+    const tmp = `${filePath}.tmp`;
+    await fs_1.promises.writeFile(tmp, JSON.stringify(payload, null, 2), 'utf-8');
+    await fs_1.promises.rename(tmp, filePath);
+    storeCache.set(filePath, store);
+}
+function normalizeSlackTarget(target, channel) {
+    if (channel?.toLowerCase() !== 'slack') {
+        return target;
+    }
+    const match = target.match(/^(user|channel|group):(.+)$/i);
+    if (!match) {
+        return target;
+    }
+    return `${match[1].toLowerCase()}:${match[2].toUpperCase()}`;
+}
+function targetsEquivalent(storedTarget, explicitTarget, channel) {
+    const normalizedStored = normalizeSlackTarget(storedTarget, channel);
+    const normalizedExplicit = normalizeSlackTarget(explicitTarget, channel);
+    return normalizedStored.toLowerCase() === normalizedExplicit.toLowerCase();
+}
+function findMatchingHandle(handles, explicitTarget, explicitThreadId) {
+    if (explicitThreadId) {
+        return handles.find(h => targetsEquivalent(h.target, explicitTarget, h.channel) &&
+            h.threadId?.trim() === explicitThreadId);
+    }
+    const matches = handles.filter(h => targetsEquivalent(h.target, explicitTarget, h.channel));
+    if (matches.length === 0) {
+        return undefined;
+    }
+    const nonThreaded = matches.find(h => !h.threadId?.trim());
+    return nonThreaded ?? sortHandlesByRecency(matches)[0];
+}
+function inferTargetFromSessionKey(sessionKey, channel) {
+    const threadMatch = sessionKey.match(/:thread:([^:]+)$/);
+    const base = threadMatch ? sessionKey.slice(0, -threadMatch[0].length) : sessionKey;
+    const directMatch = base.match(/:direct:([^:]+)$/);
+    if (directMatch) {
+        return normalizeSlackTarget(`user:${directMatch[1]}`, channel);
+    }
+    const dmMatch = base.match(/:dm:([^:]+)$/);
+    if (dmMatch) {
+        return normalizeSlackTarget(`user:${dmMatch[1]}`, channel);
+    }
+    const channelMatch = base.match(/:channel:([^:]+)$/);
+    if (channelMatch) {
+        return normalizeSlackTarget(`channel:${channelMatch[1]}`, channel);
+    }
+    const groupMatch = base.match(/:group:([^:]+)$/);
+    if (groupMatch) {
+        return normalizeSlackTarget(`channel:${groupMatch[1]}`, channel);
+    }
+    return undefined;
+}
+function inferTargetFromParams(params) {
+    const explicit = params.target?.trim();
+    if (explicit) {
+        return normalizeSlackTarget(explicit, params.channel);
+    }
+    const sessionKey = params.sessionKey?.trim().toLowerCase();
+    if (sessionKey) {
+        // Channel/group sessions should reply to the channel, not the sender DM.
+        const fromSession = inferTargetFromSessionKey(sessionKey, params.channel);
+        if (fromSession) {
+            return fromSession;
+        }
+    }
+    const senderId = params.senderId?.trim();
+    if (senderId && params.channel) {
+        return normalizeSlackTarget(`user:${senderId}`, params.channel);
+    }
+    return undefined;
+}
+function buildLabel(params) {
+    if (params.senderName?.trim()) {
+        return params.senderName.trim();
+    }
+    if (params.senderUsername?.trim()) {
+        return params.senderUsername.trim();
+    }
+    return params.target?.trim() || params.senderId?.trim();
+}
+function sortHandlesByRecency(handles) {
+    return [...handles].sort((a, b) => b.lastSeenAt - a.lastSeenAt);
+}
+/** Match store keys when legacy IDE code persisted `Default` but CLI/env use `default`. */
+function resolveStoreAgentKey(store, agentId) {
+    const id = agentId.trim();
+    if (!id) {
+        return id;
+    }
+    if (store.lastByAgent[id] || store.targetsByAgent[id]) {
+        return id;
+    }
+    if (id.toLowerCase() === 'default') {
+        for (const alias of ['default', 'Default']) {
+            if (store.lastByAgent[alias] || store.targetsByAgent[alias]) {
+                return alias;
+            }
+        }
+    }
+    return id;
+}
+/**
+ * Persist outbound route for proactive gateway sends into a session-scoped JSON file.
+ * Routes are keyed by pack id (`agentId` param); optional `gatewayAgentId` is stored on the handle.
+ */
+async function upsertGatewayOutboundHandle(storePath, agentId, params, runId, options) {
+    const storeAgentId = agentId.trim();
+    if (!storeAgentId) {
+        return undefined;
+    }
+    const gatewayAgentId = options?.gatewayAgentId?.trim() || undefined;
+    let channel = params.channel?.trim();
+    const sessionKey = params.sessionKey?.trim().toLowerCase();
+    if (!channel && sessionKey) {
+        const match = sessionKey.match(/^agent:[^:]+:([a-z0-9_-]+):/);
+        if (match) {
+            channel = match[1];
+        }
+    }
+    const target = inferTargetFromParams(params);
+    if (!channel || !target) {
+        return undefined;
+    }
+    return withStoreMutationLock(resolveStorePath(storePath), async () => {
+        const now = Date.now();
+        const store = await loadStore(storePath);
+        if (!store.targetsByAgent[storeAgentId]) {
+            store.targetsByAgent[storeAgentId] = {};
+        }
+        const routeKey = buildGatewayOutboundHandleKey(target, params.threadId?.trim());
+        const existing = store.targetsByAgent[storeAgentId][routeKey];
+        const handle = {
+            agentId: storeAgentId,
+            ...(gatewayAgentId ? { gatewayAgentId } : {}),
+            channel,
+            accountId: params.accountId?.trim() || undefined,
+            target,
+            threadId: params.threadId?.trim() || undefined,
+            sessionKey: params.sessionKey?.trim() || undefined,
+            sessionId: params.sessionId?.trim() || undefined,
+            senderId: params.senderId?.trim() || undefined,
+            senderName: params.senderName?.trim() || undefined,
+            senderUsername: params.senderUsername?.trim() || undefined,
+            label: buildLabel(params),
+            firstSeenAt: existing?.firstSeenAt ?? now,
+            lastSeenAt: now,
+            lastInboundRunId: runId,
+            inboundCount: (existing?.inboundCount ?? 0) + 1,
+        };
+        store.targetsByAgent[storeAgentId][routeKey] = handle;
+        store.lastByAgent[storeAgentId] = handle;
+        await saveStore(storePath, store);
+        return handle;
+    });
+}
+async function getLastGatewayOutboundHandle(storePath, agentId) {
+    const store = await loadStore(storePath);
+    const storeKey = resolveStoreAgentKey(store, agentId);
+    return store.lastByAgent[storeKey];
+}
+async function listGatewayOutboundTargets(storePath, agentId) {
+    const store = await loadStore(storePath);
+    if (agentId?.trim()) {
+        const id = resolveStoreAgentKey(store, agentId.trim());
+        return sortHandlesByRecency(Object.values(store.targetsByAgent[id] ?? {}));
+    }
+    const all = [];
+    for (const handles of Object.values(store.targetsByAgent)) {
+        all.push(...Object.values(handles));
+    }
+    return sortHandlesByRecency(all);
+}
+async function mergeGatewayOutboundHandles(sourceStorePath, targetStorePath, agentId) {
+    const source = await loadStore(sourceStorePath);
+    const sourceAgentIds = agentId?.trim()
+        ? [agentId.trim()]
+        : [...new Set([...Object.keys(source.targetsByAgent), ...Object.keys(source.lastByAgent)])];
+    if (sourceAgentIds.length === 0) {
+        return 0;
+    }
+    return withStoreMutationLock(resolveStorePath(targetStorePath), async () => {
+        const target = await loadStore(targetStorePath);
+        let merged = 0;
+        let changed = false;
+        for (const sourceAgentId of sourceAgentIds) {
+            const routes = source.targetsByAgent[sourceAgentId] ?? {};
+            const routeEntries = Object.entries(routes);
+            if (routeEntries.length > 0 && !target.targetsByAgent[sourceAgentId]) {
+                target.targetsByAgent[sourceAgentId] = {};
+            }
+            for (const [routeKey, handle] of routeEntries) {
+                const existing = target.targetsByAgent[sourceAgentId]?.[routeKey];
+                if (!existing || handle.lastSeenAt >= existing.lastSeenAt) {
+                    target.targetsByAgent[sourceAgentId][routeKey] = handle;
+                    merged++;
+                    changed = true;
+                }
+            }
+            const sourceLast = source.lastByAgent[sourceAgentId];
+            if (sourceLast) {
+                const targetLast = target.lastByAgent[sourceAgentId];
+                if (!targetLast || sourceLast.lastSeenAt >= targetLast.lastSeenAt) {
+                    target.lastByAgent[sourceAgentId] = sourceLast;
+                    changed = true;
+                }
+            }
+        }
+        if (changed) {
+            await saveStore(targetStorePath, target);
+        }
+        return merged;
+    });
+}
+async function resolveGatewayOutboundHandle(storePath, agentId, options) {
+    const store = await loadStore(storePath);
+    const storeKey = resolveStoreAgentKey(store, agentId);
+    const explicitTarget = options?.target?.trim();
+    if (explicitTarget) {
+        const handles = Object.values(store.targetsByAgent[storeKey] ?? {});
+        return findMatchingHandle(handles, explicitTarget, options?.threadId?.trim());
+    }
+    return store.lastByAgent[storeKey];
+}
+/**
+ * Back up the per-session outbound store to a `.bk` sibling, then rewrite it with this agent's
+ * handles removed (other agents in the same file preserved). Runs under the store mutation lock
+ * and refreshes the in-memory `storeCache` (via `saveStore`) so a later save can't resurrect the
+ * cleared handles. No-op when the agent has no entries in this store.
+ */
+async function backupAndClearOutboundHandlesForAgent(storePath, agentId, ts = (0, gatewayBackup_js_1.backupTimestamp)()) {
+    const filePath = resolveStorePath(storePath);
+    return withStoreMutationLock(filePath, async () => {
+        const store = await loadStore(storePath);
+        const storeKey = resolveStoreAgentKey(store, agentId);
+        const targets = store.targetsByAgent[storeKey];
+        const hasLast = Object.prototype.hasOwnProperty.call(store.lastByAgent, storeKey);
+        const removed = targets ? Object.keys(targets).length : 0;
+        if (removed === 0 && !hasLast) {
+            return { removed: 0 };
+        }
+        // Snapshot the current file before rewriting the pruned store.
+        const backupPath = await (0, gatewayBackup_js_1.renameToBackup)(filePath, ts);
+        delete store.targetsByAgent[storeKey];
+        delete store.lastByAgent[storeKey];
+        await saveStore(storePath, store);
+        return { removed, backupPath };
+    });
+}
+async function getGatewayOutboundStoreSnapshot(storePath) {
+    const store = await loadStore(storePath);
+    const targetsByAgent = {};
+    for (const [agentId, routes] of Object.entries(store.targetsByAgent)) {
+        targetsByAgent[agentId] = sortHandlesByRecency(Object.values(routes));
+    }
+    return { lastByAgent: store.lastByAgent, targetsByAgent };
+}