yappr 0.1.0

package/config/skills/generate-image/handler.ts

@@ -0,0 +1,133 @@
+import { payFetch, log, type SkillHandler } from "yappr";
+
+// Generate an image from a prompt via BlockRun's x402 image gateway, then hand the
+// asker the resulting URL. payFetch signs the EIP-3009 payment on Base automatically
+// (same wallet as every other agent spend), so this module just speaks plain HTTP.
+
+const ORIGIN = "https://blockrun.ai";
+const ENDPOINT = `${ORIGIN}/api/v1/images/generations`;
+
+// Available image models and their x402 price (USDC on Base, quoted at 1024x1024, 1
+// image — prices are dynamic and non-square sizes may cost more). gpt-image-1 is the
+// cheapest frontier model and what we use here; swap MODEL to trade cost for quality:
+//   openai/gpt-image-1          $0.021
+//   openai/gpt-image-2          $0.063
+//   google/nano-banana          $0.053
+//   google/nano-banana-pro      $0.105
+//   zai/cogview-4               $0.016
+//   xai/grok-imagine-image      $0.021
+//   xai/grok-imagine-image-pro  $0.074
+const MODEL = "openai/gpt-image-1"; // $0.021 / image (1024x1024)
+
+// Orientation keyword → the pixel dimensions sent to the endpoint as `size`. Square is
+// the default when the caller gives no (or an unrecognised) size.
+// gpt-image-1 only accepts these three sizes (1024x1024, 1536x1024, 1024x1536) — the
+// 1792-wide DALL·E 3 sizes are rejected. Update these if you switch MODEL.
+const SIZES: Record<string, string> = {
+  square: "1024x1024",
+  landscape: "1536x1024",
+  portrait: "1024x1536",
+};
+const DEFAULT_SIZE = "square";
+
+// Map a caller-supplied size to a dimension string: a known orientation keyword, an
+// explicit WxH the endpoint already understands, or — failing both — the square default.
+function resolveSize(raw: string | undefined): string {
+  const key = (raw ?? "").trim().toLowerCase();
+  if (key in SIZES) return SIZES[key];
+  if (/^\d{3,4}x\d{3,4}$/.test(key)) return key;
+  return SIZES[DEFAULT_SIZE];
+}
+
+// gpt-image-1 routinely runs past the server's 30s inline window: the POST then returns
+// a queued job instead of the image, and we poll it to completion. Bound the wait so a
+// stuck job can't hang the reply loop forever.
+const POST_TIMEOUT_MS = 60_000; // POST holds inline up to ~30s before handing back a job
+const POLL_TIMEOUT_MS = 30_000; // per-poll request timeout
+const POLL_INTERVAL_MS = 5_000; // pause between polls
+const POLL_MAX_ATTEMPTS = 24; // ~2 min of polling after the inline window
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+// BlockRun returns the image under data[0].url on both the inline and the completed-poll
+// responses; absent until the job finishes.
+function imageUrl(body: any): string | undefined {
+  return body?.data?.[0]?.url;
+}
+
+// Returned as `mediaUrl` on success: the reply pipeline uploads it to X and attaches it
+// to the reply, so the model should caption the image rather than paste a URL.
+const GENERATED_NOTE =
+  "Image generated — it will be attached to your reply automatically. Write a short caption for it and do NOT include any URL in your reply.";
+
+export const handler: SkillHandler = async (params) => {
+  const prompt = (params.prompt ?? "").trim();
+  if (!prompt) return { text: "missing prompt — describe the image to generate" };
+  const size = resolveSize(params.size ?? params.orientation);
+
+  // 1) Kick off generation. The server holds the request inline for up to ~30s: if the
+  // image is ready it comes back directly, otherwise we get a queued job to poll.
+  let body: any;
+  try {
+    const res = await payFetch(ENDPOINT, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ prompt, model: MODEL, size }),
+      signal: AbortSignal.timeout(POST_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+      const detail = await res.text().catch(() => "");
+      log.warn({ status: res.status, detail }, "generate-image: POST failed");
+      return { text: `image generation failed (HTTP ${res.status})` };
+    }
+    body = await res.json();
+  } catch (err) {
+    log.warn({ err: err instanceof Error ? err.message : String(err) }, "generate-image: POST errored");
+    return { text: "image generation failed — the request errored before any image was produced" };
+  }
+
+  // 2a) Fast path — the image came back inline within the 30s window.
+  const inline = imageUrl(body);
+  if (inline) {
+    log.info({ model: MODEL, size, url: inline }, "generate-image: inline result");
+    return { text: GENERATED_NOTE, mediaUrl: inline };
+  }
+
+  // 2b) Slow path — poll the job until it completes. payFetch re-signs the poll's x402
+  // challenge each time; BlockRun only settles the charge on the first completed poll
+  // (the unused authorizations for in-progress polls are never submitted on-chain), so
+  // polling does not double-bill. The poll must come from the same wallet as the POST,
+  // which it always does (one agent wallet).
+  const pollPath = body?.poll_url as string | undefined;
+  if (!pollPath) {
+    log.warn({ body }, "generate-image: no image and no poll_url to follow");
+    return { text: "image generation failed — no image and no job to poll" };
+  }
+  const pollUrl = new URL(pollPath, ORIGIN).toString();
+  log.info({ jobId: body?.id, status: body?.status, size, pollUrl }, "generate-image: job queued, polling");
+
+  for (let attempt = 1; attempt <= POLL_MAX_ATTEMPTS; attempt++) {
+    await sleep(POLL_INTERVAL_MS);
+    try {
+      const pr = await payFetch(pollUrl, { method: "GET", signal: AbortSignal.timeout(POLL_TIMEOUT_MS) });
+      const pb: any = await pr.json().catch(() => null);
+      const url = imageUrl(pb);
+      if (url) {
+        log.info({ attempt, url }, "generate-image: completed");
+        return { text: GENERATED_NOTE, mediaUrl: url };
+      }
+      if (pb?.status === "failed") {
+        log.warn({ attempt, body: pb }, "generate-image: job reported failed");
+        return { text: "image generation failed while processing the job" };
+      }
+      log.info({ attempt, status: pb?.status }, "generate-image: still generating");
+    } catch (err) {
+      // A transient poll error (timeout/network) shouldn't abort — the job may still
+      // finish, so log and try the next tick.
+      log.warn({ attempt, err: err instanceof Error ? err.message : String(err) }, "generate-image: poll errored — retrying");
+    }
+  }
+
+  log.warn({ jobId: body?.id }, "generate-image: polling exhausted before completion");
+  return { text: "image generation timed out — the job did not finish in time, try again" };
+};

package/config/skills/generate-image/skill.md

@@ -0,0 +1,20 @@
+---
+name: generate-image
+description: Generate an image from a text prompt and reply with its URL. Use when the user asks you to create, generate, draw, paint, or make an image/picture of something.
+access: admin
+---
+
+Generate an image from a text description using OpenAI `gpt-image-1` (via the BlockRun x402 gateway, paid from the agent wallet — so this costs money per call).
+
+Extract these parameters:
+- `prompt` (required) — the image description, in the user's own words (e.g. "anime style white cat playing on green grass"). Build it from what the user actually asked for; don't invent detail they didn't request.
+- `size` (optional) — the image orientation, one of:
+  - `square` — 1024×1024 (**default** — use this whenever the user doesn't ask for a shape)
+  - `landscape` — 1536×1024 (wide; for "landscape", "wide", "banner")
+  - `portrait` — 1024×1536 (tall; for "portrait", "vertical", "tall", "phone wallpaper")
+
+The skill returns `image_url: <url>` once the image is ready. Generation runs inline for up to ~30s; if it takes longer the skill polls the job in the background, so a call can take up to ~1–2 minutes. Wait for it.
+
+When you get the result back:
+- The generated image is **attached to your reply automatically** — just write a short, natural caption for it. Do **not** paste any URL or link in the reply text.
+- If the skill reports a failure or timeout, tell the user it couldn't generate the image. Never invent or describe an image that wasn't actually generated.

package/config/skills/generate-meme-prompt/handler.ts

@@ -0,0 +1,40 @@
+import { chat, log, type SkillHandler, type ChatMessage } from "yappr";
+
+// generate-meme-prompt: craft a funny, Crypto-Twitter-flavored image PROMPT from a tweet.
+// It does NOT render anything — it returns the prompt for the model to hand to the
+// generate-image skill, which does the actual (paid) rendering and attaches the result.
+// Keeping the two apart means one render path (generate-image) and no duplicated image-gen
+// code here. Use it when the user wants a meme but hasn't described the visual themselves.
+
+// The prompt-crafting brief. Bakes in Crypto Twitter context so the meme lands.
+const MEME_SYSTEM = `You are a Crypto Twitter (CT) meme director. Given the subject of a tweet, write ONE image-generation prompt for a single funny meme image.
+
+- Lean into CT humor and culture where it fits — degens, leverage and liquidations, rugs and exit liquidity, gm/wagmi/ngmi, "ser"/"anon", diamond vs paper hands, copium, "few understand this", and wojak/pepe/chad/virgin-vs-chad visual archetypes. Use what suits the subject; never force every trope in.
+- Describe a clear, vivid visual scene, and specify the EXACT short bold meme caption text to render in the image (impact-font style, just a few words).
+- Funny and a little edgy is good; never hateful, sexual, or harassing toward private individuals.
+- Output ONLY the image prompt itself — no preamble, no quotes, no explanation, no markdown.`;
+
+export const handler: SkillHandler = async (params) => {
+  const subject = (params.subject ?? params.prompt ?? "").trim();
+  if (!subject) return { text: "missing subject — pass the tweet's content/topic to meme about" };
+  const angle = params.angle?.trim() || undefined;
+
+  const user = angle ? `Tweet subject: ${subject}\n\nExtra angle to play on: ${angle}` : `Tweet subject: ${subject}`;
+  const messages: ChatMessage[] = [
+    { role: "system", content: MEME_SYSTEM },
+    { role: "user", content: user },
+  ];
+
+  try {
+    const memePrompt = (await chat(messages)).trim();
+    if (!memePrompt) throw new Error("empty prompt");
+    log.info({ subject, memePrompt }, "generate-meme-prompt: crafted prompt");
+    // Return just the prompt (as data). The chaining — "now call generate-image with this"
+    // — is driven by skill.md (a trusted instruction), since observations are fed to the
+    // model as data, not instructions.
+    return { text: `Meme image prompt (pass verbatim to the generate-image skill's "prompt"):\n\n${memePrompt}` };
+  } catch (err) {
+    log.warn({ err: err instanceof Error ? err.message : String(err) }, "generate-meme-prompt: prompt crafting failed");
+    return { text: "couldn't come up with a meme for that — try again" };
+  }
+};

package/config/skills/generate-meme-prompt/skill.md

@@ -0,0 +1,23 @@
+---
+name: generate-meme-prompt
+description: Invent a funny Crypto-Twitter image prompt for a meme about a tweet — for when the user wants a meme but hasn't said what the image should show. generate-image then renders it. Use for "make a meme", "meme this".
+access: admin
+---
+
+Use this when the user wants a meme about a tweet but **hasn't described what the image should actually show** — it invents the funny visual for you (a cheap LLM call) by writing a Crypto-Twitter-aware image prompt. It does **not** render anything; after it returns the prompt, you call the **generate-image** skill to create the meme and attach it.
+
+**When NOT to use it:** if the user already told you exactly what the image should depict (e.g. "make an image of a green pepe crying at a red chart"), skip this skill and call `generate-image` directly with their description — you don't need help inventing the visual.
+
+Extract these parameters:
+- `subject` (required) — what the meme is about. Pull it from the relevant tweet in the context: quote its key line or summarize the joke/topic, and say *why* it's meme-able.
+- `angle` (optional) — a specific spin if the user asked for one (e.g. "make fun of the leverage", "diamond-hands angle", "him coping"). Omit if there's no particular angle.
+
+Do **not** write the meme prompt yourself — this skill writes it for you.
+
+## How to make the meme (two steps)
+
+1. Call `generate-meme-prompt` with the `subject` (and optional `angle`). It returns a ready-made image prompt.
+2. Then call the **generate-image** skill, setting its `prompt` param to that returned prompt **verbatim** (and a `size` such as `landscape` only if the user asked for a shape). generate-image renders the meme and attaches it to your reply automatically.
+3. Reply with a short, natural caption — do **not** paste any URL or the prompt text.
+
+If `generate-meme-prompt` reports it couldn't come up with anything, tell the user and don't fabricate a meme.

package/config/skills/stats/handler.ts

@@ -0,0 +1,76 @@
+import { summary, getTreasury, llmCreditBalance, log, type SkillHandler } from "yappr";
+
+// stats: the agent's all-time metrics from its own ledger, plus a runway estimate (how
+// long the treasury lasts at the current burn). The runway mirrors the status dashboard's
+// two-tank model: USDC pays x-api + compute + x402, LLM credits pay inference — runway is
+// whichever tank empties first. (Burn math kept in sync with cli/status.ts by hand.)
+
+const RUNWAY_MIN_DATA_HOURS = 1; // trust the measured burn only after this much recorded window
+const X_API_POLL_COST_USD = 0.005; // always-on mentions-poll cost — the cold-start/floor burn
+
+function fmtDuration(hours: number): string {
+  if (!Number.isFinite(hours)) return "∞";
+  if (hours < 1) return `${Math.round(hours * 60)}m`;
+  if (hours < 48) return `${hours.toFixed(1)}h`;
+  return `${(hours / 24).toFixed(1)}d`;
+}
+
+export const handler: SkillHandler = async () => {
+  const s = summary();
+
+  // Burn rates from the trailing window. usdcBurn = x-api+compute+x402 (total minus the
+  // inference slice), floored at the always-on poll cost so downtime can't inflate runway;
+  // llmBurn = inference. Before there's enough recorded window, fall back to the poll-cost
+  // estimate for USDC and treat inference as not-yet-binding.
+  const pollSeconds = Math.round((Number(process.env.POLL_INTERVAL_MS) || 20_000) / 1000);
+  const predictedUsdcBurn = pollSeconds > 0 ? (3600 / pollSeconds) * X_API_POLL_COST_USD : 0;
+  const hasRate = s.rateWindowHours >= RUNWAY_MIN_DATA_HOURS && s.spentUsdWindow > 0;
+  const usdcBurn = hasRate
+    ? Math.max((s.spentUsdWindow - s.inferenceUsdWindow) / s.rateWindowHours, predictedUsdcBurn)
+    : predictedUsdcBurn;
+  const llmBurn = hasRate ? s.inferenceUsdWindow / s.rateWindowHours : 0;
+
+  // Treasury value per tank: the USDC balance (live, on-chain) and the LLM credit balance.
+  let usdcUsd: number | null = null;
+  try {
+    usdcUsd = Number((await getTreasury().balances()).usdc) / 1e6;
+  } catch (err) {
+    log.warn({ err: err instanceof Error ? err.message : String(err) }, "stats: balances fetch failed");
+  }
+  const creditUsd = await llmCreditBalance();
+
+  const usdcRunwayH = usdcBurn > 0 ? (usdcUsd != null ? usdcUsd / usdcBurn : Infinity) : Infinity;
+  const llmRunwayH = llmBurn > 0 ? (creditUsd != null ? creditUsd / llmBurn : Infinity) : Infinity;
+  const runwayHours = Math.min(usdcRunwayH, llmRunwayH);
+  const runwayKnown = usdcUsd != null || creditUsd != null;
+
+  const runway = !runwayKnown
+    ? { available: false as const }
+    : {
+        available: true as const,
+        human: fmtDuration(runwayHours),
+        hours: Number.isFinite(runwayHours) ? Number(runwayHours.toFixed(1)) : null, // null ≈ effectively infinite
+        days: Number.isFinite(runwayHours) ? Number((runwayHours / 24).toFixed(2)) : null,
+        estimated: !hasRate, // cold-start estimate — not enough recorded burn yet
+        limitedBy: usdcRunwayH <= llmRunwayH ? "usdc" : "llm-credits",
+        usdcBalanceUsd: usdcUsd,
+        llmCreditUsd: creditUsd,
+        usdcBurnUsdPerHour: Number(usdcBurn.toFixed(4)),
+        llmBurnUsdPerHour: Number(llmBurn.toFixed(4)),
+      };
+
+  return {
+    data: {
+      mentions: s.mentions,
+      replies: s.replies,
+      llmCalls: s.llm,
+      // warns/errors are deliberately omitted — internal health metrics, not user-facing
+      // (and this skill is public). They stay in summary() for the admin status dashboard.
+      spentUsd: Number(s.spentUsd.toFixed(4)),
+      spentByType: s.spentByType, // { "x-api", inference, compute, x402 }
+      earnedWeth: s.earnedWeth, // lifetime gross creator fees, in ETH/WETH
+      devWeth: s.devWeth, // dev cut within earnedWeth
+      runway,
+    },
+  };
+};

package/config/skills/stats/skill.md

@@ -0,0 +1,18 @@
+---
+name: stats
+description: Report the agent's all-time stats — mentions handled, replies, LLM calls, total spent, earned — plus a live runway estimate (how long the treasury lasts at the current burn). Use when asked "your stats", "how are you doing", "how much have you spent/earned", "what's your runway".
+access: all
+---
+
+Returns the agent's lifetime metrics from its own ledger, plus a live runway estimate. Call it with no params. It returns structured data:
+
+- `mentions`, `replies`, `llmCalls` — lifetime counts.
+- `spentUsd` — total USD spent, with `spentByType` broken out into `x-api`, `inference`, `compute` and `x402`.
+- `earnedWeth` — lifetime gross creator fees, in **ETH/WETH**; `devWeth` is the dev cut within it.
+- `runway` — how long the treasury lasts at the current burn (ignores incoming earnings):
+  - `human` — a ready string like `"12.5d"`, `"8.0h"`, or `"∞"`; plus `hours` and `days` numbers (both `null` when effectively infinite).
+  - `estimated: true` — a cold-start estimate (not enough recorded burn yet); say "roughly".
+  - `limitedBy` — the tank that runs out first: `"usdc"` (X data + compute) or `"llm-credits"` (inference).
+  - `available: false` — balances couldn't be read right now; say the runway is temporarily unavailable rather than guessing.
+
+When you reply: present the figures naturally and concisely — you don't have to list every one. Spend is in USD, earnings are in ETH. If the user asked about just one figure (e.g. "what's your runway"), lead with that. Never mention internal health metrics like warnings or error counts — those are operational internals, not something to share.

package/config/skills/wallet/handler.ts

@@ -0,0 +1,56 @@
+import { agentPrompt, type SkillHandler } from "yappr";
+
+// Bankr returns a natural-language response, so we pull transaction hashes out of
+// it and append the right block-explorer link. Hash format tells us the chain:
+//   EVM:    0x + 64 hex chars        -> basescan.org (our EVM actions run on Base)
+//   Solana: base58 signature ~88 chars -> solscan.io
+// (EVM addresses are 0x+40 hex, so they never match the 64-hex tx pattern; Solana
+// addresses are <=44 base58 chars, so they never match the long-signature pattern.)
+const EVM_TX = /0x[0-9a-fA-F]{64}/g;
+const SOL_TX = /\b[1-9A-HJ-NP-Za-km-z]{80,90}\b/g;
+
+function appendTxLinks(text: string): string {
+  const links: string[] = [];
+  const seen = new Set<string>();
+  const add = (hash: string, base: string) => {
+    if (seen.has(hash)) return;
+    seen.add(hash);
+    links.push(`${base}${hash}`);
+  };
+  for (const h of text.match(EVM_TX) ?? []) add(h, "https://basescan.org/tx/");
+  for (const s of text.match(SOL_TX) ?? []) add(s, "https://solscan.io/tx/");
+  if (links.length === 0) return text;
+  return `${text}\n\nTransaction${links.length > 1 ? "s" : ""}:\n${links.join("\n")}`;
+}
+
+export const handler: SkillHandler = async (params, _tweet) => {
+  switch (params.action) {
+    case "claim":
+      return { text: appendTxLinks(await agentPrompt("claim my token fees on base")) };
+
+    case "burn": {
+      const amount = params.amount ?? "50%";
+      return { text: appendTxLinks(await agentPrompt(`burn ${amount} of my tokens on base`)) };
+    }
+
+    case "swap": {
+      const from = params.from ?? "WETH";
+      const to = params.to ?? "USDC";
+      const amount = params.swap_amount ?? "all";
+      return { text: appendTxLinks(await agentPrompt(`swap ${amount} of ${from} to ${to} on base`)) };
+    }
+
+    case "send": {
+      if (!params.send_to) return { text: "missing recipient — specify an address, ENS name, or X @handle" };
+      if (!params.send_amount) return { text: "missing amount — specify how much to send" };
+      const token = params.send_token ?? "ETH";
+      return { text: appendTxLinks(await agentPrompt(`send ${params.send_amount} ${token} to ${params.send_to} on base`)) };
+    }
+
+    case "balance":
+      return { text: await agentPrompt("what are my token balances on base") };
+
+    default:
+      return { text: `unknown action "${params.action}" — try: claim, burn, swap, send, balance` };
+  }
+};

package/config/skills/wallet/skill.md

@@ -0,0 +1,17 @@
+---
+name: wallet
+description: Manage the agent's wallet. Use when the user asks to claim fees, burn tokens, swap tokens, send tokens, or check balances.
+access: admin
+---
+
+Extract these params from the request:
+- action (required): one of "claim", "burn", "swap", "send", "balance"
+- amount (optional): for "burn" — a token amount (e.g. "100"), a percentage (e.g. "50%"), or "all". Defaults to configured burn percentage.
+- from (optional): for "swap" — source token symbol or address
+- to (optional): for "swap" — destination token symbol or address
+- swap_amount (optional): for "swap" — amount or percentage of source token (e.g. "10%", "0.5", "all")
+- send_token (optional): for "send" — token symbol or address to send (e.g. "USDC", "ETH")
+- send_amount (optional): for "send" — amount to send (e.g. "100", "0.5")
+- send_to (optional): for "send" — recipient: wallet address, ENS name, or X handle (e.g. "0x123...", "vitalik.eth", "@someone")
+
+For on-chain actions (claim, burn, swap, send), the skill result includes a block-explorer link for each transaction. Always include the transaction link(s) verbatim in your reply so the user can verify the on-chain action.

package/config/skills/x/handler.ts

@@ -0,0 +1,135 @@
+import {
+  type SkillHandler, type SkillResult,
+  extractTweetId,
+  getTweetById, getUserTweets, searchTweets,
+  getTweetReplies, getRetweetedBy, getQuoteTweets,
+  postTweet, deleteTweet,
+  likeTweet, unlikeTweet, retweetTweet, unretweetTweet,
+  bookmarkTweet, unbookmarkTweet,
+  getUserByUsername, getUserById, getUsers, searchUsers,
+  getFollowers, getFollowing, followUser, unfollowUser, setProfile,
+  uploadMediaFromUrl,
+  getArticle,
+  getList, getListMembers, getListFollowers, getListTweets,
+  getCommunity, getCommunityMembers, getCommunityPosts,
+  getUserInsights,
+} from "yappr";
+
+type Params = Record<string, string>;
+type Action = (p: Params) => Promise<SkillResult>;
+
+// Wrap an action that needs an id (tweet/user/list/community — accepts a raw id or X URL).
+function withId(label: string, fn: (id: string, p: Params) => Promise<SkillResult>): Action {
+  return (p) => (p.id ? fn(extractTweetId(p.id), p) : Promise.resolve({ text: `missing ${label}` }));
+}
+
+// Wrap a write action that just acknowledges success with a short message.
+function ack(label: string, fn: (id: string) => Promise<void>, verb: string): Action {
+  return withId(label, async (id) => {
+    await fn(id);
+    return { text: `${verb} ${id}` };
+  });
+}
+
+const ID = "tweet id or URL";
+
+// Upload one or more image URLs (comma-separated) to X and return their media_ids to
+// attach to a post. Bounded to X's 4-images-per-tweet limit.
+async function uploadMediaUrls(raw?: string): Promise<string[] | undefined> {
+  const urls = (raw ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  if (urls.length === 0) return undefined;
+  const ids: string[] = [];
+  for (const url of urls.slice(0, 4)) ids.push(await uploadMediaFromUrl(url));
+  return ids.length ? ids : undefined;
+}
+
+const actions: Record<string, Action> = {
+  // ── tweets (read) ──
+  "tweet": withId(ID, async (id) => ({ data: await getTweetById(id) })),
+  "tweet-search": async (p) => ({
+    data: await searchTweets({
+      words: p.words ?? p.query, phrase: p.phrase, anyWords: p.any_words, noneWords: p.none_words,
+      hashtags: p.hashtags, from: p.from, to: p.to, mentioning: p.mentioning,
+      minReplies: p.min_replies ? Number(p.min_replies) : undefined,
+      minLikes: p.min_likes ? Number(p.min_likes) : undefined,
+      minReposts: p.min_reposts ? Number(p.min_reposts) : undefined,
+      since: p.since, until: p.until,
+    }),
+  }),
+  "tweet-replies": withId(ID, async (id) => ({ data: await getTweetReplies(id) })),
+  "tweet-retweeters": withId(ID, async (id) => ({ data: await getRetweetedBy(id) })),
+  "tweet-quotes": withId(ID, async (id) => ({ data: await getQuoteTweets(id) })),
+  "timeline": async (p) => (p.username ? { data: await getUserTweets(p.username) } : { text: "missing username" }),
+
+  // ── tweets (write) ──
+  "post": async (p) => {
+    if (!p.text) return { text: "missing tweet text" };
+    await postTweet(p.text, {
+      replyTo: p.reply_to ? extractTweetId(p.reply_to) : undefined,
+      quoteTweetId: p.quote_id ? extractTweetId(p.quote_id) : undefined,
+      mediaIds: await uploadMediaUrls(p.media_url),
+    });
+    return { text: "posted" };
+  },
+  "delete": ack(ID, deleteTweet, "deleted"),
+  "like": ack(ID, likeTweet, "liked"),
+  "unlike": ack(ID, unlikeTweet, "unliked"),
+  "retweet": ack(ID, retweetTweet, "retweeted"),
+  "unretweet": ack(ID, unretweetTweet, "unretweeted"),
+  "bookmark": ack(ID, bookmarkTweet, "bookmarked"),
+  "unbookmark": ack(ID, unbookmarkTweet, "removed bookmark"),
+
+  // ── users (read) ──
+  "user": async (p) => {
+    if (!p.username && !p.id) return { text: "missing username or id" };
+    return { data: p.username ? await getUserByUsername(p.username) : await getUserById(p.id) };
+  },
+  "users": async (p) => {
+    const ids = (p.ids ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    return ids.length ? { data: await getUsers(ids) } : { text: "missing ids (comma-separated numeric user IDs)" };
+  },
+  "user-search": async (p) => (p.query ? { data: await searchUsers(p.query) } : { text: "missing search query" }),
+  "followers": withId("user id", async (id) => ({ data: await getFollowers(id) })),
+  "following": withId("user id", async (id) => ({ data: await getFollowing(id) })),
+
+  // ── users (write) ──
+  "follow": async (p) => {
+    if (!p.username && !p.id) return { text: "missing username or id" };
+    await followUser({ id: p.id, username: p.username });
+    return { text: `followed ${p.username ?? p.id}` };
+  },
+  "unfollow": async (p) => {
+    if (!p.username && !p.id) return { text: "missing username or id" };
+    await unfollowUser({ id: p.id, username: p.username });
+    return { text: `unfollowed ${p.username ?? p.id}` };
+  },
+  "set-profile": async (p) => {
+    // All four fields are required (a profile set replaces the whole thing). `name` must
+    // be non-empty; bio/location/url may be an empty string, which CLEARS that field on X.
+    for (const f of ["name", "bio", "location", "url"] as const) {
+      if (p[f] === undefined) {
+        return { text: "set-profile requires all of: name, bio, location, url (pass an empty string for bio/location/url to clear them)" };
+      }
+    }
+    if (p.name.trim() === "") return { text: "name cannot be empty" };
+    await setProfile({ name: p.name, bio: p.bio, location: p.location, url: p.url });
+    return { text: "profile updated" };
+  },
+
+  // ── other ──
+  "article": withId(ID, async (id) => ({ data: await getArticle(id) })),
+  "list": withId("list id", async (id) => ({ data: await getList(id) })),
+  "list-members": withId("list id", async (id) => ({ data: await getListMembers(id) })),
+  "list-followers": withId("list id", async (id) => ({ data: await getListFollowers(id) })),
+  "list-tweets": withId("list id", async (id) => ({ data: await getListTweets(id) })),
+  "community": withId("community id", async (id) => ({ data: await getCommunity(id) })),
+  "community-members": withId("community id", async (id) => ({ data: await getCommunityMembers(id) })),
+  "community-posts": withId("community id", async (id) => ({ data: await getCommunityPosts(id) })),
+  "user-insights": async (p) => (p.username ? { data: await getUserInsights(p.username) } : { text: "missing username" }),
+};
+
+export const handler: SkillHandler = async (params) => {
+  const action = actions[params.action];
+  if (!action) return { text: `unknown action "${params.action}"` };
+  return action(params);
+};