yappr 0.1.0

package/config/skills/x/skill.md

@@ -0,0 +1,163 @@
+---
+name: x
+description: Read or search tweets and users, post, engage (like/retweet/bookmark/follow), and pull lists, communities, articles, or deep user analysis on X/Twitter. Use whenever the user asks to look something up on X or to act on their account.
+access: admin
+---
+
+Pick exactly one `action` from the list below and pass it (plus its parameters) in `params` when you call this skill, e.g. `params: {"action":"<action>", ...}`.
+
+Shared parameters:
+- `id` — a tweet, user, list, or community ID. A full X URL also works (e.g. `https://x.com/user/status/123456`); the ID is extracted automatically.
+- `username` — a handle written without the leading `@`.
+
+---
+
+## Tweets — read
+
+### tweet
+Get one tweet's full data (text, author, engagement metrics).
+- When: the user points at a single tweet or URL and wants its content or stats.
+- `id` (required) — the tweet ID or URL.
+
+### tweet-search
+Search recent tweets by keyword and filters. This is the action for "find/search tweets about …".
+- When: "find tweets about X", "what are people saying about Y", "search posts from Z this week".
+- Put the user's plain search terms in `words`. All parameters are optional — combine the ones that match the request:
+  - `words` — all of these words must appear. **This is the default keyword field — use it for a normal search.**
+  - `phrase` — match this exact phrase.
+  - `any_words` — match if any one of these words appears.
+  - `none_words` — exclude tweets containing these words.
+  - `hashtags` — required hashtags, without the `#`.
+  - `from` — only tweets authored by this handle.
+  - `to` — only tweets that are replies to this handle.
+  - `mentioning` — only tweets that mention this handle.
+  - `min_likes` / `min_replies` / `min_reposts` — minimum engagement, as numbers.
+  - `since` / `until` — date bounds in `YYYY-MM-DD` form.
+
+### tweet-replies
+List the replies under a tweet.
+- When: "what are people replying", "show the replies to this".
+- `id` (required) — the tweet being replied to.
+
+### tweet-retweeters
+List the users who reposted a tweet.
+- When: "who retweeted this".
+- `id` (required).
+
+### tweet-quotes
+List quote-tweets of a tweet.
+- When: "who quoted this", "show the quote tweets".
+- `id` (required).
+
+### timeline
+Fetch a user's recent tweets.
+- When: "show me what @user has been posting", "latest tweets from this account".
+- `username` (required).
+
+## Tweets — write
+
+### post
+Publish a new tweet, a reply, or a quote tweet.
+- When: the user asks to tweet, reply, or quote something.
+- `text` (required) — the tweet body.
+- `reply_to` (optional) — a tweet ID/URL to reply under.
+- `quote_id` (optional) — a tweet ID/URL to quote.
+- `media_url` (optional) — an image URL to attach (or several, comma-separated, up to 4). Each is uploaded to X automatically and embedded in the post.
+
+### delete
+Delete one of the agent's own tweets.
+- `id` (required) — the tweet to delete.
+
+### like / unlike
+Like or remove a like from a tweet.
+- `id` (required).
+
+### retweet / unretweet
+Repost a tweet or undo a repost.
+- `id` (required).
+
+### bookmark / unbookmark
+Add or remove a bookmark.
+- `id` (required).
+
+## Users — read
+
+### user
+Look up a single user's profile (bio, metrics, ID).
+- When: "who is @x", "show me this account", or to resolve a handle into a numeric user ID for `followers`/`following`.
+- Provide either `username` or `id`.
+
+### users
+Look up several users at once by numeric ID (one batched call).
+- When: you already hold a list of numeric user IDs (e.g. from `followers`/`retweeters`) and want their profiles together.
+- `ids` (required) — comma-separated **numeric user IDs** (not handles).
+
+### user-search
+Search for users by keyword.
+- When: "find accounts about X", "search for people who do Y".
+- `query` (required) — the search keywords.
+
+### followers
+List a user's followers.
+- When: "who follows this account".
+- `id` (required) — the **numeric user ID** (not a handle). If you only have a handle, call `user` first to get the ID.
+
+### following
+List who a user follows.
+- When: "who does this account follow".
+- `id` (required) — the **numeric user ID**; resolve a handle via `user` first.
+
+## Users — write
+
+### follow / unfollow
+Follow or unfollow an account.
+- Provide either `username` or `id`.
+
+### set-profile
+Update the agent's own X profile. **All four fields are required** — a profile update replaces the whole profile, so always include every field, even ones you're keeping the same (carry over the current value).
+- `name` (required) — display name. **Cannot be empty.**
+- `bio` (required) — profile bio/description. Pass an empty string `""` to clear it.
+- `location` (required) — profile location. Pass an empty string `""` to clear it.
+- `url` (required) — profile website URL. Pass an empty string `""` to clear it.
+
+## Other
+
+### article
+Get the full text of an X article (long-form post).
+- When: the tweet you're asked about is an X article — its `entities.urls` expands to an `x.com/i/article/…` link.
+- `id` (required) — the **tweet ID of the article tweet**, resolved like any other tweet ID:
+  - If that article tweet is the one in front of you (its own `entities.urls` expands to `x.com/i/article/…`), use that tweet's own `id` field.
+  - If you're following a link to the article, use the `…/status/<id>` ID extracted from that URL (the same as for the `tweet` action).
+  - ⚠️ Never use the number inside the `x.com/i/article/<id>` link itself — that is a separate internal article ID, not a tweet ID, and the fetch will fail.
+
+### list
+Get a list's details.
+- `id` (required) — the list ID.
+
+### list-members
+Members of a list.
+- `id` (required) — the list ID.
+
+### list-followers
+Followers of a list.
+- `id` (required) — the list ID.
+
+### list-tweets
+Recent tweets posted to a list.
+- `id` (required) — the list ID.
+
+### community
+Get a community's details.
+- `id` (required) — the community ID.
+
+### community-members
+Members of a community.
+- `id` (required) — the community ID.
+
+### community-posts
+Recent posts in a community.
+- `id` (required) — the community ID.
+
+### user-insights
+Deep analysis of a user, including monthly tweet volume. Slow — takes 30–90s, so only use it when the user explicitly asks for an in-depth breakdown of an account.
+- `username` (required).

package/dist/config/hooks/example.d.ts

@@ -0,0 +1,2 @@
+import type { AgentHooks } from "yappr";
+export declare const hooks: AgentHooks;

package/dist/config/hooks/example.js

@@ -0,0 +1,37 @@
+export const hooks = {
+// onMention: async (tweet) => {
+//   console.log(`mention from @${tweet.author?.username}: ${tweet.text.slice(0, 80)}`);
+// },
+// Return false to skip replying to this tweet.
+// shouldReply: (tweet) => {
+//   const blocked = ["spambot"];
+//   return !blocked.includes(tweet.author?.username?.toLowerCase() ?? "");
+// },
+// Mutate the question or context before it reaches the LLM. Also receives the
+// asker tweet, for per-user logic — see user-memory.ts for a real example.
+// onBeforeInference: async ({ tweet, question, context }) => {
+//   return { question, context };
+// },
+// Post-process the LLM output before it is sent.
+// onAfterInference: async ({ output }) => {
+//   return output;
+// },
+// Mutate the reply text or return null to cancel sending.
+// onBeforeReply: async ({ text }) => {
+//   return text;
+//   // return `${text}\n\npowered by x402`; // append footer
+//   // return null; // veto
+// },
+// onAfterReply: async ({ tweet, text }) => {
+//   console.log(`replied to ${tweet.id}: ${text.slice(0, 80)}`);
+// },
+// onBeforeClaim: async (balances) => {
+//   console.log("treasury cycle starting", balances);
+// },
+// onAfterClaim: async (result) => {
+//   console.log("treasury cycle done", result);
+// },
+// onSwap: async ({ kind, amount }) => {
+//   console.log(`treasury swap: ${kind} ${amount.toString()}`);
+// },
+};

package/dist/config/hooks/holder.d.ts

@@ -0,0 +1,2 @@
+import { type AgentHooks } from "yappr";
+export declare const hooks: AgentHooks;

package/dist/config/hooks/holder.js

@@ -0,0 +1,147 @@
+import { agentPrompt, skillStore, log, config } from "yappr";
+// Holder context. Resolves the asker's Bankr wallet address (via a Bankr
+// agent job — their wallet is custodied by Bankr, keyed to their X handle) and
+// their on-chain balance of the agent's own token, then injects both into the
+// prompt context so the model knows whether it's talking to a holder.
+// Delete this file to disable — nothing in the engine depends on it.
+//
+// Cost model:
+//   - The agent-job lookup runs in Max Mode (billed from LLM credits per
+//     request — see agent-prompt.ts), so it fires ONCE per user: a resolved
+//     address is stored forever; a "no Bankr account" result is retried only
+//     after NO_WALLET_RETRY_MS.
+//   - The balance is a free public-RPC read, cached for BALANCE_TTL_MS so a
+//     chatty user doesn't trigger a call per mention.
+// Storage is the shared SQLite DB via skillStore("bankr-wallet"), so both
+// caches survive restarts/redeploys and ride along in backups.
+const BALANCE_TTL_MS = 3_600_000; // re-check holdings at most hourly
+const NO_WALLET_RETRY_MS = 24 * 3_600_000; // re-ask Bankr for no-wallet users daily
+// Cap on how long a reply waits for a first-time wallet lookup. The Bankr job
+// usually answers in ~10-20s; past the cap the reply proceeds without the block
+// and the still-running job stores its result for the user's next mention.
+const RESOLVE_TIMEOUT_MS = 45_000;
+const BASE_RPC = process.env.BASE_RPC_URL || "https://mainnet.base.org";
+const TOKEN_DECIMALS = 18; // Bankr launches are fixed 18-decimal Clanker deploys
+const store = skillStore("bankr-wallet");
+// One lookup per user even when mentions arrive back-to-back.
+const inflight = new Map();
+function resolveWallet(userId, handle) {
+    const cached = store.getJSON(`wallet:${userId}`);
+    if (cached?.address)
+        return Promise.resolve(cached.address);
+    if (cached && Date.now() - cached.at < NO_WALLET_RETRY_MS)
+        return Promise.resolve(null);
+    const running = inflight.get(userId);
+    if (running)
+        return running;
+    const p = (async () => {
+        try {
+            const text = await agentPrompt(`What is the EVM wallet address of the X user @${handle}? ` +
+                `Reply with only the address, or the word "none" if they have no Bankr account.`);
+            const address = text.match(/0x[a-fA-F0-9]{40}/)?.[0] ?? null;
+            // Negative results are cached too (with a retry window) — without that,
+            // every mention from a wallet-less user would burn a paid agent job.
+            store.setJSON(`wallet:${userId}`, { address, at: Date.now() });
+            log.info({ user: handle, address }, "holder: resolved bankr wallet");
+            return address;
+        }
+        catch (err) {
+            // Transient failure — store nothing so the next mention retries.
+            log.warn({ user: handle, err: err instanceof Error ? err.message : String(err) }, "holder: wallet lookup failed");
+            return null;
+        }
+        finally {
+            inflight.delete(userId);
+        }
+    })();
+    inflight.set(userId, p);
+    return p;
+}
+// Bare-bones eth_call helper (no client dependency needed for two views).
+async function ethCall(to, data) {
+    const res = await fetch(BASE_RPC, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_call", params: [{ to, data }, "latest"] }),
+        signal: AbortSignal.timeout(10_000),
+    });
+    const body = (await res.json());
+    return body.result && /^0x[0-9a-fA-F]*$/.test(body.result) ? body.result : null;
+}
+// The token's ticker via symbol() — fetched once, then stored forever (it's
+// immutable on-chain). Falls back to "your token" until the read succeeds.
+async function tokenSymbol() {
+    const cached = store.get("meta:symbol");
+    if (cached)
+        return cached;
+    try {
+        const hex = await ethCall(config.tokenAddress, "0x95d89b41"); // symbol()
+        if (hex && hex.length >= 2 + 64 * 2) {
+            // Standard ABI string return: 32-byte offset, 32-byte length, then data.
+            const len = Number(BigInt("0x" + hex.slice(2 + 64, 2 + 128)));
+            const symbol = Buffer.from(hex.slice(2 + 128, 2 + 128 + len * 2), "hex").toString("utf8").trim();
+            if (symbol) {
+                store.set("meta:symbol", symbol);
+                return symbol;
+            }
+        }
+    }
+    catch { /* fall through */ }
+    return "your token";
+}
+// balanceOf(holder) via raw eth_call.
+async function fetchBalance(holder) {
+    const data = "0x70a08231" + holder.slice(2).toLowerCase().padStart(64, "0");
+    const result = await ethCall(config.tokenAddress, data);
+    return result && result !== "0x" ? BigInt(result) : null;
+}
+async function tokenBalance(holder) {
+    const cached = store.getJSON(`balance:${holder}`);
+    if (cached && Date.now() - cached.at < BALANCE_TTL_MS)
+        return BigInt(cached.raw);
+    try {
+        const bal = await fetchBalance(holder);
+        if (bal !== null) {
+            store.setJSON(`balance:${holder}`, { raw: bal.toString(), at: Date.now() });
+            return bal;
+        }
+    }
+    catch { /* fall through to stale */ }
+    return cached ? BigInt(cached.raw) : null; // a stale figure beats none
+}
+// "12.34M" / "5.6K" / "0.42" — compact, the model doesn't need full precision.
+function fmtTokens(v) {
+    const n = Number(v) / 10 ** TOKEN_DECIMALS;
+    if (n === 0)
+        return "0";
+    if (n >= 1e9)
+        return `${(n / 1e9).toFixed(2)}B`;
+    if (n >= 1e6)
+        return `${(n / 1e6).toFixed(2)}M`;
+    if (n >= 1e3)
+        return `${(n / 1e3).toFixed(2)}K`;
+    if (n >= 1)
+        return n.toFixed(2);
+    return n.toPrecision(2);
+}
+export const hooks = {
+    // PREPENDED like the user-memory block, so the current ask (ASKER TWEET)
+    // stays last and most salient.
+    async onBeforeInference({ tweet, question, context }) {
+        const userId = tweet.author?.id;
+        const handle = tweet.author?.username;
+        if (!userId || !handle)
+            return { question, context };
+        const address = await Promise.race([
+            resolveWallet(userId, handle),
+            new Promise((res) => setTimeout(res, RESOLVE_TIMEOUT_MS)),
+        ]);
+        if (!address)
+            return { question, context };
+        const [balance, symbol] = await Promise.all([tokenBalance(address), tokenSymbol()]);
+        const block = `=== ASKER BANKR WALLET ===\n` +
+            `@${handle}'s Bankr wallet address: ${address}\n` +
+            `Their balance of ${symbol === "your token" ? symbol : `$${symbol}`} (your token): ${balance !== null ? fmtTokens(balance) : "unknown"}`;
+        return { question, context: context ? `${block}\n\n${context}` : block };
+    },
+};

package/dist/config/hooks/user-memory.d.ts

@@ -0,0 +1,2 @@
+import { type AgentHooks } from "yappr";
+export declare const hooks: AgentHooks;

package/dist/config/hooks/user-memory.js

@@ -0,0 +1,79 @@
+import { skillStore, log } from "yappr";
+const MAX_EXCHANGES = 50; // per user, oldest dropped first
+const MAX_TEXT = 280; // per side of an exchange, to bound prompt tokens
+const mem = skillStore("user-memory");
+const load = (userId) => mem.getJSON(userId) ?? [];
+const clip = (s) => s.length > MAX_TEXT ? s.slice(0, MAX_TEXT - 1) + "…" : s;
+// "2026-06-11 14:03" — minute granularity is plenty for the model.
+const stamp = (at) => new Date(at).toISOString().slice(0, 16).replace("T", " ");
+function toExchange(t) {
+    const parsed = Date.parse(t.created_at);
+    return {
+        id: t.id,
+        at: Number.isNaN(parsed) ? Date.now() : parsed,
+        text: clip(t.text),
+        conversationId: t.conversation_id || undefined,
+        replyToId: t.referenced_tweets?.find((r) => r.type === "replied_to")?.id,
+        replyToUser: t.in_reply_to_screen_name ?? undefined,
+    };
+}
+// One exchange → one or two compact lines:
+//   [2026-06-11 14:03] them (tweet 12, conv 10, replying to @bob in 11): gm what's mcap?
+//     you replied: …
+function render(e) {
+    const where = [
+        `tweet ${e.id}`,
+        e.conversationId ? `conv ${e.conversationId}` : null,
+        e.replyToId || e.replyToUser
+            ? `replying to ${[e.replyToUser && `@${e.replyToUser}`, e.replyToId && `in ${e.replyToId}`].filter(Boolean).join(" ")}`
+            : null,
+    ].filter(Boolean).join(", ");
+    const lines = [`[${stamp(e.at)}] them (${where}): ${e.text}`];
+    if (e.agent)
+        lines.push(`  you replied: ${e.agent}`);
+    return lines.join("\n");
+}
+export const hooks = {
+    // Record every incoming mention (even ones gating later skips) under the
+    // author's id — stable across handle renames.
+    onMention(t) {
+        const uid = t.author?.id;
+        if (!uid)
+            return;
+        const exchanges = load(uid);
+        if (exchanges.some((e) => e.id === t.id))
+            return; // already recorded — skip
+        exchanges.push(toExchange(t));
+        exchanges.sort((a, b) => a.at - b.at);
+        mem.setJSON(uid, exchanges.slice(-MAX_EXCHANGES));
+    },
+    // Inject the user's past exchanges as a context block, PREPENDED so the
+    // current ask (ASKER TWEET) stays last and most salient — appended memory
+    // reads like the newest message and the model answers it instead. The current
+    // ask is already in memory (onMention ran first) but the model sees it as the
+    // ASKER TWEET block, so it's excluded here.
+    onBeforeInference({ tweet, question, context }) {
+        const uid = tweet.author?.id;
+        const past = uid ? load(uid).filter((e) => e.id !== tweet.id) : [];
+        if (past.length === 0)
+            return { question, context };
+        log.debug({ user: tweet.author?.username, exchanges: past.length }, "user-memory: injecting");
+        const block = `=== USER MEMORY: PAST exchanges between you and @${tweet.author?.username} (oldest first) ===\n` +
+            `These happened BEFORE the current request — background for continuity and recall, not part of the current ask.\n` +
+            past.map(render).join("\n");
+        return { question, context: context ? `${block}\n\n${context}` : block };
+    },
+    // Attach our posted answer (the final, possibly hook-edited text) to the
+    // exchange it answered, so memory holds dialogue rather than monologue.
+    onAfterReply({ tweet, text }) {
+        const uid = tweet.author?.id;
+        if (!uid)
+            return;
+        const exchanges = load(uid);
+        const entry = exchanges.find((e) => e.id === tweet.id);
+        if (!entry)
+            return; // trimmed out already (user is past the 50-exchange cap)
+        entry.agent = clip(text);
+        mem.setJSON(uid, exchanges);
+    },
+};

package/dist/config/skills/compute/handler.d.ts

@@ -0,0 +1,2 @@
+import { type SkillHandler } from "yappr";
+export declare const handler: SkillHandler;

package/dist/config/skills/compute/handler.js

@@ -0,0 +1,5 @@
+import { getTreasury } from "yappr";
+export const handler = async (_params, _tweet) => {
+    await getTreasury().extendCompute();
+    return { text: `compute extended by 24h` };
+};

package/dist/config/skills/cron/handler.d.ts

@@ -0,0 +1,2 @@
+import { type SkillHandler } from "yappr";
+export declare const handler: SkillHandler;

package/dist/config/skills/cron/handler.js

@@ -0,0 +1,84 @@
+import { addCronJob, listCronJobs, getCronJob, setCronJobEnabled, resumeCronJob, removeCronJob, validateSchedule, describeSchedule, checkCronCapability, config, } from "yappr";
+// Thin dispatcher over the engine's cron store ("yappr" public API). All
+// validation/caps live engine-side (validateSchedule/addCronJob) and their error
+// strings are written for the model — return them verbatim as the observation so
+// the agent can relay them (e.g. the ask-the-user-for-a-timezone message).
+//
+// Ownership model (safe to flip the skill to `access: all`): every check below
+// uses the ASKING tweet's author — id for ownership (stable across renames),
+// handle for admin status (how the engine gates admin everywhere) — never model
+// params, so a prompt can't impersonate another user. Non-admins can only see
+// and manage their OWN jobs; admins can see (scope=all) and manage everything.
+const iso = (ms) => new Date(ms).toISOString().slice(0, 16) + "Z";
+const trunc = (s, n = 120) => (s.length > n ? s.slice(0, n) + "…" : s);
+const isAdmin = (tweet) => config.adminHandles.includes(tweet.author?.username?.toLowerCase() ?? "");
+// One line per job. Prompts are shown VERBATIM on purpose: stored prompts are
+// replayed through the agent later, so `list` is their audit surface. The
+// creating tweet id is included so the model can link the origin when asked
+// (https://x.com/i/status/<id>).
+function formatJob(j) {
+    const status = j.enabled ? `next ${iso(j.nextRunAt)}` : "disabled";
+    const origin = j.sourceTweet?.id ? `, from tweet ${j.sourceTweet.id}` : "";
+    const last = j.lastError
+        ? ` | last error: ${trunc(j.lastError)}`
+        : j.lastResult ? ` | last result: ${trunc(j.lastResult)}` : "";
+    return `#${j.id} [${status}] ${describeSchedule(j.schedule)} (by @${j.creatorHandle}${origin}, ${j.runs} runs) — "${j.prompt}"${last}`;
+}
+export const handler = async (params, tweet) => {
+    switch (params.action) {
+        case "add": {
+            const schedule = validateSchedule(params);
+            if ("error" in schedule)
+                return { text: schedule.error };
+            // Refuse jobs whose instruction needs skills the creator can't use — they
+            // would burn inference on every run only to hit the access denial. No-op
+            // for admins; see src/cron/capability.ts for the why and the limits.
+            const cap = await checkCronCapability(params.prompt ?? "", isAdmin(tweet));
+            if (!cap.ok)
+                return { text: `cannot create this job — it would fail on every run: ${cap.reason}` };
+            const res = addCronJob({ prompt: params.prompt ?? "", schedule, tweet });
+            if ("error" in res)
+                return { text: res.error };
+            const j = res.job;
+            return { text: `cron #${j.id} created: ${describeSchedule(j.schedule)} — "${j.prompt}" (next run ${iso(j.nextRunAt)})` };
+        }
+        case "list": {
+            // Non-admins always see only their own jobs (other users' stored prompts
+            // are not theirs to read); admins get scope=all on request.
+            const mine = params.scope !== "all" || !isAdmin(tweet);
+            const jobs = listCronJobs(mine ? { creatorId: tweet.author?.id } : {});
+            if (jobs.length === 0)
+                return { text: mine ? `no cron jobs for @${tweet.author?.username ?? "you"}` : "no cron jobs" };
+            return { text: jobs.map(formatJob).join("\n") };
+        }
+        case "remove":
+        case "pause":
+        case "resume": {
+            const id = Number(params.id);
+            if (!Number.isInteger(id))
+                return { text: `missing or invalid "id" (got "${params.id ?? ""}") — use "list" to see job ids` };
+            const job = getCronJob(id);
+            // Not-found and not-owned return the SAME message for non-admins, so job
+            // ids can't be probed for existence.
+            if (!job || (job.creatorId !== tweet.author?.id && !isAdmin(tweet))) {
+                return { text: `no cron job #${id} of yours — use "list" to see your jobs` };
+            }
+            if (params.action === "remove") {
+                removeCronJob(id);
+                return { text: `cron #${id} removed (was: ${describeSchedule(job.schedule)} — "${job.prompt}")` };
+            }
+            if (params.action === "resume") {
+                // resumeCronJob re-checks the active-job caps (a paused job freed its
+                // slot) and re-arms next_run_at; its errors are written for the model.
+                const res = resumeCronJob(id);
+                if ("error" in res)
+                    return { text: res.error };
+                return { text: `cron #${id} resumed (next run ${iso(res.job.nextRunAt)})` };
+            }
+            const ok = setCronJobEnabled(id, false);
+            return { text: ok ? `cron #${id} paused` : `cron #${id} pause failed` };
+        }
+        default:
+            return { text: `unknown action "${params.action}" — try: add, list, remove, pause, resume` };
+    }
+};

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

@@ -0,0 +1,2 @@
+import { type SkillHandler } from "yappr";
+export declare const handler: SkillHandler;

package/dist/config/skills/generate-image/handler.js

@@ -0,0 +1,122 @@
+import { payFetch, log } 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 = {
+    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) {
+    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) => 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) {
+    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 = 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;
+    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;
+    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 = 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" };
+};