@amaster.ai/pi-channels 0.1.2-beta.2 → 0.1.2-beta.21

package/dist/index.js

@@ -1,14 +1,44 @@
 import { Type } from 'typebox';
 import { ChatBridge } from './bridge.js';
-import { loadChannelConfig } from './config.js';
+import { loadChannelConfig, updateLocalChannelConfig } from './config.js';
 import { ChannelRegistry } from './registry.js';
+const RECONNECT_DELAYS_MS = [1_000, 3_000, 10_000];
+const RECONNECT_STABLE_RESET_MS = 60_000;
 function enumSchema(values, description) {
     return Type.Union(values.map((value) => Type.Literal(value)), { description });
 }
 export default function piChannelsExtension(pi) {
     const registry = new ChannelRegistry();
     let bridge = null;
+    let sessionCwd = process.cwd();
+    let currentCtx = null;
+    let configFingerprint = '';
+    let configReloading = false;
+    let connectedAt;
+    let lastError;
+    let adapterStates = {};
+    let reconnectAttempts = 0;
+    let reconnectTimer;
+    let reconnectResetTimer;
+    const captureWaiters = new Set();
     const log = (event, data, level = 'INFO') => {
+        if (event === 'wecom-server-disconnected' || event === 'wecom-client-error') {
+            const error = typeof data?.error === 'string' ? data.error : event;
+            const adapter = typeof data?.adapter === 'string' ? data.adapter : undefined;
+            lastError = error;
+            connectedAt = undefined;
+            if (adapter) {
+                adapterStates = {
+                    ...adapterStates,
+                    [adapter]: {
+                        state: 'error',
+                        updatedAt: new Date().toISOString(),
+                        error,
+                    },
+                };
+            }
+            scheduleReconnect(event, error);
+        }
         if (level === 'ERROR')
             console.error('[pi-channels]', event, data ?? {});
         else
@@ -17,32 +47,110 @@ export default function piChannelsExtension(pi) {
     registry.setLogger(log);
     registry.setOnIncoming(async (message) => {
         pi.events.emit('channel:receive', message);
+        const captured = notifyCaptureWaiters(message);
+        autoFillEmptyRouteRecipient(sessionCwd, message, log);
+        if (captured)
+            return;
+        const turn = bridge?.isActive() ? channelIncomingTurn(message) : undefined;
+        if (turn)
+            pi.events.emit('channel:turn', turn);
         if (bridge?.isActive())
             await bridge.handleMessage(message);
     });
+    async function applyChannelConfig(ctx, reason, force = false) {
+        if (configReloading)
+            return registry.getErrors();
+        configReloading = true;
+        try {
+            sessionCwd = ctx.cwd;
+            const config = loadChannelConfig(ctx.cwd);
+            const nextFingerprint = JSON.stringify(config);
+            if (!force && nextFingerprint === configFingerprint && !lastError)
+                return registry.getErrors();
+            configFingerprint = nextFingerprint;
+            adapterStates = Object.fromEntries(Object.keys(config.adapters ?? {}).map((adapter) => [
+                adapter,
+                {
+                    state: 'connecting',
+                    updatedAt: new Date().toISOString(),
+                },
+            ]));
+            bridge?.stop();
+            bridge = null;
+            await registry.loadConfig(config, ctx.cwd);
+            log(reason === 'session_start' ? 'session_start' : 'config_reload', {
+                reason,
+                cwd: ctx.cwd,
+                adapters: Object.keys(config.adapters ?? {}),
+                routes: Object.keys(config.routes ?? {}),
+                registry: registry.list(),
+            });
+            bridge = new ChatBridge(config.bridge, ctx.cwd, registry);
+            if (config.bridge?.enabled) {
+                await registry.startListening();
+                bridge.start();
+            }
+            const errors = registry.getErrors();
+            lastError = errors.map((item) => `${item.adapter}: ${item.error}`).join('; ') || undefined;
+            connectedAt = errors.length === 0 ? new Date().toISOString() : undefined;
+            adapterStates = adapterStatesForRegistry(config, errors, connectedAt);
+            if (errors.length === 0)
+                scheduleReconnectAttemptReset();
+            for (const error of errors) {
+                ctx.ui.notify(`pi-channels: ${error.adapter}: ${error.error}`, 'warning');
+            }
+            ctx.ui.setStatus?.('pi-channels', `channels: ${registry.list().filter((item) => item.type === 'adapter').length}`);
+            return errors;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+            connectedAt = undefined;
+            throw error;
+        }
+        finally {
+            configReloading = false;
+        }
+    }
     pi.on('session_start', async (_event, ctx) => {
-        const config = loadChannelConfig(ctx.cwd);
-        await registry.loadConfig(config, ctx.cwd);
-        await registry.startListening();
-        bridge = new ChatBridge(config.bridge, ctx.cwd, registry);
-        if (config.bridge?.enabled)
-            bridge.start();
-        const errors = registry.getErrors();
-        for (const error of errors) {
-            ctx.ui.notify(`pi-channels: ${error.adapter}: ${error.error}`, 'warning');
+        if (sessionAutostartDisabled()) {
+            sessionCwd = ctx.cwd;
+            log('session_start_skipped', {
+                reason: 'PI_CHANNELS_DISABLE_SESSION_AUTOSTART',
+                cwd: ctx.cwd,
+            });
+            return;
         }
-        ctx.ui.setStatus?.('pi-channels', `channels: ${registry.list().filter((item) => item.type === 'adapter').length}`);
+        currentCtx = ctx;
+        sessionCwd = ctx.cwd;
+        await applyChannelConfig(ctx, 'session_start', false);
     });
     pi.on('session_shutdown', async (_event, ctx) => {
+        currentCtx = null;
+        connectedAt = undefined;
+        lastError = undefined;
+        clearReconnectTimers();
+        adapterStates = Object.fromEntries(Object.keys(adapterStates).map((adapter) => [
+            adapter,
+            {
+                state: 'disconnected',
+                updatedAt: new Date().toISOString(),
+            },
+        ]));
+        rejectCaptureWaiters('pi-channels session is shutting down.');
         bridge?.stop();
         bridge = null;
         await registry.stopAll();
         ctx.ui.setStatus?.('pi-channels', undefined);
     });
     pi.registerCommand('channel', {
-        description: 'Manage pi channels: /channel [list|bridge on|bridge off|bridge status]',
+        description: 'Manage pi channels: /channel [list|reload|bridge on|bridge off|bridge status]',
         handler: async (args, ctx) => {
             const tokens = (args ?? '').trim().split(/\s+/).filter(Boolean);
+            if (tokens[0] === 'reload') {
+                await applyChannelConfig(ctx, 'command', true);
+                ctx.ui.notify('pi-channels config reloaded.', 'info');
+                return;
+            }
             if (tokens[0] === 'bridge') {
                 if (!bridge) {
                     ctx.ui.notify('pi-channels bridge is not initialized.', 'warning');
@@ -71,7 +179,7 @@ export default function piChannelsExtension(pi) {
             ctx.ui.notify(items.length
                 ? items
                     .map((item) => item.type === 'route'
-                    ? `${item.name} route -> ${item.target}`
+                    ? `${item.name}${item.label ? ` (${item.label})` : ''} route -> ${item.target}`
                     : `${item.name} adapter (${item.direction})`)
                     .join('\n')
                 : 'No channels configured.', 'info');
@@ -80,9 +188,9 @@ export default function piChannelsExtension(pi) {
     pi.registerTool({
         name: 'notify',
         label: 'Channel',
-        description: 'Send messages through configured pi channels. Supports native Feishu, WeCom, and webhooks.',
+        description: 'Send messages through configured pi channels. Supports native Feishu, DingTalk, WeCom, and webhooks. Use configured adapter names or route aliases. A chat mention such as @local:channels_dingtalk:ops means route alias "ops" on the DingTalk adapter; @local:channels alone selects the plugin, not a send target.',
         parameters: Type.Object({
-            action: enumSchema(['send', 'list', 'test'], 'Action to perform'),
+            action: enumSchema(['send', 'list', 'list-adapters', 'list-routes', 'test'], 'Action to perform'),
             adapter: Type.Optional(Type.String({ description: 'Adapter name or route alias.' })),
             recipient: Type.Optional(Type.String({ description: 'Recipient id. Optional for routes.' })),
             text: Type.Optional(Type.String({ description: 'Text to send.' })),
@@ -94,19 +202,28 @@ export default function piChannelsExtension(pi) {
         }),
         async execute(_toolCallId, rawParams) {
             const params = rawParams;
-            if (params.action === 'list') {
+            if (params.action === 'list' ||
+                params.action === 'list-adapters' ||
+                params.action === 'list-routes') {
                 const items = registry.list();
+                const filteredItems = items.filter((item) => {
+                    if (params.action === 'list-adapters')
+                        return item.type === 'adapter';
+                    if (params.action === 'list-routes')
+                        return item.type === 'route';
+                    return true;
+                });
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: items.length
-                                ? items
+                            text: filteredItems.length
+                                ? filteredItems
                                     .map((item) => item.type === 'route'
-                                    ? `- ${item.name} route -> ${item.target}`
+                                    ? `- ${item.name}${item.label ? ` (${item.label})` : ''} route -> ${item.target}`
                                     : `- ${item.name} adapter (${item.direction})`)
                                     .join('\n')
-                                : 'No channels configured.',
+                                : emptyListMessage(params.action),
                         },
                     ],
                     details: undefined,
@@ -114,6 +231,9 @@ export default function piChannelsExtension(pi) {
             }
             if (!params.adapter)
                 return textToolResult('Missing required field: adapter.');
+            const adapterName = normalizeAdapterName(params.adapter, params.recipient, registry.list());
+            if (!adapterName.ok)
+                return textToolResult(adapterName.error);
             let rawBody;
             if (params.json) {
                 try {
@@ -130,8 +250,8 @@ export default function piChannelsExtension(pi) {
                 webhook.contentType = params.contentType;
             const text = params.action === 'test' ? `pi-channels test: ${new Date().toISOString()}` : params.text;
             const message = {
-                adapter: params.adapter,
-                recipient: params.recipient ?? '',
+                adapter: adapterName.value,
+                recipient: adapterName.recipient ?? params.recipient ?? '',
                 payloadMode: params.payloadMode ?? (params.json ? 'raw' : 'envelope'),
                 ...(Object.keys(webhook).length > 0 ? { webhook } : {}),
             };
@@ -145,14 +265,31 @@ export default function piChannelsExtension(pi) {
                 message.rawBody = rawBody;
             const result = await registry.send(message);
             return textToolResult(result.ok
-                ? `Sent via "${params.adapter}"${params.recipient ? ` to ${params.recipient}` : ''}.`
+                ? `Sent via "${adapterName.value}"${params.recipient ? ` to ${params.recipient}` : ''}.`
                 : `Failed: ${result.error}`);
         },
     });
     pi.events.on('channel:send', (raw) => {
         const data = raw;
-        const { callback, ...message } = data;
-        registry.send(message).then((result) => callback?.(result));
+        const { callback, config, cwd, ...message } = data;
+        void ensureSendAdapter(message, config, cwd)
+            .then((ensureResult) => (ensureResult.ok ? registry.send(message) : ensureResult))
+            .then((result) => callback?.(result))
+            .catch((error) => callback?.({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+    });
+    pi.events.on('channel:ensure-listening', (raw) => {
+        const data = raw;
+        const adapter = typeof data.adapter === 'string' ? data.adapter.trim() : '';
+        if (!adapter) {
+            data.callback?.({ ok: false, error: 'adapter is required' });
+            return;
+        }
+        void ensureListeningAdapter(adapter, data.config, typeof data.cwd === 'string' ? data.cwd : undefined)
+            .then((result) => data.callback?.(result))
+            .catch((error) => data.callback?.({
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        }));
     });
     pi.events.on('channel:register', (raw) => {
         const data = raw;
@@ -171,6 +308,401 @@ export default function piChannelsExtension(pi) {
         const data = raw;
         data.callback?.(registry.list());
     });
+    pi.events.on('channel:status', (raw) => {
+        const data = raw;
+        const errors = registry.getErrors();
+        const error = errors.map((item) => `${item.adapter}: ${item.error}`).join('; ') || lastError;
+        data.callback?.({
+            ok: Boolean(currentCtx) && errors.length === 0 && !lastError,
+            active: Boolean(currentCtx),
+            ...(currentCtx ? { cwd: sessionCwd } : {}),
+            ...(connectedAt ? { connectedAt } : {}),
+            ...(error ? { error } : {}),
+            errors,
+            items: registry.list(),
+            bridgeActive: Boolean(bridge?.isActive()),
+            adapterStates,
+        });
+    });
+    pi.events.on('channel:capture', (raw) => {
+        const data = raw;
+        if (!currentCtx) {
+            data.callback?.({ ok: false, error: 'pi-channels session is not active.' });
+            return;
+        }
+        const adapter = typeof data.adapter === 'string' ? data.adapter.trim() : '';
+        if (!adapter) {
+            data.callback?.({ ok: false, error: 'adapter is required' });
+            return;
+        }
+        const timeoutMs = typeof data.timeoutMs === 'number' && Number.isFinite(data.timeoutMs)
+            ? Math.max(5_000, Math.min(120_000, Math.floor(data.timeoutMs)))
+            : 60_000;
+        const captureToken = typeof data.captureToken === 'string' && data.captureToken.trim()
+            ? data.captureToken.trim()
+            : undefined;
+        let waiter;
+        const cleanup = () => {
+            clearTimeout(waiter.timer);
+            captureWaiters.delete(waiter);
+        };
+        waiter = {
+            adapter,
+            ...(captureToken ? { captureToken } : {}),
+            callback: (result) => {
+                cleanup();
+                data.callback?.(result);
+            },
+            timer: setTimeout(() => {
+                cleanup();
+                data.callback?.({
+                    ok: false,
+                    error: `等待群消息超时，请在 ${Math.round(timeoutMs / 1000)} 秒内给机器人发送消息`,
+                });
+            }, timeoutMs),
+        };
+        captureWaiters.add(waiter);
+    });
+    pi.events.on('channel:reload', (raw) => {
+        const data = raw;
+        const ctx = currentCtx ?? channelContextFromReload(data);
+        if (!ctx) {
+            data.callback?.({ ok: false, error: 'pi-channels session is not active.' });
+            return;
+        }
+        currentCtx = ctx;
+        sessionCwd = ctx.cwd;
+        void applyChannelConfig(ctx, data.reason ?? 'event', data.force !== false)
+            .then((errors) => data.callback?.(errors.length > 0
+            ? {
+                ok: false,
+                error: errors.map((item) => `${item.adapter}: ${item.error}`).join('; '),
+            }
+            : { ok: true }))
+            .catch((error) => {
+            data.callback?.({
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        });
+    });
+    function notifyCaptureWaiters(message) {
+        let captured = false;
+        for (const waiter of [...captureWaiters]) {
+            if (waiter.adapter !== message.adapter)
+                continue;
+            if (waiter.captureToken && !message.text.includes(waiter.captureToken))
+                continue;
+            captured = true;
+            waiter.callback({ ok: true, message });
+        }
+        return captured;
+    }
+    async function ensureSendAdapter(message, config, cwd) {
+        if (!config)
+            return { ok: true };
+        sessionCwd = cwd?.trim() || sessionCwd;
+        registry.loadRoutes(config);
+        const resolved = registry.resolveTarget(message.adapter, message.recipient);
+        await registry.ensureAdapter(resolved.adapter, config, sessionCwd);
+        const error = registry.getErrors().find((item) => item.adapter === resolved.adapter);
+        if (error)
+            return { ok: false, error: error.error };
+        adapterStates = {
+            ...adapterStates,
+            [resolved.adapter]: {
+                state: 'connected',
+                updatedAt: new Date().toISOString(),
+                connectedAt: new Date().toISOString(),
+            },
+        };
+        return { ok: true };
+    }
+    async function ensureListeningAdapter(adapter, config, cwd) {
+        if (!config) {
+            const existing = registry.getAdapter(adapter);
+            if (!existing)
+                return { ok: false, error: `No adapter "${adapter}"` };
+            await registry.startListening(adapter);
+            return { ok: true };
+        }
+        sessionCwd = cwd?.trim() || sessionCwd;
+        registry.loadRoutes(config);
+        await registry.ensureAdapter(adapter, config, sessionCwd);
+        await registry.startListening(adapter);
+        const error = registry.getErrors().find((item) => item.adapter === adapter);
+        adapterStates = {
+            ...adapterStates,
+            [adapter]: error
+                ? {
+                    state: 'error',
+                    updatedAt: new Date().toISOString(),
+                    error: error.error,
+                }
+                : {
+                    state: 'connected',
+                    updatedAt: new Date().toISOString(),
+                    connectedAt: new Date().toISOString(),
+                },
+        };
+        return error ? { ok: false, error: error.error } : { ok: true };
+    }
+    function rejectCaptureWaiters(error) {
+        for (const waiter of [...captureWaiters]) {
+            waiter.callback({ ok: false, error });
+        }
+    }
+    function scheduleReconnect(event, error) {
+        const ctx = currentCtx;
+        if (!ctx || reconnectTimer)
+            return;
+        clearReconnectResetTimer();
+        const nextAttempt = reconnectAttempts + 1;
+        if (nextAttempt > RECONNECT_DELAYS_MS.length) {
+            log('channel_reconnect_exhausted', { event, error, attempts: reconnectAttempts }, 'WARN');
+            return;
+        }
+        reconnectAttempts = nextAttempt;
+        const delayMs = RECONNECT_DELAYS_MS[nextAttempt - 1] ?? RECONNECT_DELAYS_MS.at(-1);
+        log('channel_reconnect_scheduled', { event, error, attempt: nextAttempt, delayMs }, 'WARN');
+        reconnectTimer = setTimeout(() => {
+            reconnectTimer = undefined;
+            const activeCtx = currentCtx;
+            if (!activeCtx)
+                return;
+            void applyChannelConfig(activeCtx, 'reconnect', true).catch((reconnectError) => {
+                log('channel_reconnect_failed', {
+                    attempt: nextAttempt,
+                    error: reconnectError instanceof Error ? reconnectError.message : String(reconnectError),
+                }, 'ERROR');
+            });
+        }, delayMs);
+    }
+    function scheduleReconnectAttemptReset() {
+        clearReconnectResetTimer();
+        reconnectResetTimer = setTimeout(() => {
+            reconnectAttempts = 0;
+            reconnectResetTimer = undefined;
+        }, RECONNECT_STABLE_RESET_MS);
+    }
+    function clearReconnectTimers() {
+        if (reconnectTimer)
+            clearTimeout(reconnectTimer);
+        reconnectTimer = undefined;
+        clearReconnectResetTimer();
+    }
+    function clearReconnectResetTimer() {
+        if (reconnectResetTimer)
+            clearTimeout(reconnectResetTimer);
+        reconnectResetTimer = undefined;
+    }
+}
+function channelContextFromReload(data) {
+    const cwd = typeof data.cwd === 'string' && data.cwd.trim() ? data.cwd.trim() : '';
+    if (!cwd)
+        return null;
+    return {
+        cwd,
+        ui: {
+            notify: () => undefined,
+            setStatus: () => undefined,
+        },
+    };
+}
+function sessionAutostartDisabled() {
+    return /^(1|true|yes)$/i.test(process.env.PI_CHANNELS_DISABLE_SESSION_AUTOSTART ?? '');
+}
+function adapterStatesForRegistry(config, errors, connectedAt) {
+    const updatedAt = new Date().toISOString();
+    const errorsByAdapter = new Map(errors.map((error) => [error.adapter, error.error]));
+    return Object.fromEntries(Object.keys(config.adapters ?? {}).map((adapter) => {
+        const error = errorsByAdapter.get(adapter);
+        return [
+            adapter,
+            error
+                ? { state: 'error', updatedAt, error }
+                : {
+                    state: 'connected',
+                    updatedAt,
+                    ...(connectedAt ? { connectedAt } : {}),
+                },
+        ];
+    }));
+}
+function channelIncomingTurn(message) {
+    const text = message.text.trim();
+    if (!text)
+        return undefined;
+    const sessionId = recipientFromIncoming(message);
+    if (!sessionId)
+        return undefined;
+    return {
+        sessionId,
+        adapter: message.adapter,
+        recipient: sessionId,
+        userMessage: text,
+        title: displayNameFromIncoming(message) ?? sessionId,
+        createdAt: new Date().toISOString(),
+    };
+}
+function autoFillEmptyRouteRecipient(cwd, message, log) {
+    const recipient = recipientFromIncoming(message);
+    if (!recipient)
+        return;
+    const displayName = displayNameFromIncoming(message);
+    try {
+        let filledRoute;
+        const updated = updateLocalChannelConfig(cwd, (config) => {
+            const routes = config.routes ?? {};
+            const fillableRoutes = Object.entries(routes).filter(([, route]) => route.adapter === message.adapter && !trimToUndefined(route.recipient));
+            const captureRoutes = fillableRoutes.filter(([, route]) => route.capture === true);
+            const routesToFill = captureRoutes.length > 0 ? captureRoutes : fillableRoutes;
+            if (routesToFill.length !== 1)
+                return config;
+            const [routeName, route] = routesToFill[0];
+            filledRoute = routeName;
+            return {
+                ...config,
+                routes: {
+                    ...routes,
+                    [routeName]: {
+                        ...route,
+                        recipient,
+                        capture: false,
+                        ...(displayName && !trimToUndefined(route.name) ? { name: displayName } : {}),
+                    },
+                },
+            };
+        });
+        if (updated && filledRoute) {
+            log('route_recipient_auto_filled', {
+                route: filledRoute,
+                adapter: message.adapter,
+                recipient,
+            });
+        }
+    }
+    catch (error) {
+        log('route_recipient_auto_fill_failed', {
+            adapter: message.adapter,
+            error: error instanceof Error ? error.message : String(error),
+        }, 'ERROR');
+    }
+}
+function displayNameFromIncoming(message) {
+    const metadata = message.metadata ?? {};
+    return trimToUndefined(typeof metadata.chatName === 'string'
+        ? metadata.chatName
+        : typeof metadata.groupName === 'string'
+            ? metadata.groupName
+            : undefined);
+}
+function recipientFromIncoming(message) {
+    const metadata = message.metadata ?? {};
+    if (message.adapter === 'feishu') {
+        return trimToUndefined(typeof metadata.chatId === 'string' ? metadata.chatId : undefined);
+    }
+    if (message.adapter === 'wecom') {
+        return (firstStringMetadata(metadata, ['chatId', 'groupId', 'conversationId', 'roomId']) ??
+            trimToUndefined(message.sender.split(':')[0]));
+    }
+    return trimToUndefined(message.sender);
+}
+function trimToUndefined(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+function firstStringMetadata(metadata, keys) {
+    for (const key of keys) {
+        const value = metadata[key];
+        const trimmed = trimToUndefined(typeof value === 'string' ? value : undefined);
+        if (trimmed)
+            return trimmed;
+    }
+    return undefined;
+}
+function emptyListMessage(action) {
+    if (action === 'list-adapters')
+        return 'No channel adapters configured.';
+    if (action === 'list-routes')
+        return 'No channel routes configured.';
+    return 'No channels configured.';
+}
+function normalizeAdapterName(value, recipient, items) {
+    const trimmed = value.trim();
+    const trimmedRecipient = recipient?.trim();
+    const routeSelector = /^@?local:channels_([\w.-]+):([\w.-]+)$/.exec(trimmed);
+    if (routeSelector) {
+        const adapterName = routeSelector[1];
+        const routeName = routeSelector[2];
+        return normalizeProviderRoute(adapterName, routeName, items);
+    }
+    const splitRouteSelector = /^@?local:channels_([\w.-]+)$/.exec(trimmed);
+    if (splitRouteSelector) {
+        const adapterName = splitRouteSelector[1];
+        if (!trimmedRecipient) {
+            return {
+                ok: false,
+                error: `Channel route mentions must include a route, for example @local:channels_${adapterName}:ops.`,
+            };
+        }
+        return normalizeProviderRoute(adapterName, trimmedRecipient, items, true);
+    }
+    if (/^@?local:channels[:/][\w.-]+$/.test(trimmed)) {
+        return {
+            ok: false,
+            error: 'Channel route mentions must include the provider, for example @local:channels_wecom:ops.',
+        };
+    }
+    if (trimmed !== '@local:channels' && trimmed !== 'local:channels') {
+        if (trimmedRecipient) {
+            const route = items.find((item) => item.type === 'route' && item.name === trimmedRecipient && item.adapter === trimmed);
+            if (route)
+                return { ok: true, value: route.name, recipient: '' };
+        }
+        return { ok: true, value: trimmed };
+    }
+    const routes = items.filter((item) => item.type === 'route');
+    if (routes.length > 0) {
+        return {
+            ok: false,
+            error: `@local:channels selects the plugin, not a route. Use one of these channel route mentions: ${routes
+                .map((item) => `@local:channels_${item.adapter ?? 'adapter'}:${item.name}`)
+                .join(', ')}.`,
+        };
+    }
+    const adapters = items.filter((item) => item.type === 'adapter');
+    if (adapters.length === 1) {
+        return {
+            ok: false,
+            error: `@local:channels selects the plugin, not a recipient. Use adapter "${adapters[0].name}" with a recipient.`,
+        };
+    }
+    return {
+        ok: false,
+        error: '@local:channels selects the plugin, not a send target. Run notify with action "list" and use an adapter name or route alias.',
+    };
+}
+function normalizeProviderRoute(adapterName, routeName, items, clearRecipient = false) {
+    const route = items.find((item) => item.type === 'route' && item.name === routeName);
+    if (route) {
+        if (route.adapter && route.adapter !== adapterName) {
+            return {
+                ok: false,
+                error: `Channel route "${routeName}" uses adapter "${route.adapter}", not "${adapterName}".`,
+            };
+        }
+        return { ok: true, value: route.name, ...(clearRecipient ? { recipient: '' } : {}) };
+    }
+    const routes = items.filter((item) => item.type === 'route');
+    return {
+        ok: false,
+        error: routes.length
+            ? `Unknown channel route "${routeName}". Use one of: ${routes
+                .map((item) => `local:channels_${item.adapter ?? 'adapter'}:${item.name}`)
+                .join(', ')}.`
+            : `Unknown channel route "${routeName}". No routes are configured.`,
+    };
 }
 function textToolResult(text) {
     return { content: [{ type: 'text', text }], details: undefined };