npm - yappr - Versions diffs - 0.1.0 - Mend

yappr 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (149) hide show

package/.env.example +115 -0
package/config/context/personality.md +7 -0
package/config/context/security.md +10 -0
package/config/hooks/example.ts +47 -0
package/config/hooks/holder.ts +154 -0
package/config/hooks/user-memory.ts +102 -0
package/config/skills/compute/handler.ts +6 -0
package/config/skills/compute/skill.md +7 -0
package/config/skills/cron/handler.ts +89 -0
package/config/skills/cron/skill.md +36 -0
package/config/skills/generate-image/handler.ts +133 -0
package/config/skills/generate-image/skill.md +20 -0
package/config/skills/generate-meme-prompt/handler.ts +40 -0
package/config/skills/generate-meme-prompt/skill.md +23 -0
package/config/skills/stats/handler.ts +76 -0
package/config/skills/stats/skill.md +18 -0
package/config/skills/wallet/handler.ts +56 -0
package/config/skills/wallet/skill.md +17 -0
package/config/skills/x/handler.ts +135 -0
package/config/skills/x/skill.md +163 -0
package/dist/config/hooks/example.d.ts +2 -0
package/dist/config/hooks/example.js +37 -0
package/dist/config/hooks/holder.d.ts +2 -0
package/dist/config/hooks/holder.js +147 -0
package/dist/config/hooks/user-memory.d.ts +2 -0
package/dist/config/hooks/user-memory.js +79 -0
package/dist/config/skills/compute/handler.d.ts +2 -0
package/dist/config/skills/compute/handler.js +5 -0
package/dist/config/skills/cron/handler.d.ts +2 -0
package/dist/config/skills/cron/handler.js +84 -0
package/dist/config/skills/generate-image/handler.d.ts +2 -0
package/dist/config/skills/generate-image/handler.js +122 -0
package/dist/config/skills/generate-meme/handler.d.ts +2 -0
package/dist/config/skills/generate-meme/handler.js +121 -0
package/dist/config/skills/generate-meme-prompt/handler.d.ts +2 -0
package/dist/config/skills/generate-meme-prompt/handler.js +38 -0
package/dist/config/skills/stats/handler.d.ts +2 -0
package/dist/config/skills/stats/handler.js +71 -0
package/dist/config/skills/wallet/handler.d.ts +2 -0
package/dist/config/skills/wallet/handler.js +54 -0
package/dist/config/skills/x/handler.d.ts +2 -0
package/dist/config/skills/x/handler.js +115 -0
package/dist/src/agent-prompt.d.ts +1 -0
package/dist/src/agent-prompt.js +45 -0
package/dist/src/bankr.d.ts +41 -0
package/dist/src/bankr.js +76 -0
package/dist/src/cli/backup.d.ts +7 -0
package/dist/src/cli/backup.js +78 -0
package/dist/src/cli/charts.d.ts +32 -0
package/dist/src/cli/charts.js +222 -0
package/dist/src/cli/config-sync.d.ts +7 -0
package/dist/src/cli/config-sync.js +71 -0
package/dist/src/cli/deploy.d.ts +2 -0
package/dist/src/cli/deploy.js +1059 -0
package/dist/src/cli/env.d.ts +4 -0
package/dist/src/cli/env.js +50 -0
package/dist/src/cli/host-key.d.ts +4 -0
package/dist/src/cli/host-key.js +50 -0
package/dist/src/cli/index.d.ts +2 -0
package/dist/src/cli/index.js +71 -0
package/dist/src/cli/init.d.ts +1 -0
package/dist/src/cli/init.js +51 -0
package/dist/src/cli/ssh.d.ts +2 -0
package/dist/src/cli/ssh.js +141 -0
package/dist/src/cli/status.d.ts +7 -0
package/dist/src/cli/status.js +1184 -0
package/dist/src/cli/tui.d.ts +18 -0
package/dist/src/cli/tui.js +115 -0
package/dist/src/cli/ui.d.ts +30 -0
package/dist/src/cli/ui.js +164 -0
package/dist/src/cli/update.d.ts +1 -0
package/dist/src/cli/update.js +263 -0
package/dist/src/cli/x-login.d.ts +6 -0
package/dist/src/cli/x-login.js +70 -0
package/dist/src/compute.d.ts +11 -0
package/dist/src/compute.js +109 -0
package/dist/src/config-loader.d.ts +19 -0
package/dist/src/config-loader.js +82 -0
package/dist/src/config.d.ts +29 -0
package/dist/src/config.js +68 -0
package/dist/src/cron/capability.d.ts +6 -0
package/dist/src/cron/capability.js +66 -0
package/dist/src/cron/runner.d.ts +2 -0
package/dist/src/cron/runner.js +113 -0
package/dist/src/cron/schedule.d.ts +19 -0
package/dist/src/cron/schedule.js +154 -0
package/dist/src/cron/store.d.ts +46 -0
package/dist/src/cron/store.js +220 -0
package/dist/src/db.d.ts +4 -0
package/dist/src/db.js +53 -0
package/dist/src/hooks/loader.d.ts +1 -0
package/dist/src/hooks/loader.js +17 -0
package/dist/src/hooks/registry.d.ts +17 -0
package/dist/src/hooks/registry.js +78 -0
package/dist/src/hooks/types.d.ts +45 -0
package/dist/src/hooks/types.js +1 -0
package/dist/src/index.d.ts +25 -0
package/dist/src/index.js +35 -0
package/dist/src/llm/index.d.ts +23 -0
package/dist/src/llm/index.js +213 -0
package/dist/src/llm/prompts.d.ts +6 -0
package/dist/src/llm/prompts.js +99 -0
package/dist/src/log.d.ts +2 -0
package/dist/src/log.js +30 -0
package/dist/src/reply/agent.d.ts +20 -0
package/dist/src/reply/agent.js +215 -0
package/dist/src/reply/context-blocks.d.ts +12 -0
package/dist/src/reply/context-blocks.js +22 -0
package/dist/src/reply/gating.d.ts +3 -0
package/dist/src/reply/gating.js +35 -0
package/dist/src/reply/pipeline.d.ts +3 -0
package/dist/src/reply/pipeline.js +144 -0
package/dist/src/reply/poller.d.ts +5 -0
package/dist/src/reply/poller.js +79 -0
package/dist/src/skills/holder-access.d.ts +7 -0
package/dist/src/skills/holder-access.js +53 -0
package/dist/src/skills/loader.d.ts +2 -0
package/dist/src/skills/loader.js +64 -0
package/dist/src/skills/registry.d.ts +4 -0
package/dist/src/skills/registry.js +10 -0
package/dist/src/skills/types.d.ts +16 -0
package/dist/src/skills/types.js +1 -0
package/dist/src/state.d.ts +5 -0
package/dist/src/state.js +26 -0
package/dist/src/stats-cli.d.ts +1 -0
package/dist/src/stats-cli.js +82 -0
package/dist/src/stats.d.ts +41 -0
package/dist/src/stats.js +236 -0
package/dist/src/storage.d.ts +16 -0
package/dist/src/storage.js +107 -0
package/dist/src/treasury/abi.d.ts +99 -0
package/dist/src/treasury/abi.js +71 -0
package/dist/src/treasury/cycle.d.ts +16 -0
package/dist/src/treasury/cycle.js +154 -0
package/dist/src/treasury/index.d.ts +28 -0
package/dist/src/treasury/index.js +222 -0
package/dist/src/util.d.ts +3 -0
package/dist/src/util.js +18 -0
package/dist/src/wallet.d.ts +5 -0
package/dist/src/wallet.js +241 -0
package/dist/src/x/client.d.ts +74 -0
package/dist/src/x/client.js +323 -0
package/dist/src/x/types.d.ts +61 -0
package/dist/src/x/types.js +1 -0
package/dist/src/x402.d.ts +6 -0
package/dist/src/x402.js +11 -0
package/dist/src/yappr.d.ts +1 -0
package/dist/src/yappr.js +85 -0
package/package.json +52 -0

package/dist/src/reply/context-blocks.d.ts ADDED Viewed

@@ -0,0 +1,12 @@
+export declare const BLOCK: {
+    readonly asker: "ASKER TWEET";
+    readonly replyTo: "REPLY-TO TWEET";
+    readonly root: "CONVERSATION ROOT TWEET";
+};
+export declare function referencedBlockLabel(id: string, type: string): string;
+export declare function contextBlock(label: string, body: string): string;
+export type ContextImage = {
+    url: string;
+    source: string;
+};
+export declare function imageCaption(index: number, source: string): string;

package/dist/src/reply/context-blocks.js ADDED Viewed

@@ -0,0 +1,22 @@
+// Shared labels and format for the context blocks fed to the LLM. Used by
+// pipeline.ts (which emits the blocks) and by the agent instructions in agent.ts
+// (which tell the model how to read them) — kept here so the two can never drift.
+export const BLOCK = {
+    asker: "ASKER TWEET",
+    replyTo: "REPLY-TO TWEET",
+    root: "CONVERSATION ROOT TWEET",
+};
+// Header for a tweet referenced by the asker tweet (e.g. a quoted tweet). The id
+// and type come straight from the asker tweet's referenced_tweets entry.
+export function referencedBlockLabel(id, type) {
+    return `REFERENCED TWEET IN THE ASKER TWEET (ID: ${id}, TYPE: ${type})`;
+}
+// Wrap a label + body into a "=== LABEL ===\n<body>" context block.
+export function contextBlock(label, body) {
+    return `=== ${label} ===\n${body}`;
+}
+// Caption emitted as a text part immediately before image N, so the model knows
+// which tweet each attached image belongs to (ids tie back to the JSON blocks above).
+export function imageCaption(index, source) {
+    return `Image ${index} — attached to the ${source}:`;
+}

package/dist/src/reply/gating.d.ts ADDED Viewed

@@ -0,0 +1,3 @@
+import type { Tweet } from "../x/types.js";
+export declare function replyToScreenName(t: Tweet): string | undefined;
+export declare function shouldReply(text: string, handle: string, replyToAuthorHandle?: string | null): boolean;

package/dist/src/reply/gating.js ADDED Viewed

@@ -0,0 +1,35 @@
+// Pure helpers for deciding whether/how to engage a mention — no I/O, no payments.
+// `shouldReply` is the positional filter described below.
+// The handle (without @) this tweet replies to, read straight off the tweet — no
+// extra fetch. Feeds shouldReply's "agent is first mention" branch so gating can
+// run before we pay to fetch conversation context.
+export function replyToScreenName(t) {
+    return t.in_reply_to_screen_name ?? undefined;
+}
+// Decide whether a mention is actually directed at us, to avoid replying when X
+// auto-prepends our handle into an unrelated reply chain. We reply if our handle
+// appears in the tweet body, or is the last of the leading @mentions, or is the
+// first leading mention only when the tweet replies to us (or replies to nobody).
+export function shouldReply(text, handle, replyToAuthorHandle) {
+    const trimmed = text.trim();
+    const leadingMentions = trimmed.match(/^(@\w+\s*)+/)?.[0] ?? "";
+    const body = trimmed.slice(leadingMentions.length);
+    const handleRe = new RegExp(`@${handle}\\b`, "i");
+    const h = handle.toLowerCase();
+    if (handleRe.test(body))
+        return true;
+    const mentions = [...leadingMentions.matchAll(/@(\w+)/g)].map((m) => m[1].toLowerCase());
+    if (mentions.length === 0)
+        return false;
+    if (mentions[mentions.length - 1] === h)
+        return true;
+    if (mentions[0] === h) {
+        // Agent is first in leading mentions — only reply if this tweet is itself
+        // a reply to the agent (i.e. agent started the thread), not when the agent
+        // handle was auto-prepended by X into someone else's reply chain.
+        if (!replyToAuthorHandle)
+            return true;
+        return replyToAuthorHandle.toLowerCase() === h;
+    }
+    return false;
+}

package/dist/src/reply/pipeline.d.ts ADDED Viewed

@@ -0,0 +1,3 @@
+import type { Logger } from "pino";
+import type { Tweet } from "../x/types.js";
+export declare function processTweet(t: Tweet, log: Logger): Promise<void>;

package/dist/src/reply/pipeline.js ADDED Viewed

@@ -0,0 +1,144 @@
+import { getTweets, postReply, tweetImageUrls, uploadMediaFromUrl } from "../x/client.js";
+import { runAgentLoop } from "./agent.js";
+import { runOnMention, runShouldReply, runOnBeforeInference, runOnAfterInference, runOnBeforeReply, runOnAfterReply, } from "../hooks/registry.js";
+import { shouldReply, replyToScreenName } from "./gating.js";
+import { BLOCK, referencedBlockLabel, contextBlock } from "./context-blocks.js";
+import { config } from "../config.js";
+import { recordReply } from "../stats.js";
+// Handles one mention end-to-end: decide whether to reply (positional gating +
+// hooks) → gather thread context → run the agent loop → post the reply. Gating runs
+// before the (paid) context fetch, so mentions we skip cost nothing. User hooks run
+// at each stage so forks can observe or veto without touching this file.
+export async function processTweet(t, log) {
+    await runOnMention(t);
+    // Who the asker tweet replies to is carried on the tweet itself, so positional
+    // gating needs no extra fetch — we only pay for context once we'll actually reply.
+    if (!shouldReply(t.text, config.agentHandle, replyToScreenName(t))) {
+        log.info({ id: t.id, text: t.text }, "skipping: mention not in valid position");
+        return;
+    }
+    const hookVeto = await runShouldReply(t);
+    if (!hookVeto) {
+        log.info({ id: t.id }, "skipping: hook vetoed reply");
+        return;
+    }
+    log.info({ id: t.id, author: t.author?.username, text: t.text }, "processing mention");
+    const ctx = await fetchContext(t, log);
+    const askingTweet = contextBlock(BLOCK.asker, JSON.stringify(t, null, 2));
+    let context = ctx?.body ? `${ctx.body}\n\n${askingTweet}` : askingTweet;
+    // Images to show the vision model: the asker's own photos plus any on the tweets
+    // it references (e.g. "what's in the image above"), each tagged with its source
+    // tweet and deduped by URL (asker wins when a photo appears in more than one).
+    const askerImages = tweetImageUrls(t).map((url) => ({ url, source: `${BLOCK.asker} (id ${t.id})` }));
+    const images = dedupeImages([...askerImages, ...(ctx?.images ?? [])]);
+    try {
+        // onBeforeInference receives the asker tweet (for per-user logic like memory
+        // injection) and its raw text. The model reads the ask from the ASKER TWEET
+        // in `context`, so a hook steers inference by rewriting `context`.
+        const inferred = await runOnBeforeInference(t, t.text, context);
+        context = inferred.context ?? context;
+        const isAdmin = config.adminHandles.length > 0 &&
+            config.adminHandles.includes(t.author?.username?.toLowerCase() ?? "");
+        // deniedSkills is ignored for live mentions: the model's reply already
+        // tells the asker about the denial; it only drives cron failure handling.
+        const result = await runAgentLoop(context, isAdmin, t, log, images);
+        let replyText = result.text;
+        replyText = await runOnAfterInference(t.text, replyText);
+        const finalText = await runOnBeforeReply(t, replyText);
+        if (finalText === null) {
+            log.info({ id: t.id }, "skipping: onBeforeReply hook vetoed reply");
+            return;
+        }
+        // Attach any images the skills produced this turn (e.g. generate-image).
+        const mediaIds = await uploadReplyMedia(result.mediaUrls, t.id, log);
+        await postReply(t.id, finalText, mediaIds);
+        await runOnAfterReply(t, finalText);
+        log.info({ id: t.id }, "replied");
+        recordReply();
+    }
+    catch (err) {
+        log.error({ err, id: t.id }, "reply failed");
+    }
+}
+// Upload each image a skill produced this turn to X and return the media_ids to attach
+// to the reply. Best-effort and bounded to X's 4-images-per-tweet limit: a failed upload
+// is logged and skipped so the reply still goes out (as text) rather than failing because
+// one image couldn't be attached.
+async function uploadReplyMedia(urls, tweetId, log) {
+    if (urls.length === 0)
+        return undefined;
+    const ids = [];
+    for (const url of urls.slice(0, 4)) {
+        try {
+            ids.push(await uploadMediaFromUrl(url));
+        }
+        catch (err) {
+            log.warn({ err: err instanceof Error ? err.message : String(err), id: tweetId, url }, "reply media upload failed — skipping");
+        }
+    }
+    return ids.length ? ids : undefined;
+}
+// Drop duplicate images by URL, keeping the first occurrence (and thus its source
+// label) — so a photo on both the asker tweet and a tweet it quotes is sent once,
+// attributed to the asker.
+function dedupeImages(images) {
+    const seen = new Set();
+    return images.filter((img) => !seen.has(img.url) && (seen.add(img.url), true));
+}
+// Fetch the conversation root and/or the reply-to tweet (one paid getTweets call)
+// and render them into the context blocks the model reads, plus any images they
+// carry (tagged with their source tweet, for the vision path). Returns undefined
+// when the mention is a standalone tweet with nothing to fetch.
+async function fetchContext(t, log) {
+    const refs = t.referenced_tweets ?? [];
+    const replyToId = refs.find((r) => r.type === "replied_to")?.id;
+    // Other references carried on the asker tweet (e.g. a "quoted" tweet) — fetched
+    // and shown individually with their id + type.
+    const otherRefs = refs.filter((r) => r.type !== "replied_to" && r.id);
+    // The tweet the asker replied to is always shown as REPLY-TO TWEET. We also show
+    // the CONVERSATION ROOT TWEET only when the reply-to tweet isn't itself the root —
+    // i.e. its conversation_id differs from its id (equivalently: replyToId differs
+    // from the thread's conversation_id, which is invariant across the thread).
+    const wantsRoot = !!replyToId && !!t.conversation_id && replyToId !== t.conversation_id;
+    // One batched (paid) fetch for everything we need. Dedupe in case ids overlap.
+    const idsToFetch = [...new Set([
+            ...(wantsRoot ? [t.conversation_id] : []),
+            ...(replyToId ? [replyToId] : []),
+            ...otherRefs.map((r) => r.id),
+        ])];
+    if (idsToFetch.length === 0)
+        return undefined;
+    let fetched = [];
+    try {
+        fetched = await getTweets(idsToFetch);
+    }
+    catch (err) {
+        log.error({ err }, "context fetch failed; proceeding without context");
+        return undefined;
+    }
+    const parts = [];
+    const images = [];
+    const collect = (tweet, source) => images.push(...tweetImageUrls(tweet).map((url) => ({ url, source })));
+    if (wantsRoot) {
+        const root = fetched.find((x) => x.id === t.conversation_id);
+        if (root) {
+            parts.push(contextBlock(BLOCK.root, JSON.stringify(root, null, 2)));
+            collect(root, `${BLOCK.root} (id ${root.id})`);
+        }
+    }
+    if (replyToId) {
+        const replyTo = fetched.find((x) => x.id === replyToId);
+        if (replyTo) {
+            parts.push(contextBlock(BLOCK.replyTo, JSON.stringify(replyTo, null, 2)));
+            collect(replyTo, `${BLOCK.replyTo} (id ${replyTo.id})`);
+        }
+    }
+    for (const ref of otherRefs) {
+        const refTweet = fetched.find((x) => x.id === ref.id);
+        if (refTweet) {
+            parts.push(contextBlock(referencedBlockLabel(ref.id, ref.type), JSON.stringify(refTweet, null, 2)));
+            collect(refTweet, referencedBlockLabel(ref.id, ref.type));
+        }
+    }
+    return parts.length || images.length ? { body: parts.length ? parts.join("\n\n") : undefined, images } : undefined;
+}

package/dist/src/reply/poller.d.ts ADDED Viewed

@@ -0,0 +1,5 @@
+import type { Logger } from "pino";
+export declare function createPoller(log: Logger): {
+    start: () => Promise<void>;
+    stop: () => void;
+};

package/dist/src/reply/poller.js ADDED Viewed

@@ -0,0 +1,79 @@
+import { config } from "../config.js";
+import { searchMentions } from "../x/client.js";
+import { loadState, saveState } from "../state.js";
+import { recordMention } from "../stats.js";
+import { processTweet } from "./pipeline.js";
+// The ingest loop: every POLL_INTERVAL_MS it searches for new @mentions, tracks
+// the highest tweet id seen (persisted in the state table) so each mention is handled
+// once, and hands every fresh mention to processTweet(). Tweet ids are snowflakes
+// (monotonically increasing), so we compare them as BigInts to order by recency.
+function idGt(a, b) {
+    return BigInt(a) > BigInt(b);
+}
+function idMax(a, b) {
+    return idGt(a, b) ? a : b;
+}
+// Twitter snowflake ids embed a millisecond timestamp in their high bits (epoch
+// 2010-11-04). This builds the smallest id for "now", used to anchor the baseline
+// at startup when there are no existing mentions to anchor to — so we still reply
+// to mentions that arrive afterward instead of treating the first one as backfill.
+const TWITTER_EPOCH_MS = 1288834974657n;
+function snowflakeForNow() {
+    return ((BigInt(Date.now()) - TWITTER_EPOCH_MS) << 22n).toString();
+}
+export function createPoller(log) {
+    let state = { lastSeenId: null };
+    let isRunning = false;
+    let timer = null;
+    async function cycle() {
+        if (isRunning) {
+            log.warn("previous poll still running, skipping tick");
+            return;
+        }
+        isRunning = true;
+        try {
+            log.info("poll cycle start");
+            const response = await searchMentions(config.agentHandle);
+            const tweets = (response.data || []).slice().sort((a, b) => (idGt(a.id, b.id) ? 1 : -1));
+            // No baseline yet: skip pre-existing mentions by anchoring the baseline — to the
+            // newest mention if any exist, or to startup time otherwise. Keyed on
+            // lastSeenId === null (not a one-shot flag) so an empty first poll just retries
+            // next tick instead of leaving it unset.
+            if (state.lastSeenId === null) {
+                state.lastSeenId = tweets.at(-1)?.id ?? snowflakeForNow();
+                await saveState(state);
+                log.info({ lastSeenId: state.lastSeenId }, "baseline established on startup; skipping backfill");
+                return;
+            }
+            const baseline = state.lastSeenId;
+            const fresh = tweets.filter((t) => idGt(t.id, baseline));
+            if (fresh.length === 0)
+                return;
+            log.info({ count: fresh.length }, "new mentions found");
+            recordMention(fresh.length);
+            state.lastSeenId = fresh.reduce((max, t) => idMax(max, t.id), fresh[0].id);
+            await saveState(state);
+            for (const t of fresh) {
+                void processTweet(t, log);
+            }
+        }
+        catch (err) {
+            log.error({ err }, "poll cycle failed");
+        }
+        finally {
+            isRunning = false;
+        }
+    }
+    async function start() {
+        state = await loadState();
+        log.info({ lastSeenId: state.lastSeenId }, "poller starting");
+        void cycle();
+        timer = setInterval(() => void cycle(), config.pollIntervalMs);
+    }
+    function stop() {
+        if (timer)
+            clearInterval(timer);
+        timer = null;
+    }
+    return { start, stop };
+}

package/dist/src/skills/holder-access.d.ts ADDED Viewed

@@ -0,0 +1,7 @@
+import type { Tweet } from "../x/types.js";
+export declare function checkHolderAccess(tweet: Tweet, minHolding: number): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/src/skills/holder-access.js ADDED Viewed

@@ -0,0 +1,53 @@
+import { skillStore } from "../storage.js";
+// Code-side gate for `access: holder` skills, mirroring the admin check in
+// reply/agent.ts: enforced HERE, never trusted to the LLM. Every input is
+// outside the model's reach — the asker's identity comes from the pipeline's
+// tweet object (tweet.author.id, set by the X API, not by skill params), the
+// threshold comes from skill.md frontmatter, and the holdings come from the
+// shared DB — so a prompt-injected "I hold a billion tokens" changes nothing.
+//
+// The holdings themselves are the ones the holder hook (config/hooks/holder.ts)
+// cached in skillStore("bankr-wallet"): the asker's Bankr wallet (resolved once
+// per user) and their token balance (refreshed at most hourly). The hook runs
+// before the agent loop on every mention, so by the time a skill call is being
+// gated the asker's entries are as fresh as they'll get. If the hook was
+// removed, no holdings exist in the DB and every holder skill denies — closed
+// by default, never open.
+// Mirrors the hook's storage layout (namespace + key shapes + entry types).
+const STORE_NS = "bankr-wallet";
+const TOKEN_DECIMALS = 18n; // Bankr launches are fixed 18-decimal Clanker deploys
+// Whole tokens → wei, via BigInt(string) so large thresholds (e.g. 1e9 tokens)
+// don't round through float math.
+function toWei(wholeTokens) {
+    return BigInt(Math.floor(wholeTokens)) * 10n ** TOKEN_DECIMALS;
+}
+const fmtWhole = (wei) => (wei / 10n ** TOKEN_DECIMALS).toLocaleString("en-US");
+export function checkHolderAccess(tweet, minHolding) {
+    const userId = tweet.author?.id;
+    if (!userId)
+        return { ok: false, reason: "could not identify the requesting user" };
+    const store = skillStore(STORE_NS);
+    const wallet = store.getJSON(`wallet:${userId}`);
+    if (!wallet?.address) {
+        return { ok: false, reason: "this skill is for holders of the agent's token, and no Bankr wallet is known for you yet" };
+    }
+    const required = toWei(minHolding);
+    if (required === 0n)
+        return { ok: true }; // wallet on record is the whole bar
+    const balance = store.getJSON(`balance:${wallet.address}`);
+    let held = null;
+    try {
+        held = balance ? BigInt(balance.raw) : null;
+    }
+    catch { /* malformed → unknown */ }
+    if (held === null) {
+        return { ok: false, reason: "this skill is for holders of the agent's token, and your holdings aren't known yet — try again in a moment" };
+    }
+    if (held < required) {
+        return {
+            ok: false,
+            reason: `this skill requires holding at least ${fmtWhole(required)} of the agent's token — you hold ${fmtWhole(held)}`,
+        };
+    }
+    return { ok: true };
+}

package/dist/src/skills/loader.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ import type { SkillDef } from "./types.js";
2	+ export declare function loadSkills(): Promise<SkillDef[]>;

package/dist/src/skills/loader.js ADDED Viewed

@@ -0,0 +1,64 @@
+import { readFile } from "node:fs/promises";
+import { log } from "../log.js";
+import { listSkills, importConfigModule } from "../config-loader.js";
+function parseFrontmatter(raw) {
+    const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!match)
+        return { name: "", description: "", body: raw.trim(), access: "all" };
+    const meta = match[1];
+    const body = match[2].trim();
+    const name = meta.match(/^name:\s*(.+)$/m)?.[1]?.trim() ?? "";
+    const description = meta.match(/^description:\s*(.+)$/m)?.[1]?.trim() ?? "";
+    const accessRaw = meta.match(/^access:\s*(.+)$/m)?.[1]?.trim();
+    const access = accessRaw === "admin" ? "admin" : accessRaw === "holder" ? "holder" : "all";
+    // `min_holding: <whole tokens>` — only meaningful with `access: holder`.
+    // A malformed value falls back to 0 (wallet required, no minimum) with a warn,
+    // rather than silently granting "all" access.
+    const minRaw = meta.match(/^min_holding:\s*(.+)$/m)?.[1]?.trim();
+    let minHolding;
+    if (minRaw !== undefined) {
+        const n = Number(minRaw.replace(/[_,]/g, ""));
+        if (Number.isFinite(n) && n >= 0) {
+            minHolding = n;
+        }
+        else {
+            log.warn({ name, min_holding: minRaw }, "skill: invalid min_holding — treating as 0");
+            minHolding = 0;
+        }
+    }
+    return { name, description, body, access, minHolding };
+}
+export async function loadSkills() {
+    const skills = [];
+    // Discovery (which skills exist, and where their skill.md + handler live) is owned
+    // by config-loader, so user and built-in config layer the same way everywhere.
+    for (const entry of await listSkills()) {
+        try {
+            const raw = await readFile(entry.mdPath, "utf8");
+            const { name, description, body, access, minHolding } = parseFrontmatter(raw);
+            if (!name || !description) {
+                log.warn({ entry: entry.name }, "skill skipped: missing name or description");
+                continue;
+            }
+            // A skill with no handler file is context-only. If a handler file is present
+            // but fails to import, that's a real error worth surfacing (not silent).
+            let handler;
+            if (entry.handlerPath) {
+                try {
+                    const mod = await importConfigModule(entry.handlerPath);
+                    if (typeof mod.handler === "function")
+                        handler = mod.handler;
+                }
+                catch (err) {
+                    log.warn({ entry: entry.name, err: err?.message }, "skill handler failed to load; treating as context-only");
+                }
+            }
+            skills.push({ name, description, body, access, minHolding, handler });
+            log.info({ name, access, ...(access === "holder" ? { minHolding: minHolding ?? 0 } : {}), type: handler ? "handler" : "context-only" }, `skill loaded: ${name}`);
+        }
+        catch (err) {
+            log.error({ entry: entry.name, err: err.message }, `skill load failed: ${entry.name}`);
+        }
+    }
+    return skills;
+}

package/dist/src/skills/registry.d.ts ADDED Viewed

@@ -0,0 +1,4 @@
+import type { SkillDef } from "./types.js";
+export declare function initSkills(skills: SkillDef[]): void;
+export declare function getSkill(name: string): SkillDef | undefined;
+export declare function listSkills(): SkillDef[];

package/dist/src/skills/registry.js ADDED Viewed

@@ -0,0 +1,10 @@
+let _skills = [];
+export function initSkills(skills) {
+    _skills = skills;
+}
+export function getSkill(name) {
+    return _skills.find((s) => s.name === name);
+}
+export function listSkills() {
+    return _skills;
+}

package/dist/src/skills/types.d.ts ADDED Viewed

@@ -0,0 +1,16 @@
+import type { Tweet } from "../x/types.js";
+export type SkillResult = {
+    text?: string;
+    data?: unknown;
+    mediaUrl?: string;
+};
+export type SkillHandler = (params: Record<string, string>, tweet: Tweet) => Promise<SkillResult>;
+export type SkillAccess = "all" | "admin" | "holder";
+export type SkillDef = {
+    name: string;
+    description: string;
+    body: string;
+    access: SkillAccess;
+    minHolding?: number;
+    handler?: SkillHandler;
+};

package/dist/src/skills/types.js ADDED Viewed

	@@ -0,0 +1 @@
1	+ export {};

package/dist/src/state.d.ts ADDED Viewed

@@ -0,0 +1,5 @@
+export type State = {
+    lastSeenId: string | null;
+};
+export declare function loadState(): Promise<State>;
+export declare function saveState(state: State): Promise<void>;

package/dist/src/state.js ADDED Viewed

@@ -0,0 +1,26 @@
+import { withSchema } from "./db.js";
+const LAST_SEEN = "last_seen_id";
+const SCHEMA = "CREATE TABLE IF NOT EXISTS state (key TEXT PRIMARY KEY, value TEXT)";
+const conn = () => withSchema(SCHEMA);
+export async function loadState() {
+    const d = conn();
+    if (!d)
+        return { lastSeenId: null };
+    try {
+        const row = d.prepare("SELECT value FROM state WHERE key = ?").get(LAST_SEEN);
+        return { lastSeenId: row?.value ?? null };
+    }
+    catch {
+        return { lastSeenId: null };
+    }
+}
+export async function saveState(state) {
+    const d = conn();
+    if (!d)
+        return;
+    try {
+        d.prepare("INSERT INTO state(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value")
+            .run(LAST_SEEN, state.lastSeenId);
+    }
+    catch { /* best-effort */ }
+}

package/dist/src/stats-cli.d.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ import "dotenv/config";

package/dist/src/stats-cli.js ADDED Viewed

@@ -0,0 +1,82 @@
+import "dotenv/config";
+import { summary, recordSpend } from "./stats.js";
+import { getDb } from "./db.js";
+// Tiny command-line face on the stats DB, compiled to dist so it can be invoked over
+// SSH without tsx. Used by the dashboard:
+//   node node_modules/yappr/dist/src/stats-cli.js summary        → prints Summary JSON
+//   node node_modules/yappr/dist/src/stats-cli.js cron           → prints the cron_jobs
+//        rows as JSON (schedule pre-rendered, source tweet dropped) for the CRON page
+//   node node_modules/yappr/dist/src/stats-cli.js backup <dest>  → writes a consistent
+//        snapshot of the DB to <dest> (pulled down as a local backup)
+//   node node_modules/yappr/dist/src/stats-cli.js record-spend <type> <usd> → append one
+//        spend event (used by `yappr deploy` to book the deploy-time compute payment,
+//        which is paid locally — outside the agent's payFetch — so it'd otherwise be lost)
+// It opens the same DB the agent uses (via db.ts, which reads DB_PATH), so its reads
+// land in the same database.
+async function main() {
+    const [cmd, ...args] = process.argv.slice(2);
+    switch (cmd) {
+        case "summary":
+            process.stdout.write(JSON.stringify(summary()));
+            return;
+        case "cron": {
+            // Lazy import: cron/store pulls in config.ts, which requires the full agent
+            // env at import time — summary/backup must keep working without it.
+            const { listCronJobs, describeSchedule } = await import("./cron/store.js");
+            const jobs = listCronJobs().map((j) => ({
+                id: j.id,
+                prompt: j.prompt,
+                schedule: describeSchedule(j.schedule),
+                creator: j.creatorHandle,
+                enabled: j.enabled,
+                nextRunAt: j.nextRunAt,
+                lastRunAt: j.lastRunAt,
+                lastResult: j.lastResult,
+                lastError: j.lastError,
+                runs: j.runs,
+                consecutiveFailures: j.consecutiveFailures,
+                createdAt: j.createdAt,
+            }));
+            process.stdout.write(JSON.stringify(jobs));
+            return;
+        }
+        case "backup": {
+            const dest = args[0];
+            if (!dest) {
+                process.stderr.write("backup: expected a destination path\n");
+                process.exit(1);
+            }
+            const db = getDb();
+            if (!db) {
+                process.stderr.write("backup: could not open the stats DB\n");
+                process.exit(1);
+            }
+            // VACUUM INTO writes a single consistent, compacted copy — safe while the agent
+            // is writing (WAL readers see a stable snapshot) and free of -wal/-shm sidecars.
+            db.exec(`VACUUM INTO '${dest.replace(/'/g, "''")}'`);
+            process.stdout.write(JSON.stringify({ ok: true, dest }));
+            return;
+        }
+        case "record-spend": {
+            // Append one spend event to the ledger. Used by `yappr deploy` to book the
+            // deploy-time compute payment (paid locally, outside the agent's payFetch).
+            const [type, usdRaw] = args;
+            const usd = Number(usdRaw);
+            const valid = ["x-api", "compute", "inference", "x402"];
+            if (!type || !valid.includes(type) || !Number.isFinite(usd) || usd <= 0) {
+                process.stderr.write(`record-spend: expected <type: ${valid.join(" | ")}> <usd> (positive number)\n`);
+                process.exit(1);
+            }
+            recordSpend(type, usd);
+            process.stdout.write(JSON.stringify({ ok: true, type, usd }));
+            return;
+        }
+        default:
+            process.stderr.write(`stats-cli: unknown command ${JSON.stringify(cmd)} (expected: summary | cron | backup | record-spend)\n`);
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`stats-cli: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/src/stats.d.ts ADDED Viewed

@@ -0,0 +1,41 @@
+export type SpendType = "x-api" | "compute" | "inference" | "x402";
+export type Summary = {
+    mentions: number;
+    replies: number;
+    llm: number;
+    warns: number;
+    errors: number;
+    spentUsd: number;
+    spentByType: Record<SpendType, number>;
+    earnedWeth: number;
+    devWeth: number;
+    spentUsdWindow: number;
+    inferenceUsdWindow: number;
+    earnedWethWindow: number;
+    rateWindowHours: number;
+    chart: {
+        day: {
+            spendUsd: number[];
+            earnedWeth: number[];
+            startMs: number;
+            endMs: number;
+        };
+        byType: {
+            startMs: number;
+            xapi: number[];
+            inference: number[];
+            compute: number[];
+            x402: number[];
+            earned: number[];
+        };
+    };
+};
+export declare function recordSpend(type: SpendType, usdc: number): void;
+export declare function recordMention(n: number): void;
+export declare function recordReply(): void;
+export declare function recordLlm(): void;
+export declare function recordWarn(): void;
+export declare function recordError(): void;
+export declare function recordEarned(weth: number): void;
+export declare function recordDevWeth(weth: number): void;
+export declare function summary(): Summary;