yappr 0.1.0

package/dist/src/stats.js

@@ -0,0 +1,236 @@
+import { withSchema } from "./db.js";
+// Trailing window used to estimate the current burn/earn rate for runway (24h).
+const RATE_WINDOW_MS = 24 * 60 * 60 * 1000;
+// Resolution of the dashboard chart series (points across the 24h window).
+const CHART_BUCKETS = 120;
+// This feature's tables (created on first use via the shared connection).
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS events (
+    id    INTEGER PRIMARY KEY,
+    ts    TEXT    NOT NULL,
+    kind  TEXT    NOT NULL,
+    type  TEXT,
+    usdc  REAL,
+    weth  REAL,
+    n     INTEGER
+  );
+  CREATE INDEX IF NOT EXISTS idx_events_ts   ON events(ts);
+  CREATE INDEX IF NOT EXISTS idx_events_kind ON events(kind);
+  CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value REAL);
+`;
+const conn = () => withSchema(SCHEMA);
+const now = () => new Date().toISOString();
+function insert(ev) {
+    const d = conn();
+    if (!d)
+        return;
+    try {
+        d.prepare("INSERT INTO events (ts, kind, type, usdc, weth, n) VALUES (?, ?, ?, ?, ?, ?)")
+            .run(now(), ev.kind, ev.type ?? null, ev.usdc ?? null, ev.weth ?? null, ev.n ?? null);
+    }
+    catch { /* best-effort */ }
+}
+function getMeta(key) {
+    const d = conn();
+    if (!d)
+        return undefined;
+    try {
+        const row = d.prepare("SELECT value FROM meta WHERE key = ?").get(key);
+        return row?.value;
+    }
+    catch {
+        return undefined;
+    }
+}
+function setMeta(key, value) {
+    const d = conn();
+    if (!d)
+        return;
+    try {
+        d.prepare("INSERT INTO meta(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(key, value);
+    }
+    catch { /* best-effort */ }
+}
+export function recordSpend(type, usdc) {
+    if (!Number.isFinite(usdc) || usdc <= 0)
+        return;
+    insert({ kind: "spend", type, usdc });
+}
+export function recordMention(n) {
+    if (!(n > 0))
+        return;
+    insert({ kind: "mention", n });
+}
+export function recordReply() { insert({ kind: "reply" }); }
+export function recordLlm() { insert({ kind: "llm" }); }
+export function recordWarn() { insert({ kind: "warn" }); }
+export function recordError() { insert({ kind: "error" }); }
+// Inference spend is recorded per-request from token usage × per-model pricing (see
+// llm/index.ts: recordSpend("inference", …)), so there's no credit-balance polling
+// here. The live credit balance is still shown on the dashboard as the remaining
+// budget, but it's read directly from the gateway, not tracked as spend.
+// All-time creator fees earned (WETH), reported by Bankr as a cumulative total.
+// Polled on a short timer, so treat it as a gauge: always refresh the stored total,
+// but only append an `earned` event (the increment) when it actually grows — keeping
+// the events table a clean, sliceable record of real earnings, not poll noise.
+export function recordEarned(weth) {
+    if (!Number.isFinite(weth) || weth < 0)
+        return;
+    const prev = getMeta("last_earned_weth");
+    // First observation ever (fresh DB, no restored backup): just set the baseline.
+    // Booking an event here would drop the token's entire pre-agent fee history into
+    // the trailing window as one giant "earned" spike, faking the windowed metrics
+    // ("Sustainable: yes") and charts for a day. All-time earned still shows in full
+    // — summary() reads it from this gauge, not from summing events.
+    if (prev === undefined) {
+        setMeta("last_earned_weth", weth);
+        return;
+    }
+    if (weth > prev + 1e-12)
+        insert({ kind: "earned", weth: weth - prev });
+    setMeta("last_earned_weth", weth);
+}
+// WETH paid out to the dev address this treasury cycle (the dev fee). Each payment is its
+// own `dev` event (an increment), so summing them gives all-time dev revenue.
+export function recordDevWeth(weth) {
+    if (!Number.isFinite(weth) || weth <= 0)
+        return;
+    insert({ kind: "dev", weth });
+}
+// Build a cumulative spend/earn chart series over [startMs, endMs] in CHART_BUCKETS evenly
+// spaced points. Bucketing is done in SQL (one grouped row per bucket via unixepoch), so it
+// stays cheap no matter how many events the range covers — then we running-sum in JS.
+function buildSeries(d, startMs, endMs) {
+    const spendUsd = new Array(CHART_BUCKETS).fill(0);
+    const earnedWeth = new Array(CHART_BUCKETS).fill(0);
+    const span = endMs - startMs;
+    if (span > 0) {
+        const startSec = Math.floor(startMs / 1000);
+        const bucketSec = span / 1000 / CHART_BUCKETS;
+        const rows = d.prepare(`
+      SELECT CAST((unixepoch(ts) - ?) / ? AS INTEGER) AS b,
+             COALESCE(SUM(usdc) FILTER (WHERE kind = 'spend'),  0) AS spend,
+             COALESCE(SUM(weth) FILTER (WHERE kind = 'earned'), 0) AS earned
+      FROM events
+      WHERE ts >= ? AND kind IN ('spend','earned')
+      GROUP BY b
+    `).all(startSec, bucketSec, new Date(startMs).toISOString());
+        for (const r of rows) {
+            const i = Math.min(CHART_BUCKETS - 1, Math.max(0, r.b));
+            spendUsd[i] += r.spend || 0;
+            earnedWeth[i] += r.earned || 0;
+        }
+        for (let i = 1; i < CHART_BUCKETS; i++) {
+            spendUsd[i] += spendUsd[i - 1];
+            earnedWeth[i] += earnedWeth[i - 1];
+        }
+    }
+    return { spendUsd, earnedWeth, startMs, endMs };
+}
+// Per-hour spend by type AND per-hour earnings over the 24 clock-hours ending with the
+// current hour. Returns 24 buckets each (spend USD by type; earned WETH), not cumulative,
+// plus the first bucket's (clock-aligned) start. For the hourly bar charts. Bucketed in SQL.
+function buildHourlyByType(d) {
+    const N = 24, HOUR = 3_600_000;
+    const startMs = Math.floor(Date.now() / HOUR) * HOUR - (N - 1) * HOUR; // 24 hours ending this hour
+    const xapi = new Array(N).fill(0), inference = new Array(N).fill(0), compute = new Array(N).fill(0);
+    const x402 = new Array(N).fill(0);
+    const earned = new Array(N).fill(0);
+    const startSec = startMs / 1000;
+    const startIso = new Date(startMs).toISOString(), endIso = new Date(startMs + N * HOUR).toISOString();
+    const rows = d.prepare(`
+    SELECT CAST((unixepoch(ts) - ?) / 3600 AS INTEGER) AS b, type, COALESCE(SUM(usdc), 0) AS u
+    FROM events
+    WHERE kind = 'spend' AND ts >= ? AND ts < ?
+    GROUP BY b, type
+  `).all(startSec, startIso, endIso);
+    for (const r of rows) {
+        if (r.b < 0 || r.b >= N)
+            continue;
+        if (r.type === "x-api")
+            xapi[r.b] += r.u || 0;
+        else if (r.type === "inference")
+            inference[r.b] += r.u || 0;
+        else if (r.type === "compute")
+            compute[r.b] += r.u || 0;
+        else if (r.type === "x402")
+            x402[r.b] += r.u || 0;
+    }
+    const erows = d.prepare(`
+    SELECT CAST((unixepoch(ts) - ?) / 3600 AS INTEGER) AS b, COALESCE(SUM(weth), 0) AS w
+    FROM events
+    WHERE kind = 'earned' AND ts >= ? AND ts < ?
+    GROUP BY b
+  `).all(startSec, startIso, endIso);
+    for (const r of erows)
+        if (r.b >= 0 && r.b < N)
+            earned[r.b] += r.w || 0;
+    return { startMs, xapi, inference, compute, x402, earned };
+}
+// All-time rolled-up totals, computed straight from the events table. Cheap with the
+// kind/ts indexes; the dashboard polls this via the CLI.
+export function summary() {
+    const empty = {
+        mentions: 0, replies: 0, llm: 0, warns: 0, errors: 0,
+        spentUsd: 0, spentByType: { "x-api": 0, compute: 0, inference: 0, x402: 0 }, earnedWeth: 0, devWeth: 0,
+        spentUsdWindow: 0, inferenceUsdWindow: 0, earnedWethWindow: 0, rateWindowHours: 0,
+        chart: {
+            day: { spendUsd: [], earnedWeth: [], startMs: 0, endMs: 0 },
+            byType: { startMs: 0, xapi: [], inference: [], compute: [], x402: [], earned: [] },
+        },
+    };
+    const d = conn();
+    if (!d)
+        return empty;
+    try {
+        const agg = d.prepare(`
+      SELECT
+        COALESCE(SUM(n)    FILTER (WHERE kind = 'mention'), 0) AS mentions,
+        COUNT(*)           FILTER (WHERE kind = 'reply')       AS replies,
+        COUNT(*)           FILTER (WHERE kind = 'llm')         AS llm,
+        COUNT(*)           FILTER (WHERE kind = 'warn')        AS warns,
+        COUNT(*)           FILTER (WHERE kind = 'error')       AS errors,
+        COALESCE(SUM(usdc) FILTER (WHERE kind = 'spend'), 0)   AS spentUsd,
+        COALESCE(SUM(weth) FILTER (WHERE kind = 'dev'),   0)   AS devWeth
+      FROM events
+    `).get();
+        const spentByType = { "x-api": 0, compute: 0, inference: 0, x402: 0 };
+        const rows = d.prepare("SELECT type, COALESCE(SUM(usdc), 0) AS u FROM events WHERE kind = 'spend' GROUP BY type").all();
+        for (const r of rows)
+            if (r.type && r.type in spentByType)
+                spentByType[r.type] = r.u;
+        // Burn/earn over the trailing window for the runway estimate. The divisor is the
+        // window length, but never longer than the agent's age (first event → now), so a
+        // young agent's rate isn't diluted by counting hours it wasn't running.
+        const since = new Date(Date.now() - RATE_WINDOW_MS).toISOString();
+        const win = d.prepare(`
+      SELECT
+        COALESCE(SUM(usdc) FILTER (WHERE kind = 'spend'),                       0) AS spentUsdWindow,
+        COALESCE(SUM(usdc) FILTER (WHERE kind = 'spend' AND type = 'inference'), 0) AS inferenceUsdWindow,
+        COALESCE(SUM(weth) FILTER (WHERE kind = 'earned'),                      0) AS earnedWethWindow
+      FROM events WHERE ts >= ?
+    `).get(since);
+        const firstTs = d.prepare("SELECT MIN(ts) AS t FROM events").get().t;
+        const startMs = firstTs ? Math.max(Date.now() - RATE_WINDOW_MS, Date.parse(firstTs)) : Date.now();
+        const rateWindowHours = Math.max(0, (Date.now() - startMs) / 3_600_000);
+        // Chart series for the dashboard: a 24h view (`day`, from startMs = max(now-24h,
+        // firstEvent)) through now.
+        const chartNow = Date.now();
+        const day = buildSeries(d, startMs, chartNow);
+        const byType = buildHourlyByType(d);
+        // `earnedWeth`/`earnedWethWindow` are GROSS creator fees (the dev cut is part of
+        // this revenue, not subtracted). `devWeth` is surfaced separately as a breakdown
+        // ("Dev rev") of how much of that gross was routed to the dev address.
+        return {
+            mentions: agg.mentions, replies: agg.replies, llm: agg.llm, warns: agg.warns, errors: agg.errors,
+            spentUsd: agg.spentUsd, spentByType,
+            earnedWeth: getMeta("last_earned_weth") ?? 0, devWeth: agg.devWeth,
+            spentUsdWindow: win.spentUsdWindow, inferenceUsdWindow: win.inferenceUsdWindow,
+            earnedWethWindow: win.earnedWethWindow, rateWindowHours,
+            chart: { day, byType },
+        };
+    }
+    catch {
+        return empty;
+    }
+}

package/dist/src/storage.d.ts

@@ -0,0 +1,16 @@
+export type SkillStoreEntry = {
+    key: string;
+    value: string;
+    updatedAt: number;
+};
+export type SkillStore = {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    /** JSON.parse'd get(); null if missing or not valid JSON (logged). */
+    getJSON<T = unknown>(key: string): T | null;
+    /** set() with JSON.stringify — for structured values. */
+    setJSON(key: string, value: unknown): void;
+    delete(key: string): boolean;
+    list(prefix?: string): SkillStoreEntry[];
+};
+export declare function skillStore(ns: string): SkillStore;

package/dist/src/storage.js

@@ -0,0 +1,107 @@
+import { withSchema } from "./db.js";
+import { log } from "./log.js";
+// Namespaced key/value storage for skills and hooks, in the shared SQLite DB
+// (see db.ts). This is the convenience layer of the public storage API: a skill
+// calls skillStore("<its-name>") and gets get/set/delete/list with zero SQL and
+// zero schema decisions. All namespaces share one table (skill_kv) keyed on
+// (ns, key), so a store can only see its own namespace's rows.
+//
+// Because rows live in yappr.db at DB_PATH, skill data survives restarts and
+// redeploys and is included in the dashboard's rolling backups — which is why
+// skills should store here rather than open their own files.
+//
+// Convention: namespace = the skill's folder name, unless two extensions are
+// deliberately sharing data. Skills that need real columns instead of KV use
+// withSchema() directly with their own `skill_<name>_*` table.
+//
+// Like everything on db.ts, operations are best-effort: if the DB can't be
+// opened, reads return empty and writes no-op, degrading the skill instead of
+// crashing the agent. Unlike the engine's own ledgers, failures here are
+// logged (warn): skill params come from LLM JSON, so a non-string value
+// sneaking past the types is a realistic bug the author needs to see.
+const SCHEMA = `CREATE TABLE IF NOT EXISTS skill_kv (
+  ns TEXT NOT NULL,
+  key TEXT NOT NULL,
+  value TEXT NOT NULL,
+  updated_at INTEGER NOT NULL,
+  PRIMARY KEY (ns, key)
+)`;
+const conn = () => withSchema(SCHEMA);
+// Escape LIKE wildcards so list("user:") treats the prefix literally.
+const likePrefix = (prefix) => prefix.replace(/[\\%_]/g, (c) => "\\" + c) + "%";
+export function skillStore(ns) {
+    const store = {
+        get(key) {
+            const d = conn();
+            if (!d)
+                return null;
+            try {
+                const row = d.prepare("SELECT value FROM skill_kv WHERE ns = ? AND key = ?").get(ns, key);
+                return row?.value ?? null;
+            }
+            catch (err) {
+                log.warn({ ns, key, err }, "skillStore.get failed");
+                return null;
+            }
+        },
+        set(key, value) {
+            const d = conn();
+            if (!d)
+                return;
+            try {
+                d.prepare("INSERT INTO skill_kv(ns, key, value, updated_at) VALUES(?, ?, ?, ?) " +
+                    "ON CONFLICT(ns, key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at").run(ns, key, value, Date.now());
+            }
+            catch (err) {
+                // Most likely a non-string value from untyped LLM params — surface it,
+                // a skill that thinks it stored something must not fail silently.
+                log.warn({ ns, key, err }, "skillStore.set failed (value not stored)");
+            }
+        },
+        getJSON(key) {
+            const raw = store.get(key);
+            if (raw === null)
+                return null;
+            try {
+                return JSON.parse(raw);
+            }
+            catch (err) {
+                log.warn({ ns, key, err }, "skillStore.getJSON: stored value is not valid JSON");
+                return null;
+            }
+        },
+        setJSON(key, value) {
+            // stringify(undefined) is undefined, which would fail to bind — store null.
+            store.set(key, JSON.stringify(value) ?? "null");
+        },
+        delete(key) {
+            const d = conn();
+            if (!d)
+                return false;
+            try {
+                return d.prepare("DELETE FROM skill_kv WHERE ns = ? AND key = ?").run(ns, key).changes > 0;
+            }
+            catch (err) {
+                log.warn({ ns, key, err }, "skillStore.delete failed");
+                return false;
+            }
+        },
+        list(prefix) {
+            const d = conn();
+            if (!d)
+                return [];
+            try {
+                const rows = prefix !== undefined
+                    ? d.prepare("SELECT key, value, updated_at FROM skill_kv WHERE ns = ? AND key LIKE ? ESCAPE '\\' ORDER BY key").all(ns, likePrefix(prefix))
+                    : d.prepare("SELECT key, value, updated_at FROM skill_kv WHERE ns = ? ORDER BY key").all(ns);
+                return rows
+                    .map((r) => ({ key: r.key, value: r.value, updatedAt: r.updated_at }));
+            }
+            catch (err) {
+                log.warn({ ns, prefix, err }, "skillStore.list failed");
+                return [];
+            }
+        },
+    };
+    return store;
+}

package/dist/src/treasury/abi.d.ts

@@ -0,0 +1,99 @@
+export declare const ERC20_ABI: readonly [{
+    readonly name: "transfer";
+    readonly type: "function";
+    readonly inputs: readonly [{
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly name: "balanceOf";
+    readonly type: "function";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly name: "approve";
+    readonly type: "function";
+    readonly inputs: readonly [{
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly name: "allowance";
+    readonly type: "function";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+}];
+export declare const WETH_ABI: readonly [{
+    readonly name: "withdraw";
+    readonly type: "function";
+    readonly inputs: readonly [{
+        readonly name: "wad";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}];
+export declare const UNISWAP_ROUTER_ABI: readonly [{
+    readonly name: "exactInputSingle";
+    readonly type: "function";
+    readonly inputs: readonly [{
+        readonly name: "params";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "tokenIn";
+            readonly type: "address";
+        }, {
+            readonly name: "tokenOut";
+            readonly type: "address";
+        }, {
+            readonly name: "fee";
+            readonly type: "uint24";
+        }, {
+            readonly name: "recipient";
+            readonly type: "address";
+        }, {
+            readonly name: "amountIn";
+            readonly type: "uint256";
+        }, {
+            readonly name: "amountOutMinimum";
+            readonly type: "uint256";
+        }, {
+            readonly name: "sqrtPriceLimitX96";
+            readonly type: "uint160";
+        }];
+    }];
+    readonly outputs: readonly [{
+        readonly name: "amountOut";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "payable";
+}];

package/dist/src/treasury/abi.js

@@ -0,0 +1,71 @@
+export const ERC20_ABI = [
+    {
+        name: "transfer",
+        type: "function",
+        inputs: [
+            { name: "to", type: "address" },
+            { name: "amount", type: "uint256" },
+        ],
+        outputs: [{ type: "bool" }],
+        stateMutability: "nonpayable",
+    },
+    {
+        name: "balanceOf",
+        type: "function",
+        inputs: [{ name: "account", type: "address" }],
+        outputs: [{ type: "uint256" }],
+        stateMutability: "view",
+    },
+    {
+        name: "approve",
+        type: "function",
+        inputs: [
+            { name: "spender", type: "address" },
+            { name: "amount", type: "uint256" },
+        ],
+        outputs: [{ type: "bool" }],
+        stateMutability: "nonpayable",
+    },
+    {
+        name: "allowance",
+        type: "function",
+        inputs: [
+            { name: "owner", type: "address" },
+            { name: "spender", type: "address" },
+        ],
+        outputs: [{ type: "uint256" }],
+        stateMutability: "view",
+    },
+];
+export const WETH_ABI = [
+    {
+        name: "withdraw",
+        type: "function",
+        inputs: [{ name: "wad", type: "uint256" }],
+        outputs: [],
+        stateMutability: "nonpayable",
+    },
+];
+export const UNISWAP_ROUTER_ABI = [
+    {
+        name: "exactInputSingle",
+        type: "function",
+        inputs: [
+            {
+                name: "params",
+                type: "tuple",
+                components: [
+                    { name: "tokenIn", type: "address" },
+                    { name: "tokenOut", type: "address" },
+                    { name: "fee", type: "uint24" },
+                    { name: "recipient", type: "address" },
+                    { name: "amountIn", type: "uint256" },
+                    { name: "amountOutMinimum", type: "uint256" },
+                    { name: "sqrtPriceLimitX96", type: "uint160" },
+                ],
+            },
+        ],
+        outputs: [{ name: "amountOut", type: "uint256" }],
+        stateMutability: "payable",
+    },
+];

package/dist/src/treasury/cycle.d.ts

@@ -0,0 +1,16 @@
+import type { Logger } from "pino";
+import { type Treasury } from "./index.js";
+export type TreasuryCycleResult = {
+    tokenClaimed: bigint;
+    wethClaimed: bigint;
+    tokenBurned: bigint;
+    tokenToDev: bigint;
+    wethToDev: bigint;
+    wethUnwrapped: bigint;
+    wethSwapped: bigint;
+    computeExtended: boolean;
+    txHashes: string[];
+    cycledAt: string;
+};
+export declare function runTreasuryCycle(treasury: Treasury, log: Logger): Promise<void>;
+export declare function startTreasury(treasury: Treasury, log: Logger): () => void;