@clawnch/clawtomaton 0.7.0 → 0.8.1

package/dist/skills/clawnx.js

@@ -1,28 +1,43 @@
 /**
- * Skill: clawnx — X/Twitter integration via ClawnX from @clawnch/sdk.
+ * Skill: clawnx — Full X/Twitter integration via ClawnX from @clawnch/clawnx.
+ *
+ * 45+ actions covering every surface of the X API v2:
+ *
+ *   Content:     post_tweet, post_thread, post_with_media, upload_media, delete_tweet, get_tweet, search
+ *   Engagement:  like, unlike, retweet, unretweet, bookmark, unbookmark, list_bookmarks, list_likes,
+ *                liking_users, retweeted_by, quote_tweets
+ *   Social:      follow, unfollow, list_followers, list_following, block, unblock, mute, unmute,
+ *                list_blocked, list_muted, get_user, search_users, lookup_users
+ *   Timelines:   get_timeline, home_timeline, get_mentions, get_my_profile
+ *   DMs:         send_dm, send_dm_to_conversation, list_dms, get_dm_conversation
+ *   Threads:     get_conversation
+ *   Lists:       create_list, delete_list, get_list, get_user_lists, add_list_member,
+ *                remove_list_member, list_members, list_tweets
+ *   Streaming:   stream_start, stream_stop, stream_rules_set, stream_rules_get
+ *   Orchestration: action_chain (multi-step with PREV_TWEET_ID substitution)
+ *   Media:       upload_media, post_with_media
+ *
+ * All X API logic lives in @clawnch/clawnx — this file is a thin Clawtomaton
+ * skill adapter that maps action names + params to ClawnX method calls.
  *
- * Lets the agent post tweets, search, engage, and monitor X/Twitter.
  * Requires X API credentials in environment variables:
  *   X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET, X_BEARER_TOKEN
- *
- * ClawnX is lazy-loaded from @clawnch/sdk (optional dependency).
  */
 /** Lazy singleton — created once on first use */
 let cachedClient = null;
 async function getClawnX() {
     if (cachedClient)
         return cachedClient;
-    let sdk;
+    let mod;
     try {
-        // @ts-ignore — @clawnch/sdk is an optional dependency
-        sdk = await import('@clawnch/sdk');
+        // @ts-ignore — @clawnch/clawnx is an optional dependency
+        mod = await import('@clawnch/clawnx');
     }
     catch {
-        throw new Error('@clawnch/sdk not installed. Run: npm install @clawnch/sdk\n' +
+        throw new Error('@clawnch/clawnx not installed. Run: npm install @clawnch/clawnx\n' +
             'Then set env vars: X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET, X_BEARER_TOKEN');
     }
-    // ClawnX constructor reads credentials from env vars by default
-    cachedClient = new sdk.ClawnX();
+    cachedClient = new mod.ClawnX();
     return cachedClient;
 }
 function formatTweet(tweet) {
@@ -39,20 +54,28 @@ function formatUser(user) {
 }
 export const clawnxSkill = {
     name: 'clawnx',
-    description: 'X/Twitter: post tweets, search, like, retweet, follow, read timelines, post threads, get mentions. ' +
-        'Requires X API credentials (X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET, X_BEARER_TOKEN).',
+    description: 'Full X/Twitter integration: 45+ actions covering content, engagement, social graph, DMs, lists, ' +
+        'streaming, media, and multi-step orchestration. Agent-native with structured metadata, action chaining, ' +
+        'and atomic thread posting. Requires X API credentials.',
     parameters: [
         {
             name: 'action',
             type: 'string',
-            description: 'Action: "post_tweet", "post_thread", "search", "get_tweet", "like", "retweet", ' +
-                '"follow", "get_user", "get_mentions", "get_timeline", "get_my_profile", "delete_tweet".',
+            description: 'Action to perform. Content: post_tweet, post_thread, post_with_media, upload_media, delete_tweet, get_tweet, search. ' +
+                'Engagement: like, unlike, retweet, unretweet, bookmark, unbookmark, list_bookmarks, list_likes, liking_users, retweeted_by, quote_tweets. ' +
+                'Social: follow, unfollow, list_followers, list_following, block, unblock, mute, unmute, list_blocked, list_muted, get_user, search_users, lookup_users. ' +
+                'Timelines: get_timeline, home_timeline, get_mentions, get_my_profile. ' +
+                'DMs: send_dm, send_dm_to_conversation, list_dms, get_dm_conversation. ' +
+                'Threads: get_conversation. ' +
+                'Lists: create_list, delete_list, get_list, get_user_lists, add_list_member, remove_list_member, list_members, list_tweets. ' +
+                'Streaming: stream_start, stream_stop, stream_rules_set, stream_rules_get. ' +
+                'Orchestration: action_chain.',
             required: true,
         },
         {
             name: 'text',
             type: 'string',
-            description: 'Tweet text (for post_tweet). Max 280 chars.',
+            description: 'Tweet text (for post_tweet, post_with_media) or DM text (for send_dm). Max 280 chars for tweets.',
             required: false,
         },
         {
@@ -64,31 +87,105 @@ export const clawnxSkill = {
         {
             name: 'query',
             type: 'string',
-            description: 'Search query (for search action). Supports X query syntax ($TICKER, from:user, etc.).',
+            description: 'Search query (for search, search_users). Supports X query syntax ($TICKER, from:user, etc.).',
             required: false,
         },
         {
             name: 'tweet_id',
             type: 'string',
-            description: 'Tweet ID or URL (for get_tweet, like, retweet, delete_tweet).',
+            description: 'Tweet ID or URL (for get_tweet, like, unlike, retweet, unretweet, delete_tweet, bookmark, unbookmark, get_conversation, liking_users, retweeted_by, quote_tweets).',
             required: false,
         },
         {
             name: 'username',
             type: 'string',
-            description: 'Username without @ (for get_user, follow, get_timeline).',
+            description: 'Username without @ (for get_user, follow, unfollow, get_timeline, list_followers, list_following, block, unblock, mute, unmute, send_dm, list_likes, lookup_users).',
+            required: false,
+        },
+        {
+            name: 'usernames',
+            type: 'string',
+            description: 'Comma-separated usernames for lookup_users (e.g. "alice,bob,carol").',
             required: false,
         },
         {
             name: 'reply_to',
             type: 'string',
-            description: 'Tweet ID or URL to reply to (for post_tweet).',
+            description: 'Tweet ID or URL to reply to (for post_tweet, post_with_media).',
             required: false,
         },
         {
             name: 'quote',
             type: 'string',
-            description: 'Tweet ID or URL to quote (for post_tweet).',
+            description: 'Tweet ID or URL to quote (for post_tweet, post_with_media).',
+            required: false,
+        },
+        {
+            name: 'media_url',
+            type: 'string',
+            description: 'URL to media file for upload_media or post_with_media. Supports images, GIFs, videos.',
+            required: false,
+        },
+        {
+            name: 'media_type',
+            type: 'string',
+            description: 'MIME type override (e.g. "image/jpeg", "video/mp4"). Auto-detected if omitted.',
+            required: false,
+        },
+        {
+            name: 'count',
+            type: 'number',
+            description: 'Number of results to return for list/pagination actions (default: 20, max: 100).',
+            required: false,
+            default: 20,
+        },
+        {
+            name: 'list_id',
+            type: 'string',
+            description: 'List ID (for list actions: get_list, delete_list, add_list_member, remove_list_member, list_members, list_tweets).',
+            required: false,
+        },
+        {
+            name: 'list_name',
+            type: 'string',
+            description: 'List name (for create_list).',
+            required: false,
+        },
+        {
+            name: 'list_description',
+            type: 'string',
+            description: 'List description (for create_list).',
+            required: false,
+        },
+        {
+            name: 'list_private',
+            type: 'boolean',
+            description: 'Whether the list is private (for create_list). Default: false.',
+            required: false,
+        },
+        {
+            name: 'conversation_id',
+            type: 'string',
+            description: 'DM conversation ID (for send_dm_to_conversation, get_dm_conversation).',
+            required: false,
+        },
+        {
+            name: 'stream_rules',
+            type: 'string',
+            description: 'JSON array of stream filter rules for stream_rules_set. E.g. [{"value":"$CLAWNCH","tag":"token"}].',
+            required: false,
+        },
+        {
+            name: 'stream_duration',
+            type: 'number',
+            description: 'Stream duration in seconds for stream_start (default: 30, max: 300).',
+            required: false,
+            default: 30,
+        },
+        {
+            name: 'chain_steps',
+            type: 'string',
+            description: 'JSON array of action steps for action_chain. Each step is {action, ...params}. Use "PREV_TWEET_ID" to reference the previous step\'s tweet ID.',
             required: false,
         },
     ],
@@ -112,6 +209,7 @@ export const clawnxSkill = {
                         callId: '',
                         success: true,
                         result: `Posted tweet ${tweet.id}: ${tweet.text}\nhttps://x.com/i/status/${tweet.id}`,
+                        metadata: { tweet_id: tweet.id },
                     };
                 }
                 case 'post_thread': {
@@ -124,11 +222,12 @@ export const clawnxSkill = {
                     }
                     const threadTweets = texts.map((t) => ({ text: t }));
                     const result = await x.postThread(threadTweets);
-                    const ids = result.tweets.map((t) => t.data?.id ?? 'unknown');
+                    const ids = result.tweetIds;
                     return {
                         callId: '',
                         success: true,
                         result: `Posted ${ids.length}-tweet thread.\nFirst: https://x.com/i/status/${ids[0]}\nIDs: ${ids.join(', ')}`,
+                        metadata: { tweet_ids: ids, first_tweet_id: ids[0] },
                     };
                 }
                 case 'search': {
@@ -189,7 +288,7 @@ export const clawnxSkill = {
                     const username = params.username;
                     if (!username)
                         return { callId: '', success: false, result: null, error: 'username is required for get_timeline' };
-                    const result = await x.getUserTimeline({ username, maxResults: 10 });
+                    const result = await x.getUserTimeline(username, { maxResults: 10 });
                     const tweets = result.data ?? [];
                     if (tweets.length === 0)
                         return { callId: '', success: true, result: `No recent tweets from @${username}.` };
@@ -207,12 +306,608 @@ export const clawnxSkill = {
                     await x.deleteTweet(tweetId);
                     return { callId: '', success: true, result: `Deleted tweet ${tweetId}` };
                 }
+                // ==================================================================
+                // Undo engagement
+                // ==================================================================
+                case 'unlike': {
+                    const tweetId = params.tweet_id;
+                    if (!tweetId)
+                        return { callId: '', success: false, result: null, error: 'tweet_id is required for unlike' };
+                    await x.unlikeTweet(tweetId);
+                    return { callId: '', success: true, result: `Unliked tweet ${tweetId}` };
+                }
+                case 'unretweet': {
+                    const tweetId = params.tweet_id;
+                    if (!tweetId)
+                        return { callId: '', success: false, result: null, error: 'tweet_id is required for unretweet' };
+                    await x.unretweet(tweetId);
+                    return { callId: '', success: true, result: `Unretweeted ${tweetId}` };
+                }
+                case 'unfollow': {
+                    const username = params.username;
+                    if (!username)
+                        return { callId: '', success: false, result: null, error: 'username is required for unfollow' };
+                    await x.unfollowUser(username);
+                    return { callId: '', success: true, result: `Unfollowed @${username}` };
+                }
+                // ==================================================================
+                // Bookmarks
+                // ==================================================================
+                case 'bookmark': {
+                    const tweetId = params.tweet_id;
+                    if (!tweetId)
+                        return { callId: '', success: false, result: null, error: 'tweet_id is required for bookmark' };
+                    await x.bookmarkTweet(tweetId);
+                    return { callId: '', success: true, result: `Bookmarked tweet ${tweetId}` };
+                }
+                case 'unbookmark': {
+                    const tweetId = params.tweet_id;
+                    if (!tweetId)
+                        return { callId: '', success: false, result: null, error: 'tweet_id is required for unbookmark' };
+                    await x.unbookmarkTweet(tweetId);
+                    return { callId: '', success: true, result: `Removed bookmark for tweet ${tweetId}` };
+                }
+                case 'list_bookmarks': {
+                    const count = params.count ?? 20;
+                    const result = await x.getBookmarks({ maxResults: Math.min(count, 100) });
+                    const tweets = result.data ?? [];
+                    if (tweets.length === 0)
+                        return { callId: '', success: true, result: 'No bookmarks.' };
+                    const lines = tweets.map(formatTweet);
+                    return { callId: '', success: true, result: `${tweets.length} bookmarked tweets:\n${lines.join('\n')}` };
+                }
+                // ==================================================================
+                // Block / Mute
+                // ==================================================================
+                case 'block': {
+                    const username = params.username;
+                    if (!username)
+                        return { callId: '', success: false, result: null, error: 'username is required for block' };
+                    await x.blockUser(username);
+                    return { callId: '', success: true, result: `Blocked @${username}` };
+                }
+                case 'unblock': {
+                    const username = params.username;
+                    if (!username)
+                        return { callId: '', success: false, result: null, error: 'username is required for unblock' };
+                    await x.unblockUser(username);
+                    return { callId: '', success: true, result: `Unblocked @${username}` };
+                }
+                case 'mute': {
+                    const username = params.username;
+                    if (!username)
+                        return { callId: '', success: false, result: null, error: 'username is required for mute' };
+                    await x.muteUser(username);
+                    return { callId: '', success: true, result: `Muted @${username}` };
+                }
+                case 'unmute': {
+                    const username = params.username;
+                    if (!username)
+                        return { callId: '', success: false, result: null, error: 'username is required for unmute' };
+                    await x.unmuteUser(username);
+                    return { callId: '', success: true, result: `Unmuted @${username}` };
+                }
+                case 'list_blocked': {
+                    const count = params.count ?? 20;
+                    const result = await x.getBlockedUsers({ maxResults: Math.min(count, 100) });
+                    const users = result.data ?? [];
+                    if (users.length === 0)
+                        return { callId: '', success: true, result: 'No blocked users.' };
+                    const lines = users.map(formatUser);
+                    return { callId: '', success: true, result: `${users.length} blocked users:\n${lines.join('\n')}` };
+                }
+                case 'list_muted': {
+                    const count = params.count ?? 20;
+                    const result = await x.getMutedUsers({ maxResults: Math.min(count, 100) });
+                    const users = result.data ?? [];
+                    if (users.length === 0)
+                        return { callId: '', success: true, result: 'No muted users.' };
+                    const lines = users.map(formatUser);
+                    return { callId: '', success: true, result: `${users.length} muted users:\n${lines.join('\n')}` };
+                }
+                // ==================================================================
+                // Social graph
+                // ==================================================================
+                case 'list_followers': {
+                    const username = params.username;
+                    if (!username)
+                        return { callId: '', success: false, result: null, error: 'username is required for list_followers' };
+                    const count = params.count ?? 20;
+                    const result = await x.getFollowers(username, { maxResults: Math.min(count, 100) });
+                    const users = result.data ?? [];
+                    if (users.length === 0)
+                        return { callId: '', success: true, result: `@${username} has no followers (or account is private).` };
+                    const lines = users.map(formatUser);
+                    return {
+                        callId: '',
+                        success: true,
+                        result: `@${username}'s followers (${users.length}):\n${lines.join('\n')}`,
+                        metadata: { count: users.length, username },
+                    };
+                }
+                case 'list_following': {
+                    const username = params.username;
+                    if (!username)
+                        return { callId: '', success: false, result: null, error: 'username is required for list_following' };
+                    const count = params.count ?? 20;
+                    const result = await x.getFollowing(username, { maxResults: Math.min(count, 100) });
+                    const users = result.data ?? [];
+                    if (users.length === 0)
+                        return { callId: '', success: true, result: `@${username} follows nobody.` };
+                    const lines = users.map(formatUser);
+                    return {
+                        callId: '',
+                        success: true,
+                        result: `@${username} follows (${users.length}):\n${lines.join('\n')}`,
+                        metadata: { count: users.length, username },
+                    };
+                }
+                // ==================================================================
+                // Engagement lookups
+                // ==================================================================
+                case 'list_likes': {
+                    const username = params.username;
+                    if (!username)
+                        return { callId: '', success: false, result: null, error: 'username is required for list_likes' };
+                    const count = params.count ?? 20;
+                    const result = await x.getLikedTweets(username, { maxResults: Math.min(count, 100) });
+                    const tweets = result.data ?? [];
+                    if (tweets.length === 0)
+                        return { callId: '', success: true, result: `@${username} has no public likes.` };
+                    const lines = tweets.map(formatTweet);
+                    return { callId: '', success: true, result: `@${username}'s liked tweets (${tweets.length}):\n${lines.join('\n')}` };
+                }
+                case 'liking_users': {
+                    const tweetId = params.tweet_id;
+                    if (!tweetId)
+                        return { callId: '', success: false, result: null, error: 'tweet_id is required for liking_users' };
+                    const count = params.count ?? 20;
+                    const result = await x.getLikingUsers(tweetId, { maxResults: Math.min(count, 100) });
+                    const users = result.data ?? [];
+                    if (users.length === 0)
+                        return { callId: '', success: true, result: 'No users liked this tweet.' };
+                    const lines = users.map(formatUser);
+                    return {
+                        callId: '',
+                        success: true,
+                        result: `Users who liked ${tweetId} (${users.length}):\n${lines.join('\n')}`,
+                        metadata: { count: users.length },
+                    };
+                }
+                case 'retweeted_by': {
+                    const tweetId = params.tweet_id;
+                    if (!tweetId)
+                        return { callId: '', success: false, result: null, error: 'tweet_id is required for retweeted_by' };
+                    const count = params.count ?? 20;
+                    const result = await x.getRetweetedBy(tweetId, { maxResults: Math.min(count, 100) });
+                    const users = result.data ?? [];
+                    if (users.length === 0)
+                        return { callId: '', success: true, result: 'No users retweeted this tweet.' };
+                    const lines = users.map(formatUser);
+                    return {
+                        callId: '',
+                        success: true,
+                        result: `Users who retweeted ${tweetId} (${users.length}):\n${lines.join('\n')}`,
+                        metadata: { count: users.length },
+                    };
+                }
+                case 'quote_tweets': {
+                    const tweetId = params.tweet_id;
+                    if (!tweetId)
+                        return { callId: '', success: false, result: null, error: 'tweet_id is required for quote_tweets' };
+                    const count = params.count ?? 20;
+                    const result = await x.getQuoteTweets(tweetId, { maxResults: Math.min(count, 100) });
+                    const tweets = result.data ?? [];
+                    if (tweets.length === 0)
+                        return { callId: '', success: true, result: 'No quote tweets.' };
+                    const lines = tweets.map(formatTweet);
+                    return { callId: '', success: true, result: `Quote tweets of ${tweetId} (${tweets.length}):\n${lines.join('\n')}` };
+                }
+                // ==================================================================
+                // Home timeline
+                // ==================================================================
+                case 'home_timeline': {
+                    const count = params.count ?? 20;
+                    const result = await x.getHomeTimeline({ maxResults: Math.min(count, 100) });
+                    const tweets = result.data ?? [];
+                    if (tweets.length === 0)
+                        return { callId: '', success: true, result: 'Home timeline is empty.' };
+                    const lines = tweets.map(formatTweet);
+                    return { callId: '', success: true, result: `Home timeline (${tweets.length} tweets):\n${lines.join('\n')}` };
+                }
+                // ==================================================================
+                // Tweet metrics (detailed)
+                // ==================================================================
+                case 'get_tweet_metrics': {
+                    const tweetId = params.tweet_id;
+                    if (!tweetId)
+                        return { callId: '', success: false, result: null, error: 'tweet_id is required for get_tweet_metrics' };
+                    const result = await x.getTweetMetrics(tweetId);
+                    const t = result.data;
+                    const m = t.public_metrics;
+                    const lines = [
+                        `Tweet ${t.id}: ${t.text?.substring(0, 100)}${(t.text?.length ?? 0) > 100 ? '...' : ''}`,
+                        m ? `  Likes: ${m.like_count}  Retweets: ${m.retweet_count}  Replies: ${m.reply_count}  Quotes: ${m.quote_count ?? 0}  Impressions: ${m.impression_count ?? 'N/A'}  Bookmarks: ${m.bookmark_count ?? 'N/A'}` : '  Metrics unavailable',
+                    ];
+                    return { callId: '', success: true, result: lines.join('\n'), metadata: { metrics: m } };
+                }
+                // ==================================================================
+                // Conversation / thread retrieval
+                // ==================================================================
+                case 'get_conversation': {
+                    const tweetId = params.tweet_id;
+                    if (!tweetId)
+                        return { callId: '', success: false, result: null, error: 'tweet_id is required for get_conversation' };
+                    const count = params.count ?? 20;
+                    const result = await x.getConversation(tweetId, { maxResults: Math.min(count, 100) });
+                    const tweets = result.data ?? [];
+                    if (tweets.length === 0)
+                        return { callId: '', success: true, result: 'No conversation thread found.' };
+                    const lines = tweets.map(formatTweet);
+                    return { callId: '', success: true, result: `Conversation thread (${tweets.length} tweets):\n${lines.join('\n')}` };
+                }
+                // ==================================================================
+                // Direct Messages
+                // ==================================================================
+                case 'send_dm': {
+                    const username = params.username;
+                    const text = params.text;
+                    if (!username)
+                        return { callId: '', success: false, result: null, error: 'username is required for send_dm' };
+                    if (!text)
+                        return { callId: '', success: false, result: null, error: 'text is required for send_dm' };
+                    const result = await x.sendDM(username, { text });
+                    const eventId = result.data?.dm_event_id ?? result.data?.id ?? 'sent';
+                    return {
+                        callId: '',
+                        success: true,
+                        result: `DM sent to @${username}: "${text.substring(0, 60)}${text.length > 60 ? '...' : ''}"\nEvent: ${eventId}`,
+                        metadata: { dm_event_id: eventId, recipient: username },
+                    };
+                }
+                case 'send_dm_to_conversation': {
+                    const conversationId = params.conversation_id;
+                    const text = params.text;
+                    if (!conversationId)
+                        return { callId: '', success: false, result: null, error: 'conversation_id is required for send_dm_to_conversation' };
+                    if (!text)
+                        return { callId: '', success: false, result: null, error: 'text is required for send_dm_to_conversation' };
+                    const result = await x.sendDMToConversation(conversationId, { text });
+                    const eventId = result.data?.dm_event_id ?? result.data?.id ?? 'sent';
+                    return {
+                        callId: '',
+                        success: true,
+                        result: `DM sent to conversation ${conversationId}: "${text.substring(0, 60)}${text.length > 60 ? '...' : ''}"\nEvent: ${eventId}`,
+                        metadata: { dm_event_id: eventId, conversation_id: conversationId },
+                    };
+                }
+                case 'list_dms': {
+                    const count = params.count ?? 20;
+                    const result = await x.getDMEvents({ maxResults: Math.min(count, 100) });
+                    const events = result.data ?? [];
+                    if (events.length === 0)
+                        return { callId: '', success: true, result: 'No recent DM events.' };
+                    const lines = events.map((e) => {
+                        const sender = e.sender_id ?? 'unknown';
+                        const text = e.text ?? e.dm_conversation_id ?? '';
+                        const time = e.created_at ? ` (${e.created_at})` : '';
+                        return `  ${e.id}: [${sender}] ${text.substring(0, 80)}${text.length > 80 ? '...' : ''}${time}`;
+                    });
+                    return { callId: '', success: true, result: `${events.length} recent DM events:\n${lines.join('\n')}` };
+                }
+                case 'get_dm_conversation': {
+                    const conversationId = params.conversation_id;
+                    if (!conversationId)
+                        return { callId: '', success: false, result: null, error: 'conversation_id is required for get_dm_conversation' };
+                    const count = params.count ?? 20;
+                    const result = await x.getDMConversation(conversationId, { maxResults: Math.min(count, 100) });
+                    const events = result.data ?? [];
+                    if (events.length === 0)
+                        return { callId: '', success: true, result: 'No messages in this conversation.' };
+                    const lines = events.map((e) => {
+                        const sender = e.sender_id ?? 'unknown';
+                        const text = e.text ?? '';
+                        const time = e.created_at ? ` (${e.created_at})` : '';
+                        return `  [${sender}] ${text}${time}`;
+                    });
+                    return { callId: '', success: true, result: `Conversation ${conversationId} (${events.length} messages):\n${lines.join('\n')}` };
+                }
+                // ==================================================================
+                // Lists management
+                // ==================================================================
+                case 'create_list': {
+                    const name = params.list_name;
+                    if (!name)
+                        return { callId: '', success: false, result: null, error: 'list_name is required for create_list' };
+                    const result = await x.createList({
+                        name,
+                        description: params.list_description ?? '',
+                        private: params.list_private ?? false,
+                    });
+                    const list = result.data;
+                    return {
+                        callId: '',
+                        success: true,
+                        result: `List created: "${list.name}" (ID: ${list.id})`,
+                        metadata: { list_id: list.id, list_name: list.name },
+                    };
+                }
+                case 'delete_list': {
+                    const listId = params.list_id;
+                    if (!listId)
+                        return { callId: '', success: false, result: null, error: 'list_id is required for delete_list' };
+                    await x.deleteList(listId);
+                    return { callId: '', success: true, result: `Deleted list ${listId}` };
+                }
+                case 'get_list': {
+                    const listId = params.list_id;
+                    if (!listId)
+                        return { callId: '', success: false, result: null, error: 'list_id is required for get_list' };
+                    const result = await x.getList(listId);
+                    const l = result.data;
+                    return { callId: '', success: true, result: `List "${l.name}" (${l.id}): ${l.description ?? 'no description'} | ${l.member_count ?? '?'} members | ${l.private ? 'private' : 'public'}` };
+                }
+                case 'get_user_lists': {
+                    const username = params.username;
+                    if (!username)
+                        return { callId: '', success: false, result: null, error: 'username is required for get_user_lists' };
+                    const count = params.count ?? 20;
+                    const result = await x.getUserLists(username, { maxResults: Math.min(count, 100) });
+                    const lists = result.data ?? [];
+                    if (lists.length === 0)
+                        return { callId: '', success: true, result: `@${username} has no public lists.` };
+                    const lines = lists.map((l) => `  ${l.id}: "${l.name}" — ${l.member_count ?? '?'} members`);
+                    return { callId: '', success: true, result: `@${username}'s lists (${lists.length}):\n${lines.join('\n')}` };
+                }
+                case 'add_list_member': {
+                    const listId = params.list_id;
+                    const username = params.username;
+                    if (!listId)
+                        return { callId: '', success: false, result: null, error: 'list_id is required for add_list_member' };
+                    if (!username)
+                        return { callId: '', success: false, result: null, error: 'username is required for add_list_member' };
+                    await x.addListMember(listId, username);
+                    return { callId: '', success: true, result: `Added @${username} to list ${listId}` };
+                }
+                case 'remove_list_member': {
+                    const listId = params.list_id;
+                    const username = params.username;
+                    if (!listId)
+                        return { callId: '', success: false, result: null, error: 'list_id is required for remove_list_member' };
+                    if (!username)
+                        return { callId: '', success: false, result: null, error: 'username is required for remove_list_member' };
+                    await x.removeListMember(listId, username);
+                    return { callId: '', success: true, result: `Removed @${username} from list ${listId}` };
+                }
+                case 'list_members': {
+                    const listId = params.list_id;
+                    if (!listId)
+                        return { callId: '', success: false, result: null, error: 'list_id is required for list_members' };
+                    const count = params.count ?? 20;
+                    const result = await x.getListMembers(listId, { maxResults: Math.min(count, 100) });
+                    const users = result.data ?? [];
+                    if (users.length === 0)
+                        return { callId: '', success: true, result: 'No members in this list.' };
+                    const lines = users.map(formatUser);
+                    return { callId: '', success: true, result: `List ${listId} members (${users.length}):\n${lines.join('\n')}` };
+                }
+                case 'list_tweets': {
+                    const listId = params.list_id;
+                    if (!listId)
+                        return { callId: '', success: false, result: null, error: 'list_id is required for list_tweets' };
+                    const count = params.count ?? 20;
+                    const result = await x.getListTweets(listId, { maxResults: Math.min(count, 100) });
+                    const tweets = result.data ?? [];
+                    if (tweets.length === 0)
+                        return { callId: '', success: true, result: 'No tweets in this list.' };
+                    const lines = tweets.map(formatTweet);
+                    return { callId: '', success: true, result: `List ${listId} tweets (${tweets.length}):\n${lines.join('\n')}` };
+                }
+                // ==================================================================
+                // User lookup & search
+                // ==================================================================
+                case 'search_users': {
+                    const query = params.query;
+                    if (!query)
+                        return { callId: '', success: false, result: null, error: 'query is required for search_users' };
+                    const count = params.count ?? 20;
+                    const result = await x.searchUsers(query, { maxResults: Math.min(count, 100) });
+                    const users = result.data ?? [];
+                    if (users.length === 0)
+                        return { callId: '', success: true, result: `No users match "${query}".` };
+                    const lines = users.map(formatUser);
+                    return { callId: '', success: true, result: `Users matching "${query}" (${users.length}):\n${lines.join('\n')}` };
+                }
+                case 'lookup_users': {
+                    const usernamesStr = params.usernames;
+                    if (!usernamesStr)
+                        return { callId: '', success: false, result: null, error: 'usernames (comma-separated) is required for lookup_users' };
+                    const usernames = usernamesStr.split(',').map(u => u.trim()).filter(Boolean);
+                    if (usernames.length === 0)
+                        return { callId: '', success: false, result: null, error: 'No valid usernames provided' };
+                    const result = await x.getUsersByUsernames(usernames);
+                    const users = result.data ?? [];
+                    if (users.length === 0)
+                        return { callId: '', success: true, result: 'No users found.' };
+                    const lines = users.map(formatUser);
+                    return { callId: '', success: true, result: `${users.length} users:\n${lines.join('\n')}` };
+                }
+                // ==================================================================
+                // Media upload
+                // ==================================================================
+                case 'upload_media': {
+                    const mediaUrl = params.media_url;
+                    if (!mediaUrl)
+                        return { callId: '', success: false, result: null, error: 'media_url is required for upload_media' };
+                    const result = await x.uploadMediaFromUrl({
+                        url: mediaUrl,
+                        mimeType: params.media_type,
+                    });
+                    return {
+                        callId: '',
+                        success: true,
+                        result: `Media uploaded. media_id: ${result.media_id_string}\nUse this ID with post_with_media or post_tweet.`,
+                        metadata: { media_id: result.media_id_string },
+                    };
+                }
+                case 'post_with_media': {
+                    const text = params.text;
+                    const mediaUrl = params.media_url;
+                    if (!text)
+                        return { callId: '', success: false, result: null, error: 'text is required for post_with_media' };
+                    if (!mediaUrl)
+                        return { callId: '', success: false, result: null, error: 'media_url is required for post_with_media' };
+                    // Upload media first
+                    const media = await x.uploadMediaFromUrl({
+                        url: mediaUrl,
+                        mimeType: params.media_type,
+                    });
+                    // Post tweet with media
+                    const opts = { text, mediaIds: [media.media_id_string] };
+                    if (params.reply_to)
+                        opts.replyTo = params.reply_to;
+                    if (params.quote)
+                        opts.quoteTweetId = params.quote;
+                    const result = await x.postTweet(opts);
+                    const tweet = result.data;
+                    return {
+                        callId: '',
+                        success: true,
+                        result: `Posted tweet with media ${tweet.id}: ${tweet.text}\nhttps://x.com/i/status/${tweet.id}`,
+                        metadata: { tweet_id: tweet.id, media_id: media.media_id_string },
+                    };
+                }
+                // ==================================================================
+                // New: Streaming
+                // ==================================================================
+                case 'stream_start': {
+                    const durationSec = Math.min(params.stream_duration ?? 30, 300);
+                    // Stop any active stream first
+                    x.stopStream();
+                    const tweets = await x.streamFiltered({
+                        durationMs: durationSec * 1000,
+                        maxTweets: 50,
+                    });
+                    if (tweets.length === 0) {
+                        return { callId: '', success: true, result: 'Stream completed. No tweets matched your filter rules. Set rules with stream_rules_set first.' };
+                    }
+                    const lines = tweets.map(formatTweet);
+                    return {
+                        callId: '',
+                        success: true,
+                        result: `Streamed ${tweets.length} tweets in ${durationSec}s:\n${lines.join('\n')}`,
+                        metadata: { tweet_count: tweets.length, duration_sec: durationSec },
+                    };
+                }
+                case 'stream_stop': {
+                    x.stopStream();
+                    return { callId: '', success: true, result: 'Stream stopped.' };
+                }
+                case 'stream_rules_set': {
+                    const rulesJson = params.stream_rules;
+                    if (!rulesJson)
+                        return { callId: '', success: false, result: null, error: 'stream_rules (JSON array) is required for stream_rules_set' };
+                    let rules;
+                    try {
+                        rules = JSON.parse(rulesJson);
+                    }
+                    catch {
+                        return { callId: '', success: false, result: null, error: 'stream_rules is not valid JSON. Must be a JSON array of {value, tag?} objects.' };
+                    }
+                    if (!Array.isArray(rules) || rules.length === 0) {
+                        return { callId: '', success: false, result: null, error: 'stream_rules must be a non-empty JSON array of {value, tag?} objects' };
+                    }
+                    const result = await x.setStreamRules(rules);
+                    const added = result.length ?? 0;
+                    return {
+                        callId: '',
+                        success: true,
+                        result: `Stream rules updated. ${added} rules active.\nRules: ${rules.map(r => `"${r.value}"${r.tag ? ` (${r.tag})` : ''}`).join(', ')}`,
+                        metadata: { rules_count: added },
+                    };
+                }
+                case 'stream_rules_get': {
+                    const rules = await x.getStreamRules();
+                    if (rules.length === 0) {
+                        return { callId: '', success: true, result: 'No stream filter rules configured. Use stream_rules_set to add rules.' };
+                    }
+                    const lines = rules.map((r) => `  ${r.id}: "${r.value}"${r.tag ? ` (${r.tag})` : ''}`);
+                    return { callId: '', success: true, result: `${rules.length} active stream rules:\n${lines.join('\n')}` };
+                }
+                // ==================================================================
+                // New: Action chaining
+                // ==================================================================
+                case 'action_chain': {
+                    const stepsJson = params.chain_steps;
+                    if (!stepsJson)
+                        return { callId: '', success: false, result: null, error: 'chain_steps (JSON array) is required for action_chain' };
+                    let steps;
+                    try {
+                        steps = JSON.parse(stepsJson);
+                    }
+                    catch {
+                        return { callId: '', success: false, result: null, error: 'chain_steps is not valid JSON. Must be a JSON array of action objects.' };
+                    }
+                    if (!Array.isArray(steps) || steps.length === 0) {
+                        return { callId: '', success: false, result: null, error: 'chain_steps must be a non-empty JSON array of action objects' };
+                    }
+                    const results = [];
+                    let prevTweetId = null;
+                    for (let i = 0; i < steps.length; i++) {
+                        const step = { ...steps[i] };
+                        // Replace PREV_TWEET_ID placeholder with actual tweet ID from previous step
+                        for (const [key, val] of Object.entries(step)) {
+                            if (val === 'PREV_TWEET_ID') {
+                                if (!prevTweetId) {
+                                    results.push(`Step ${i + 1} (${step.action}): FAILED — references PREV_TWEET_ID but no previous step produced a tweet ID`);
+                                    return {
+                                        callId: '',
+                                        success: false,
+                                        result: `Action chain halted at step ${i + 1}:\n${results.join('\n')}`,
+                                        error: `Step ${i + 1} references PREV_TWEET_ID but no previous step produced a tweet ID`,
+                                    };
+                                }
+                                step[key] = prevTweetId;
+                            }
+                        }
+                        // Recursively execute each step through this same skill
+                        const stepResult = await clawnxSkill.execute(step, {});
+                        results.push(`Step ${i + 1} (${step.action}): ${stepResult.success ? 'OK' : 'FAILED'} — ${stepResult.result ?? stepResult.error}`);
+                        // Extract tweet ID for chaining
+                        if (stepResult.metadata?.tweet_id) {
+                            prevTweetId = stepResult.metadata.tweet_id;
+                        }
+                        else if (stepResult.metadata?.first_tweet_id) {
+                            prevTweetId = stepResult.metadata.first_tweet_id;
+                        }
+                        // Stop chain on failure
+                        if (!stepResult.success) {
+                            results.push(`Chain halted at step ${i + 1}.`);
+                            break;
+                        }
+                    }
+                    return {
+                        callId: '',
+                        success: true,
+                        result: `Action chain completed (${steps.length} steps):\n${results.join('\n')}`,
+                        metadata: { steps_executed: results.length, last_tweet_id: prevTweetId },
+                    };
+                }
                 default:
                     return {
                         callId: '',
                         success: false,
                         result: null,
-                        error: `Unknown ClawnX action: "${action}". Valid: post_tweet, post_thread, search, get_tweet, like, retweet, follow, get_user, get_mentions, get_timeline, get_my_profile, delete_tweet.`,
+                        error: `Unknown ClawnX action: "${action}". Valid actions: ` +
+                            'Content: post_tweet, post_thread, post_with_media, upload_media, delete_tweet, get_tweet, search. ' +
+                            'Engagement: like, unlike, retweet, unretweet, bookmark, unbookmark, list_bookmarks, list_likes, liking_users, retweeted_by, quote_tweets. ' +
+                            'Social: follow, unfollow, list_followers, list_following, block, unblock, mute, unmute, list_blocked, list_muted, get_user, search_users, lookup_users. ' +
+                            'Timelines: get_timeline, home_timeline, get_mentions, get_my_profile, get_tweet_metrics. ' +
+                            'DMs: send_dm, send_dm_to_conversation, list_dms, get_dm_conversation. ' +
+                            'Threads: get_conversation. ' +
+                            'Lists: create_list, delete_list, get_list, get_user_lists, add_list_member, remove_list_member, list_members, list_tweets. ' +
+                            'Streaming: stream_start, stream_stop, stream_rules_set, stream_rules_get. ' +
+                            'Orchestration: action_chain.',
                     };
             }
         }