feat(channels): add channel schema, RPC controllers, and definition-driven UI (tinyhumansai#88)

* refactor(tests): rename native_dispatcher test for clarity and update assertions

- Renamed the test function to better reflect its purpose: checking that the native dispatcher returns protocol-only instructions.
- Updated assertions to ensure the instructions contain the expected protocol information and do not inline tool names.

* feat(channels): introduce channel controllers and enhance channel management

- Added new `controllers` module for channel definitions, connection management, and RPC controllers.
- Implemented channel connection logic, including connection status and credential management.
- Updated existing functions to extend support for new channel schemas and definitions.
- Enhanced documentation for channel-related functionalities, including descriptions for new RPC methods.

* feat(messaging): enhance MessagingPanel with backend-driven channel definitions and status management

- Introduced backend-driven channel definitions and status retrieval in MessagingPanel.
- Replaced hardcoded channel and auth mode definitions with dynamic data from the backend.
- Improved error handling and loading states for channel connections.
- Updated API service to support fetching channel definitions and connection statuses.
- Refactored state management for better clarity and maintainability.

* feat(messaging): implement fallback definitions for channel connections in MessagingPanel

- Added fallback definitions for Telegram and Discord channels to enhance messaging capabilities when backend is unreachable.
- Updated MessagingPanel to utilize fallback definitions if backend data is unavailable, improving error handling and user experience.
- Refactored API service methods to return results directly, streamlining data retrieval for channel definitions and statuses.

* feat(channels): add web channel support and enhance routing logic

- Introduced a new 'web' channel definition in MessagingPanel, allowing chat via the built-in web UI.
- Updated channel connection state management to include the web channel, ensuring proper handling of connections.
- Enhanced routing logic to support fallback mechanisms across all defined channels, improving resilience in connection handling.
- Refactored channel type definitions to accommodate the new web channel, ensuring consistency across the application.

Author: senamakel

app/src/components/settings/panels/MessagingPanel.tsx

@@ -8,6 +8,8 @@ import type {
 
 const SEND_PRIORITY: ChannelAuthMode[] = ['managed_dm', 'oauth', 'bot_token', 'api_key'];
 
+const ALL_CHANNELS: ChannelType[] = ['telegram', 'discord', 'web'];
+
 function isConnected(connection: ChannelConnection | undefined): boolean {
   return connection?.status === 'connected';
 }
@@ -17,6 +19,7 @@ export function resolvePreferredAuthModeForChannel(
   channel: ChannelType
 ): ChannelAuthMode | null {
   const channelModes = state.connections[channel];
+  if (!channelModes) return null;
   for (const authMode of SEND_PRIORITY) {
     if (isConnected(channelModes[authMode])) {
       return authMode;
@@ -35,9 +38,14 @@ export function resolveOutboundRoute(
     return { channel, authMode: mode };
   }
 
-  const fallbackChannel: ChannelType = channel === 'telegram' ? 'discord' : 'telegram';
-  const fallbackMode = resolvePreferredAuthModeForChannel(state, fallbackChannel);
-  if (!fallbackMode) return null;
+  // Try other channels as fallback.
+  for (const fallback of ALL_CHANNELS) {
+    if (fallback === channel) continue;
+    const fallbackMode = resolvePreferredAuthModeForChannel(state, fallback);
+    if (fallbackMode) {
+      return { channel: fallback, authMode: fallbackMode };
+    }
+  }
 
-  return { channel: fallbackChannel, authMode: fallbackMode };
+  return null;
 }

app/src/lib/channels/routing.ts

@@ -1,163 +1,69 @@
 import type {
   ChannelAuthMode,
-  ChannelConnection,
-  ChannelConnectionsByMode,
+  ChannelConnectionResult,
+  ChannelDefinition,
+  ChannelStatusEntry,
   ChannelType,
 } from '../../types/channels';
 import { callCoreRpc } from '../coreRpcClient';
 
 interface ConnectChannelPayload {
   authMode: ChannelAuthMode;
-  credentials?: { botToken?: string; apiKey?: string };
-}
-
-interface ConnectChannelResponse {
-  connection?: ChannelConnection;
-  oauthUrl?: string;
-}
-
-interface ChannelConnectionsResponse {
-  defaultMessagingChannel: ChannelType;
-  connections: Record<ChannelType, ChannelConnectionsByMode>;
-}
-
-interface AuthProfileSummary {
-  provider: string;
-  profileName: string;
-}
-
-interface OAuthIntegrationSummary {
-  id: string;
-  provider: string;
-}
-
-const SUPPORTED_CHANNELS: ChannelType[] = ['telegram', 'discord'];
-const SUPPORTED_AUTH_MODES: ChannelAuthMode[] = ['managed_dm', 'oauth', 'bot_token', 'api_key'];
-
-function emptyChannelConnectionsResponse(): ChannelConnectionsResponse {
-  return { defaultMessagingChannel: 'telegram', connections: { telegram: {}, discord: {} } };
-}
-
-function isSupportedChannel(value: string): value is ChannelType {
-  return SUPPORTED_CHANNELS.includes(value as ChannelType);
-}
-
-function makeConnectedChannelConnection(
-  channel: ChannelType,
-  authMode: ChannelAuthMode
-): ChannelConnection {
-  return {
-    channel,
-    authMode,
-    status: 'connected',
-    selectedDefault: false,
-    lastError: undefined,
-    capabilities: authMode === 'managed_dm' ? ['dm'] : ['read', 'write'],
-    updatedAt: new Date().toISOString(),
-  };
+  credentials?: Record<string, string>;
 }
 
 export const channelConnectionsApi = {
-  listConnections: async (): Promise<ChannelConnectionsResponse> => {
-    const [profilesResponse, integrationsResponse] = await Promise.all([
-      callCoreRpc<{ result: AuthProfileSummary[] }>({
-        method: 'openhuman.auth.list_provider_credentials',
-        params: {},
-      }),
-      callCoreRpc<{ result: OAuthIntegrationSummary[] }>({
-        method: 'openhuman.auth.oauth_list_integrations',
-        params: {},
-      }),
-    ]);
-
-    const output = emptyChannelConnectionsResponse();
-    const profiles = profilesResponse.result ?? [];
-    const integrations = integrationsResponse.result ?? [];
-
-    for (const profile of profiles) {
-      if (!isSupportedChannel(profile.provider)) continue;
-      const authMode = profile.profileName as ChannelAuthMode;
-      if (!SUPPORTED_AUTH_MODES.includes(authMode) || authMode === 'oauth') continue;
-      output.connections[profile.provider][authMode] = makeConnectedChannelConnection(
-        profile.provider,
-        authMode
-      );
-    }
-
-    for (const integration of integrations) {
-      if (!isSupportedChannel(integration.provider)) continue;
-      output.connections[integration.provider].oauth = makeConnectedChannelConnection(
-        integration.provider,
-        'oauth'
-      );
-    }
+  /** Fetch all available channel definitions from the backend. */
+  listDefinitions: async (): Promise<ChannelDefinition[]> => {
+    const result = await callCoreRpc<ChannelDefinition[]>({
+      method: 'openhuman.channels_list',
+      params: {},
+    });
+    return result;
+  },
 
-    return output;
+  /** Get connection status for one or all channels. */
+  listStatus: async (channel?: ChannelType): Promise<ChannelStatusEntry[]> => {
+    const params: Record<string, string> = {};
+    if (channel) params.channel = channel;
+    const result = await callCoreRpc<ChannelStatusEntry[]>({
+      method: 'openhuman.channels_status',
+      params,
+    });
+    return result;
   },
 
+  /** Connect a channel with the given auth mode and credentials. */
   connectChannel: async (
     channel: ChannelType,
     payload: ConnectChannelPayload
-  ): Promise<ConnectChannelResponse> => {
-    if (payload.authMode === 'oauth') {
-      const response = await callCoreRpc<{ result: { oauthUrl: string } }>({
-        method: 'openhuman.auth.oauth_connect',
-        params: { provider: channel, skillId: channel },
-      });
-      return {
-        oauthUrl: response.result.oauthUrl,
-        connection: makeConnectedChannelConnection(channel, payload.authMode),
-      };
-    }
-
-    const token =
-      payload.authMode === 'bot_token'
-        ? payload.credentials?.botToken?.trim()
-        : payload.authMode === 'api_key'
-          ? payload.credentials?.apiKey?.trim()
-          : undefined;
-
-    await callCoreRpc({
-      method: 'openhuman.auth.store_provider_credentials',
-      params: {
-        provider: channel,
-        profile: payload.authMode,
-        token,
-        fields: { authMode: payload.authMode },
-        setActive: true,
-      },
+  ): Promise<ChannelConnectionResult> => {
+    const result = await callCoreRpc<ChannelConnectionResult>({
+      method: 'openhuman.channels_connect',
+      params: { channel, authMode: payload.authMode, credentials: payload.credentials ?? {} },
     });
-
-    return { connection: makeConnectedChannelConnection(channel, payload.authMode) };
+    return result;
   },
 
+  /** Disconnect a channel for a given auth mode. */
   disconnectChannel: async (channel: ChannelType, authMode: ChannelAuthMode): Promise<void> => {
-    if (authMode === 'oauth') {
-      const listResponse = await callCoreRpc<{ result: OAuthIntegrationSummary[] }>({
-        method: 'openhuman.auth.oauth_list_integrations',
-        params: {},
-      });
-      const integrationIds = (listResponse.result ?? [])
-        .filter(item => item.provider === channel)
-        .map(item => item.id);
-
-      await Promise.all(
-        integrationIds.map(integrationId =>
-          callCoreRpc({
-            method: 'openhuman.auth.oauth_revoke_integration',
-            params: { integrationId },
-          })
-        )
-      );
-      return;
-    }
+    await callCoreRpc({ method: 'openhuman.channels_disconnect', params: { channel, authMode } });
+  },
 
-    await callCoreRpc({
-      method: 'openhuman.auth.remove_provider_credentials',
-      params: { provider: channel, profile: authMode },
+  /** Test channel credentials without persisting. */
+  testChannel: async (
+    channel: ChannelType,
+    authMode: ChannelAuthMode,
+    credentials: Record<string, string>
+  ): Promise<{ success: boolean; message: string }> => {
+    const result = await callCoreRpc<{ success: boolean; message: string }>({
+      method: 'openhuman.channels_test',
+      params: { channel, authMode, credentials },
     });
+    return result;
   },
 
+  /** Placeholder for default channel preference sync. */
   updatePreferences: async (defaultMessagingChannel: ChannelType): Promise<void> => {
     void defaultMessagingChannel;
   },

app/src/services/api/channelConnectionsApi.ts

@@ -21,7 +21,11 @@ const initialState: ChannelConnectionsState = {
   schemaVersion: SCHEMA_VERSION,
   migrationCompleted: false,
   defaultMessagingChannel: 'telegram',
-  connections: { telegram: makeEmptyChannelModes(), discord: makeEmptyChannelModes() },
+  connections: {
+    telegram: makeEmptyChannelModes(),
+    discord: makeEmptyChannelModes(),
+    web: makeEmptyChannelModes(),
+  },
 };
 
 function touchConnection(
@@ -47,6 +51,7 @@ const channelConnectionsSlice = createSlice({
       if (state.migrationCompleted) return;
       state.connections.telegram = makeEmptyChannelModes();
       state.connections.discord = makeEmptyChannelModes();
+      state.connections.web = makeEmptyChannelModes();
       state.defaultMessagingChannel = 'telegram';
       state.migrationCompleted = true;
       state.schemaVersion = SCHEMA_VERSION;

app/src/store/channelConnectionsSlice.ts

@@ -1,4 +1,4 @@
-export type ChannelType = 'telegram' | 'discord';
+export type ChannelType = 'telegram' | 'discord' | 'web';
 
 export type ChannelAuthMode = 'managed_dm' | 'oauth' | 'bot_token' | 'api_key';
 
@@ -32,3 +32,53 @@ export interface OutboundRoute {
   channel: ChannelType;
   authMode: ChannelAuthMode;
 }
+
+// --- Backend-driven definitions (from openhuman.channels_list) ---
+
+export interface FieldRequirement {
+  key: string;
+  label: string;
+  field_type: string; // "string" | "secret" | "boolean"
+  required: boolean;
+  placeholder: string;
+}
+
+export interface AuthModeSpec {
+  mode: ChannelAuthMode;
+  description: string;
+  fields: FieldRequirement[];
+  auth_action?: string; // e.g. "telegram_managed_dm", "discord_oauth"
+}
+
+export type ChannelCapability =
+  | 'send_text'
+  | 'send_rich_text'
+  | 'receive_text'
+  | 'typing'
+  | 'draft_updates'
+  | 'threaded_replies'
+  | 'file_attachments'
+  | 'reactions';
+
+export interface ChannelDefinition {
+  id: string;
+  display_name: string;
+  description: string;
+  icon: string;
+  auth_modes: AuthModeSpec[];
+  capabilities: ChannelCapability[];
+}
+
+export interface ChannelStatusEntry {
+  channel_id: string;
+  auth_mode: ChannelAuthMode;
+  connected: boolean;
+  has_credentials: boolean;
+}
+
+export interface ChannelConnectionResult {
+  status: string; // "connected" | "pending_auth"
+  restart_required: boolean;
+  auth_action?: string;
+  message?: string;
+}

app/src/types/channels.ts

@@ -17,9 +17,9 @@ todo
 [] Integrate our custom memory engine into core - sanil
 [] Integrate our skills registry into core - steve
 [x] Integrate accessibility service installation
-[] Add as a step and setting in the UI - cyrus 
-[x] Remove mentions of zeroclaw from the codebaes 
-[x] Integrate local LLM into core 
+[] Add as a step and setting in the UI - cyrus
+[x] Remove mentions of zeroclaw from the codebaes
+[x] Integrate local LLM into core
 [x] Handle process/deamon properly
 [x] install the linux philosophy of few modules that do their own thing really well sort of..
 [x] Remove android / ios support from the codebase.
@@ -29,9 +29,13 @@ todo
 [] Add icon and app name to the various permission settings - mithil
 [] add self update based on github release. create a update action on the cli - aniketh
 [] for each skill show information on how much data has been synced locally and information on how much syncs have happened so far etc.. - mithil/elvin
-[x] redo the docs once everything is done. 
+[x] redo the docs once everything is done.
 [x] remove unwanted feature flags from the rust binary
 [] fix the config properly - mithil
 [] Allow for Migrating from OpenClaw - steve done - to be tested
 [] allow users to choose which version of LLM model they'd like to choose based on their CPU. better ram and gpu means higher parameter model can be used. - mithil
-[x] in the client side app, make console.log follow a logger style logging where there's a namespace for every logger (like python) - steve 
+[x] in the client side app, make console.log follow a logger style logging where there's a namespace for every logger (like python) - steve
+
+--- e2e tests to write up
+
+- [ ] connecting a channel like telegram/discord works properly

docs/TODO.md

@@ -49,6 +49,8 @@ fn build_registered_controllers() -> Vec<RegisteredController> {
     controllers.extend(
         crate::openhuman::channels::providers::web::all_web_channel_registered_controllers(),
     );
+    controllers
+        .extend(crate::openhuman::channels::controllers::all_channels_registered_controllers());
     controllers.extend(crate::openhuman::config::all_config_registered_controllers());
     controllers.extend(crate::openhuman::credentials::all_credentials_registered_controllers());
     controllers.extend(crate::openhuman::service::all_service_registered_controllers());
@@ -76,6 +78,7 @@ fn build_declared_controller_schemas() -> Vec<ControllerSchema> {
     schemas.extend(crate::openhuman::autocomplete::all_autocomplete_controller_schemas());
     schemas
         .extend(crate::openhuman::channels::providers::web::all_web_channel_controller_schemas());
+    schemas.extend(crate::openhuman::channels::controllers::all_channels_controller_schemas());
     schemas.extend(crate::openhuman::config::all_config_controller_schemas());
     schemas.extend(crate::openhuman::credentials::all_credentials_controller_schemas());
     schemas.extend(crate::openhuman::service::all_service_controller_schemas());
@@ -108,6 +111,7 @@ pub fn namespace_description(namespace: &str) -> Option<&'static str> {
     match namespace {
         "auth" => Some("Manage app session and provider credentials."),
         "autocomplete" => Some("Inline autocomplete engine controls and style settings."),
+        "channels" => Some("Channel definitions, connections, and lifecycle management."),
         "config" => Some("Read and update persisted runtime configuration."),
         "cron" => Some("Manage scheduled jobs and run history."),
         "decrypt" => Some("Decrypt secure values managed by secret storage."),