yappr 0.1.0

package/dist/src/cron/schedule.js

@@ -0,0 +1,154 @@
+import { config } from "../config.js";
+const TIME_RE = /^([01]?\d|2[0-3]):([0-5]\d)$/; // HH:MM, 24h
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/; // YYYY-MM-DD
+function validTimezone(tz) {
+    // Intl is the source of truth for zone names: constructing a formatter with an
+    // unknown timeZone throws a RangeError. "UTC" is itself a valid IANA zone.
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: tz });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Build a validated Schedule from the raw string params the LLM passed to the
+// skill. Returns `{ error }` with a message written FOR the model (it becomes the
+// skill observation), so a bad request turns into a helpful reply to the user.
+export function validateSchedule(raw) {
+    const type = raw.schedule;
+    if (type === "interval") {
+        const minutes = Number(raw.minutes);
+        if (!Number.isFinite(minutes) || minutes <= 0) {
+            return { error: `interval schedules need a positive "minutes" param (got "${raw.minutes}")` };
+        }
+        if (minutes < config.cronMinIntervalMin) {
+            return { error: `interval too short — the minimum is every ${config.cronMinIntervalMin} minute${config.cronMinIntervalMin === 1 ? "" : "s"}` };
+        }
+        return { type: "interval", minutes: Math.round(minutes) };
+    }
+    if (type === "once") {
+        if (raw.minutes !== undefined && raw.minutes !== "") {
+            const minutes = Number(raw.minutes);
+            if (!Number.isFinite(minutes) || minutes <= 0) {
+                return { error: `one-shot relative schedules need a positive "minutes" param (got "${raw.minutes}")` };
+            }
+            return { type: "once", minutes: Math.round(minutes) };
+        }
+        // Absolute one-shot: time (+ optional date) in an explicit timezone.
+        const abs = validateWallClock(raw, "a one-shot at a specific time");
+        if ("error" in abs)
+            return abs;
+        return { type: "once", date: raw.date || undefined, time: abs.time, timezone: abs.timezone };
+    }
+    if (type === "daily") {
+        const abs = validateWallClock(raw, "a daily schedule");
+        if ("error" in abs)
+            return abs;
+        return { type: "daily", time: abs.time, timezone: abs.timezone };
+    }
+    return { error: `unknown schedule type "${type}" — use "interval", "once" or "daily"` };
+}
+// Shared validation for wall-clock (time + timezone) schedules. The timezone is
+// REQUIRED by design: if the user didn't state one, the agent must ask, not guess.
+function validateWallClock(raw, what) {
+    if (!raw.time || !TIME_RE.test(raw.time)) {
+        return { error: `${what} needs a "time" param in 24h HH:MM format (got "${raw.time ?? ""}")` };
+    }
+    if (!raw.timezone) {
+        return {
+            error: `${what} needs an explicit timezone — ask the user which timezone they mean (an IANA name like Europe/Paris, America/New_York, or UTC)`,
+        };
+    }
+    if (!validTimezone(raw.timezone)) {
+        return { error: `unknown timezone "${raw.timezone}" — ask the user for an IANA timezone name like Europe/Paris or UTC` };
+    }
+    if (raw.date && !DATE_RE.test(raw.date)) {
+        return { error: `"date" must be YYYY-MM-DD (got "${raw.date}")` };
+    }
+    return { time: raw.time, timezone: raw.timezone };
+}
+// ── Wall-clock → instant conversion ─────────────────────────────────────────
+//
+// JS has no native "instant for 09:00 on 2026-06-12 in Europe/Paris". Intl can
+// only go the other way (instant → zone-local wall time), so we invert it by
+// fixed-point iteration:
+//
+//   1. guess: treat the wall time as if it were UTC → t0
+//   2. format t0 in the target zone, measure how far the result is from the
+//      wanted wall time, and shift the guess by that difference
+//   3. repeat once — the zone offset is piecewise-constant, so this converges
+//      in ≤2 steps even across DST transitions.
+//
+// DST edge cases (documented, accepted): a nonexistent local time (the
+// spring-forward gap, e.g. 02:30 the night clocks jump) resolves ~1h shifted;
+// an ambiguous time (fall-back hour) resolves to one of the two instants.
+// Wall-clock fields of `t` in `timeZone`, read via Intl (en-CA gives YYYY-MM-DD).
+function wallParts(t, timeZone) {
+    const parts = new Intl.DateTimeFormat("en-CA", {
+        timeZone, year: "numeric", month: "2-digit", day: "2-digit",
+        hour: "2-digit", minute: "2-digit", hourCycle: "h23",
+    }).formatToParts(t);
+    const get = (type) => Number(parts.find((p) => p.type === type)?.value);
+    return { y: get("year"), mo: get("month"), d: get("day"), h: get("hour"), mi: get("minute") };
+}
+// Epoch ms of `y-mo-d hh:mm` wall time in `timeZone` (fixed-point, see above).
+function zonedTimeToInstant(y, mo, d, hh, mm, timeZone) {
+    let t = Date.UTC(y, mo - 1, d, hh, mm);
+    for (let i = 0; i < 2; i++) {
+        const w = wallParts(t, timeZone);
+        const diff = Date.UTC(w.y, w.mo - 1, w.d, w.h, w.mi) - Date.UTC(y, mo - 1, d, hh, mm);
+        t -= diff;
+    }
+    return t;
+}
+const DAY_MS = 24 * 60 * 60 * 1000;
+// Next occurrence of `s` strictly after `after` (epoch ms). Returns null for a
+// spent one-shot (absolute time already in the past — the runner treats overdue
+// one-shots separately; at creation the store rejects null).
+export function nextRunAt(s, after) {
+    if (s.type === "interval")
+        return after + s.minutes * 60_000;
+    if (s.type === "once") {
+        if (s.minutes !== undefined)
+            return after + s.minutes * 60_000;
+        const [hh, mm] = s.time.split(":").map(Number);
+        if (s.date) {
+            const [y, mo, d] = s.date.split("-").map(Number);
+            const t = zonedTimeToInstant(y, mo, d, hh, mm, s.timezone);
+            return t > after ? t : null;
+        }
+        // No date: the next time the wall clock reads HH:MM in that zone.
+        return nextWallClock(hh, mm, s.timezone, after);
+    }
+    // daily
+    const [hh, mm] = s.time.split(":").map(Number);
+    return nextWallClock(hh, mm, s.timezone, after);
+}
+// Next instant after `after` at which it is HH:MM in `timeZone`: try today (in
+// the zone), then advance day by day. The +DAY_MS probe moves the wall-clock
+// date forward; the exact instant is recomputed from the new date each step, so
+// DST days (23h/25h long) can't drift the result.
+function nextWallClock(hh, mm, timeZone, after) {
+    let probe = after;
+    for (let i = 0; i < 3; i++) {
+        const w = wallParts(probe, timeZone);
+        const t = zonedTimeToInstant(w.y, w.mo, w.d, hh, mm, timeZone);
+        if (t > after)
+            return t;
+        probe += DAY_MS;
+    }
+    // Unreachable (within 2 days there is always a next HH:MM), but never loop forever.
+    return after + DAY_MS;
+}
+// Human/one-line form for logs and the skill's `list` output.
+export function describeSchedule(s) {
+    if (s.type === "interval")
+        return `every ${s.minutes} min`;
+    if (s.type === "once") {
+        if (s.minutes !== undefined)
+            return `once, ${s.minutes} min after creation`;
+        return `once at ${s.date ? `${s.date} ` : ""}${s.time} ${s.timezone}`;
+    }
+    return `daily at ${s.time} ${s.timezone}`;
+}

package/dist/src/cron/store.d.ts

@@ -0,0 +1,46 @@
+import type { Tweet } from "../x/types.js";
+import { type Schedule, describeSchedule } from "./schedule.js";
+export type CronJob = {
+    id: number;
+    prompt: string;
+    schedule: Schedule;
+    creatorId: string;
+    creatorHandle: string;
+    sourceTweet: Tweet | null;
+    enabled: boolean;
+    nextRunAt: number;
+    lastRunAt: number | null;
+    lastResult: string | null;
+    lastError: string | null;
+    runs: number;
+    consecutiveFailures: number;
+    createdAt: number;
+};
+export declare function addCronJob(input: {
+    prompt: string;
+    schedule: Schedule;
+    tweet: Tweet;
+}): {
+    job: CronJob;
+} | {
+    error: string;
+};
+export declare function getCronJob(id: number): CronJob | null;
+export declare function listCronJobs(opts?: {
+    includeDisabled?: boolean;
+    creatorId?: string;
+}): CronJob[];
+export declare function setCronJobEnabled(id: number, enabled: boolean): boolean;
+export declare function resumeCronJob(id: number): {
+    job: CronJob;
+} | {
+    error: string;
+};
+export declare function removeCronJob(id: number): boolean;
+export declare function dueCronJobs(now: number): CronJob[];
+export declare function armCronJob(id: number, nextRunAt: number | null): void;
+export declare function markCronRun(id: number, outcome: {
+    result?: string;
+    error?: string;
+}): void;
+export { describeSchedule };

package/dist/src/cron/store.js

@@ -0,0 +1,220 @@
+import { withSchema } from "../db.js";
+import { config } from "../config.js";
+import { nextRunAt, describeSchedule } from "./schedule.js";
+// Persistent cron jobs in the shared SQLite DB (see db.ts) — same pattern as
+// state.ts/stats.ts: the feature owns its table, the DB survives redeploys (it
+// lives at DB_PATH outside the wiped project dir) and rides the dashboard's
+// backup system. The DB row is the ONLY scheduler state: there is no in-memory
+// timer registry to keep in sync — the runner just reads `next_run_at` (see
+// runner.ts for why that design).
+//
+// Security model: the stored prompt is replayed later through an LLM that can
+// call skills, so treat it like code — it is shown verbatim by `list`, logged on
+// every run, and grants nothing by itself: the creator's privileges are
+// re-derived from ADMIN_HANDLES at each run (runner.ts), never from this table.
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS cron_jobs (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    prompt          TEXT NOT NULL,
+    schedule        TEXT NOT NULL,
+    creator_id      TEXT NOT NULL,
+    creator_handle  TEXT NOT NULL,
+    source_tweet    TEXT,
+    enabled         INTEGER NOT NULL DEFAULT 1,
+    next_run_at     INTEGER NOT NULL,
+    last_run_at     INTEGER,
+    last_result     TEXT,
+    last_error      TEXT,
+    runs            INTEGER NOT NULL DEFAULT 0,
+    consecutive_failures INTEGER NOT NULL DEFAULT 0,
+    created_at      INTEGER NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS idx_cron_due ON cron_jobs(enabled, next_run_at);
+`;
+const conn = () => withSchema(SCHEMA);
+function rowToJob(r) {
+    let sourceTweet = null;
+    try {
+        sourceTweet = r.source_tweet ? JSON.parse(r.source_tweet) : null;
+    }
+    catch { /* keep null */ }
+    return {
+        id: r.id,
+        prompt: r.prompt,
+        schedule: JSON.parse(r.schedule),
+        creatorId: r.creator_id,
+        creatorHandle: r.creator_handle,
+        sourceTweet,
+        enabled: r.enabled === 1,
+        nextRunAt: r.next_run_at,
+        lastRunAt: r.last_run_at,
+        lastResult: r.last_result,
+        lastError: r.last_error,
+        runs: r.runs,
+        consecutiveFailures: r.consecutive_failures,
+        createdAt: r.created_at,
+    };
+}
+// Create a job. Error strings are written for the LLM observation (the skill
+// returns them verbatim), so they read as something the model can relay to the
+// user. The creator is snapshotted from the CREATING tweet's author — params are
+// model-controlled, the tweet author is not.
+// Caps on ACTIVE (enabled = 1) jobs — every run costs money, so disabled jobs
+// don't count. Checked at creation AND on resume (resumeCronJob): if resume
+// skipped it, pause-create-resume cycles would bypass the limits. The per-user
+// cap on top of the global one matters once the skill is opened to non-admins —
+// a single user must not be able to exhaust the pool.
+function checkCaps(d, creatorId) {
+    const active = d.prepare("SELECT COUNT(*) AS n FROM cron_jobs WHERE enabled = 1").get();
+    if (active.n >= config.cronMaxJobs) {
+        return { error: `cron job limit reached (${config.cronMaxJobs} active jobs) — remove one first` };
+    }
+    const own = d.prepare("SELECT COUNT(*) AS n FROM cron_jobs WHERE enabled = 1 AND creator_id = ?")
+        .get(creatorId);
+    if (own.n >= config.cronMaxJobsPerUser) {
+        return { error: `you already have ${own.n} active cron jobs (limit ${config.cronMaxJobsPerUser}) — remove one first` };
+    }
+    return { ok: true };
+}
+export function addCronJob(input) {
+    const d = conn();
+    if (!d)
+        return { error: "cron storage unavailable" };
+    const prompt = input.prompt?.trim();
+    if (!prompt)
+        return { error: 'missing "prompt" — the self-contained instruction to run on schedule' };
+    const author = input.tweet.author;
+    if (!author?.id || !author?.username) {
+        return { error: "could not identify the requesting user from the tweet" };
+    }
+    const caps = checkCaps(d, author.id);
+    if ("error" in caps)
+        return caps;
+    const now = Date.now();
+    // Relative schedules ("in/every N minutes") anchor at the asking tweet's
+    // created_at, not at job creation: poll lag + the creating agent loop add
+    // ~15-40s before this row exists, and the user counts from when they tweeted.
+    // Falls back to `now` when created_at is missing/unparseable (or ahead of our
+    // clock). If processing was so slow that anchor+delay is already past, the
+    // job simply fires on the next tick, like any overdue job.
+    const isRelative = input.schedule.type === "interval" ||
+        (input.schedule.type === "once" && input.schedule.minutes !== undefined);
+    const tweetAt = Date.parse(input.tweet.created_at ?? "");
+    const anchor = isRelative && Number.isFinite(tweetAt) && tweetAt <= now ? tweetAt : now;
+    const next = nextRunAt(input.schedule, anchor);
+    // null = an absolute one-shot already in the past — refuse rather than store a
+    // job that would either never fire or fire "late" immediately.
+    if (next === null)
+        return { error: "that time is already in the past — pick a future time" };
+    const res = d.prepare(`
+    INSERT INTO cron_jobs (prompt, schedule, creator_id, creator_handle, source_tweet, next_run_at, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(prompt, JSON.stringify(input.schedule), author.id, author.username.toLowerCase(), JSON.stringify(input.tweet), next, now);
+    const job = getCronJob(Number(res.lastInsertRowid));
+    return job ? { job } : { error: "failed to store the cron job" };
+}
+export function getCronJob(id) {
+    const d = conn();
+    if (!d)
+        return null;
+    const row = d.prepare("SELECT * FROM cron_jobs WHERE id = ?").get(id);
+    return row ? rowToJob(row) : null;
+}
+// Disabled jobs (spent one-shots, paused, auto-paused after repeated failures)
+// stay listed until removed — `list` is the audit surface for stored prompts.
+// `creatorId` filters to one user's jobs (matched on the stable X user id, not
+// the handle, so renames don't detach a user from their jobs).
+export function listCronJobs(opts = {}) {
+    const d = conn();
+    if (!d)
+        return [];
+    const { includeDisabled = true, creatorId } = opts;
+    const where = [];
+    const args = [];
+    if (!includeDisabled)
+        where.push("enabled = 1");
+    if (creatorId) {
+        where.push("creator_id = ?");
+        args.push(creatorId);
+    }
+    const sql = `SELECT * FROM cron_jobs${where.length ? ` WHERE ${where.join(" AND ")}` : ""} ORDER BY id`;
+    return d.prepare(sql).all(...args).map(rowToJob);
+}
+// Disable only — resuming goes through resumeCronJob (cap re-check + re-arm).
+export function setCronJobEnabled(id, enabled) {
+    const d = conn();
+    if (!d)
+        return false;
+    if (enabled)
+        return "job" in resumeCronJob(id);
+    return d.prepare("UPDATE cron_jobs SET enabled = 0 WHERE id = ?").run(id).changes > 0;
+}
+// Re-arm a paused job. Subject to the same active-job caps as creation —
+// otherwise pause-create-resume cycles would bypass the limits — and
+// next_run_at is recomputed from now, otherwise a job paused past its slot
+// would fire immediately on resume.
+export function resumeCronJob(id) {
+    const d = conn();
+    if (!d)
+        return { error: "cron storage unavailable" };
+    const job = getCronJob(id);
+    if (!job)
+        return { error: `no cron job #${id}` };
+    if (job.enabled)
+        return { job }; // already running — nothing to do
+    const caps = checkCaps(d, job.creatorId);
+    if ("error" in caps)
+        return caps;
+    const next = nextRunAt(job.schedule, Date.now());
+    if (next === null)
+        return { error: `cron #${id} can't be resumed — its one-shot time is already spent` };
+    d.prepare("UPDATE cron_jobs SET enabled = 1, next_run_at = ?, consecutive_failures = 0 WHERE id = ?")
+        .run(next, id);
+    return { job: getCronJob(id) };
+}
+export function removeCronJob(id) {
+    const d = conn();
+    if (!d)
+        return false;
+    return d.prepare("DELETE FROM cron_jobs WHERE id = ?").run(id).changes > 0;
+}
+// Runner internals ───────────────────────────────────────────────────────────
+export function dueCronJobs(now) {
+    const d = conn();
+    if (!d)
+        return [];
+    return d.prepare("SELECT * FROM cron_jobs WHERE enabled = 1 AND next_run_at <= ? ORDER BY next_run_at")
+        .all(now).map(rowToJob);
+}
+// Advance the job's clock — called by the runner BEFORE executing, so a crash
+// mid-run skips the slot instead of double-firing on restart (at-most-once).
+// `enabled = 0` here is how one-shots are spent.
+export function armCronJob(id, nextRunAt) {
+    const d = conn();
+    if (!d)
+        return;
+    if (nextRunAt === null) {
+        d.prepare("UPDATE cron_jobs SET enabled = 0 WHERE id = ?").run(id);
+    }
+    else {
+        d.prepare("UPDATE cron_jobs SET next_run_at = ? WHERE id = ?").run(nextRunAt, id);
+    }
+}
+export function markCronRun(id, outcome) {
+    const d = conn();
+    if (!d)
+        return;
+    if (outcome.error !== undefined) {
+        d.prepare(`
+      UPDATE cron_jobs SET last_run_at = ?, last_error = ?, runs = runs + 1,
+        consecutive_failures = consecutive_failures + 1 WHERE id = ?
+    `).run(Date.now(), outcome.error, id);
+    }
+    else {
+        d.prepare(`
+      UPDATE cron_jobs SET last_run_at = ?, last_result = ?, last_error = NULL, runs = runs + 1,
+        consecutive_failures = 0 WHERE id = ?
+    `).run(Date.now(), outcome.result ?? "", id);
+    }
+}
+export { describeSchedule };

package/dist/src/db.d.ts

@@ -0,0 +1,4 @@
+import "dotenv/config";
+import Database from "better-sqlite3";
+export declare function getDb(): Database.Database | null;
+export declare function withSchema(ddl: string): Database.Database | null;

package/dist/src/db.js

@@ -0,0 +1,53 @@
+import "dotenv/config";
+import { resolve } from "node:path";
+import Database from "better-sqlite3";
+// The single SQLite database for the whole app (yappr.db). One shared connection that
+// every feature needing storage opens through getDb() — stats today, more tables
+// later. Each feature owns its own `CREATE TABLE IF NOT EXISTS` (see stats.ts), so
+// adding a table is local to that feature; this module just owns the connection and
+// pragmas.
+//
+// Path comes from DB_PATH. On the server that points *outside* the redeploy-wiped
+// /yappr dir (so data survives deploys); locally it defaults to ./yappr.db. Opening
+// is best-effort: a DB that won't open returns null, and callers degrade to no-ops
+// rather than crashing the agent.
+const DB_PATH = process.env.DB_PATH || resolve(process.cwd(), "yappr.db");
+let db = null;
+let initFailed = false;
+export function getDb() {
+    if (db)
+        return db;
+    if (initFailed)
+        return null;
+    try {
+        const handle = new Database(DB_PATH);
+        handle.pragma("journal_mode = WAL"); // concurrent readers (the CLI) alongside the writer
+        handle.pragma("busy_timeout = 5000"); // wait out a brief writer lock instead of erroring
+        db = handle;
+        return db;
+    }
+    catch {
+        initFailed = true;
+        return null;
+    }
+}
+const ensured = new Set();
+// Get the shared connection with a feature's tables guaranteed to exist. Pass the
+// feature's `CREATE TABLE IF NOT EXISTS …` DDL; it runs once per process (memoised on
+// the DDL text). Returns null if the DB can't be opened, so callers stay best-effort.
+// This is how each feature owns its own schema while sharing one connection.
+export function withSchema(ddl) {
+    const d = getDb();
+    if (!d)
+        return null;
+    if (!ensured.has(ddl)) {
+        try {
+            d.exec(ddl);
+            ensured.add(ddl);
+        }
+        catch {
+            return null;
+        }
+    }
+    return d;
+}

package/dist/src/hooks/loader.d.ts

@@ -0,0 +1 @@
+export declare function loadHooks(): Promise<void>;

package/dist/src/hooks/loader.js

@@ -0,0 +1,17 @@
+import { registerHooks } from "./registry.js";
+import { log } from "../log.js";
+import { listHooks, importConfigModule } from "../config-loader.js";
+export async function loadHooks() {
+    for (const { name, modulePath } of await listHooks()) {
+        try {
+            const mod = await importConfigModule(modulePath);
+            if (mod.hooks && typeof mod.hooks === "object") {
+                registerHooks(mod.hooks);
+                log.info({ file: name }, `hook loaded: ${name}`);
+            }
+        }
+        catch (err) {
+            log.error({ file: name, err: err.message }, `hook load failed: ${name}`);
+        }
+    }
+}

package/dist/src/hooks/registry.d.ts

@@ -0,0 +1,17 @@
+import type { AgentHooks } from "./types.js";
+import type { Tweet } from "../x/types.js";
+import type { TreasuryBalances } from "../treasury/index.js";
+import type { TreasuryCycleResult } from "../treasury/cycle.js";
+export declare function registerHooks(hooks: AgentHooks): void;
+export declare function runOnMention(tweet: Tweet): Promise<void>;
+export declare function runShouldReply(tweet: Tweet): Promise<boolean>;
+export declare function runOnBeforeInference(tweet: Tweet, question: string, context: string | undefined): Promise<{
+    question: string;
+    context: string | undefined;
+}>;
+export declare function runOnAfterInference(question: string, output: string): Promise<string>;
+export declare function runOnBeforeReply(tweet: Tweet, text: string): Promise<string | null>;
+export declare function runOnAfterReply(tweet: Tweet, text: string): Promise<void>;
+export declare function runOnBeforeClaim(balances: TreasuryBalances): Promise<void>;
+export declare function runOnAfterClaim(result: TreasuryCycleResult): Promise<void>;
+export declare function runOnSwap(kind: "burn" | "swap", amount: bigint): Promise<void>;

package/dist/src/hooks/registry.js

@@ -0,0 +1,78 @@
+// Every loaded hook file registers its own AgentHooks set; they COMPOSE rather
+// than overwrite (multiple files can implement the same hook — e.g. user-memory
+// and holder both use onBeforeInference; a spread-merge here used to let the
+// last file silently clobber the others). Sets run in registration order (the
+// loader's alphabetical file order):
+//   - observers (onMention, onAfterReply, treasury hooks) all run;
+//   - shouldReply is a veto chain — any false skips the reply;
+//   - transformers (onBeforeInference, onAfterInference, onBeforeReply) thread
+//     their value through each set in turn; onBeforeReply short-circuits on null.
+const _hookSets = [];
+export function registerHooks(hooks) {
+    _hookSets.push(hooks);
+}
+export async function runOnMention(tweet) {
+    for (const h of _hookSets) {
+        if (h.onMention)
+            await h.onMention(tweet);
+    }
+}
+export async function runShouldReply(tweet) {
+    for (const h of _hookSets) {
+        if (h.shouldReply && !(await h.shouldReply(tweet)))
+            return false;
+    }
+    return true;
+}
+export async function runOnBeforeInference(tweet, question, context) {
+    let cur = { question, context };
+    for (const h of _hookSets) {
+        if (h.onBeforeInference)
+            cur = await h.onBeforeInference({ tweet, ...cur });
+    }
+    return cur;
+}
+export async function runOnAfterInference(question, output) {
+    let cur = output;
+    for (const h of _hookSets) {
+        if (h.onAfterInference)
+            cur = await h.onAfterInference({ question, output: cur });
+    }
+    return cur;
+}
+export async function runOnBeforeReply(tweet, text) {
+    let cur = text;
+    for (const h of _hookSets) {
+        if (!h.onBeforeReply)
+            continue;
+        const next = await h.onBeforeReply({ tweet, text: cur });
+        if (next === null)
+            return null; // vetoed — later sets don't resurrect it
+        cur = next;
+    }
+    return cur;
+}
+export async function runOnAfterReply(tweet, text) {
+    for (const h of _hookSets) {
+        if (h.onAfterReply)
+            await h.onAfterReply({ tweet, text });
+    }
+}
+export async function runOnBeforeClaim(balances) {
+    for (const h of _hookSets) {
+        if (h.onBeforeClaim)
+            await h.onBeforeClaim(balances);
+    }
+}
+export async function runOnAfterClaim(result) {
+    for (const h of _hookSets) {
+        if (h.onAfterClaim)
+            await h.onAfterClaim(result);
+    }
+}
+export async function runOnSwap(kind, amount) {
+    for (const h of _hookSets) {
+        if (h.onSwap)
+            await h.onSwap({ kind, amount });
+    }
+}

package/dist/src/hooks/types.d.ts

@@ -0,0 +1,45 @@
+import type { Tweet } from "../x/types.js";
+import type { TreasuryBalances } from "../treasury/index.js";
+import type { TreasuryCycleResult } from "../treasury/cycle.js";
+export type OnMentionHook = (tweet: Tweet) => Promise<void> | void;
+export type ShouldReplyHook = (tweet: Tweet) => Promise<boolean> | boolean;
+export type OnBeforeInferenceHook = (input: {
+    tweet: Tweet;
+    question: string;
+    context: string | undefined;
+}) => Promise<{
+    question: string;
+    context: string | undefined;
+}> | {
+    question: string;
+    context: string | undefined;
+};
+export type OnAfterInferenceHook = (input: {
+    question: string;
+    output: string;
+}) => Promise<string> | string;
+export type OnBeforeReplyHook = (input: {
+    tweet: Tweet;
+    text: string;
+}) => Promise<string | null> | string | null;
+export type OnAfterReplyHook = (input: {
+    tweet: Tweet;
+    text: string;
+}) => Promise<void> | void;
+export type OnBeforeClaimHook = (balances: TreasuryBalances) => Promise<void> | void;
+export type OnAfterClaimHook = (result: TreasuryCycleResult) => Promise<void> | void;
+export type OnSwapHook = (input: {
+    kind: "burn" | "swap";
+    amount: bigint;
+}) => Promise<void> | void;
+export type AgentHooks = {
+    onMention?: OnMentionHook;
+    shouldReply?: ShouldReplyHook;
+    onBeforeInference?: OnBeforeInferenceHook;
+    onAfterInference?: OnAfterInferenceHook;
+    onBeforeReply?: OnBeforeReplyHook;
+    onAfterReply?: OnAfterReplyHook;
+    onBeforeClaim?: OnBeforeClaimHook;
+    onAfterClaim?: OnAfterClaimHook;
+    onSwap?: OnSwapHook;
+};

package/dist/src/hooks/types.js

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

package/dist/src/index.d.ts

@@ -0,0 +1,25 @@
+export type { SkillHandler, SkillResult, SkillDef, SkillAccess } from "./skills/types.js";
+export type { AgentHooks } from "./hooks/types.js";
+export type { Tweet, SearchResponse } from "./x/types.js";
+export type { Treasury, TreasuryBalances } from "./treasury/index.js";
+export type { TreasuryCycleResult } from "./treasury/cycle.js";
+export type { CronJob } from "./cron/store.js";
+export type { Schedule } from "./cron/schedule.js";
+export type { SkillStore, SkillStoreEntry } from "./storage.js";
+export type { Database } from "better-sqlite3";
+export { agentPrompt } from "./agent-prompt.js";
+export { getTreasury } from "./treasury/index.js";
+export { log } from "./log.js";
+export { config } from "./config.js";
+export { payFetch, paidUsd, walletAddress } from "./wallet.js";
+export { chat, llmCreditBalance } from "./llm/index.js";
+export type { ChatMessage, ContentPart } from "./llm/index.js";
+export { summary } from "./stats.js";
+export type { Summary, SpendType } from "./stats.js";
+export { checkHolderAccess } from "./skills/holder-access.js";
+export { skillStore } from "./storage.js";
+export { withSchema } from "./db.js";
+export { addCronJob, listCronJobs, getCronJob, setCronJobEnabled, resumeCronJob, removeCronJob, describeSchedule } from "./cron/store.js";
+export { validateSchedule } from "./cron/schedule.js";
+export { checkCronCapability } from "./cron/capability.js";
+export * from "./x/client.js";