@pickhooks/sdk 0.0.0-stage → 0.4.0

package/dist/agents.js

@@ -0,0 +1,667 @@
+import { encodeFunctionData, formatEther, isAddressEqual, parseAbi, parseEventLogs } from "viem";
+import { agentsDeskAbi, agentsFactoryAbi, agentsHookAbi } from "./abis/agents.js";
+import { clPoolManagerAbi, erc20Abi } from "./abis/common.js";
+import { ZERO_ADDRESS } from "./addresses.js";
+import { AGENT_LIMITS, AGENT_RULES, AGENT_RULE_BY_KIND, ALLOWED_MASK, ANSWER_SCHEMA, BUCKETS, ENVELOPE_TUPLE, OBJECTIVES, PERSONALITIES, PROGRAM_TUPLE, agentKindsOf, decodeProgram, describeProgram, noteHash, readPlan, starterEnvelope, starterProgram, systemPrompt, toPlan, toProgram, userPrompt, } from "./agents-catalog.js";
+import { ruleText } from "./coins.js";
+import { PickhooksError, decodeRevert, explain, findRevertData, toPickhooksError } from "./errors.js";
+import { blockedKind, buildInfiSwap, infiPriceBnb, infiQuote, permit2Approvals, poolIdOf, toKey } from "./infinity.js";
+import { chainDeadline, minusBps, sendAll, sendTx, signer } from "./tx.js";
+import { approvalFor } from "./v3.js";
+const PLAIN = parseAbi(["function name() view returns (string)", "function symbol() view returns (string)", "function metadata() view returns (string)"]);
+const randomSalt = () => {
+    const b = new Uint8Array(32);
+    globalThis.crypto.getRandomValues(b);
+    return `0x${Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("")}`;
+};
+/** AgentsLimits' Bad(what) reasons, in words (the chain's strings are the keys). */
+const AGENT_BAD = {
+    maxFee: "The coin's fee cap must be between 1 % and 10 %.",
+    maxCreator: "The creator can get at most 50 % of the coin's part.",
+    allowed: "The envelope allows a rule an agent may never use (a gate, or one that can hold sells).",
+    notice: "The notice must be between 10 minutes and a day.",
+    minGap: "The gap between changes must be between 1 hour and 7 days.",
+    veto: "The veto share must be between 1 % and 50 % of the coins outside the pool.",
+    fire: "The fire share must be between 1 % and 50 % of the coins outside the pool.",
+    buyFee: "The buy fee must be between 1 % and the coin's cap.",
+    sellFee: "The sell fee must be between 1 % and the coin's cap.",
+    creator: "The creator's share is over the coin's cap.",
+    routing: "The routing shares add up to more than 100 %.",
+    "rule not allowed": "A rule in this program is not allowed by the coin's envelope.",
+    "too many rules": "At most 8 rules at once.",
+    "rewards without rule": "A rewards share needs the buyer_rewards rule on.",
+    "jackpot without rule": "A jackpot share needs the jackpot rule on.",
+    maxTrade: "Max per buy: 0.1 % to 100 % of supply.",
+    buysPerBlock: "Anti bundle: at least 1 buy per block.",
+    maxGasPrice: "Gas cap: at least 0.05 gwei.",
+    raiseBps: "Raise: 0.01 % to 100 %.",
+    raiseReset: "Raise: the reset between 10 seconds and a day.",
+    minBuy: "Min buy: at most 1 % of supply.",
+    slowSeconds: "Slow mode: 1 second to an hour.",
+    buyLimit: "Buy limit: at least 1 buy.",
+    dumpBuy: "Anti dump: the buy cap between 0.1 % and 100 % of supply.",
+    dumpSell: "Anti dump: the sell cap between 0.1 % and 100 % of supply.",
+    taperEnd: "Taper: the end cap between 0.05 % and 100 %.",
+    taperStart: "Taper: the start cap must be at least the end cap and at most 100 %.",
+    taperSold: "Taper: the curve share between 1 % and 100 %.",
+    cooldown: "Cooldown: 1 second to a day.",
+    hours: "Market hours: open and close hours from 0 to 23, not the same.",
+    weekdays: "Market hours: at least one weekday.",
+    "market hours must keep sells open": "An agent's market hours only ever close buys: sells stay open.",
+    sellPeriod: "Sell window: the period between a minute and a day.",
+    sellWindow: "Sell window: at least a minute and shorter than the period.",
+    tickSeconds: "Tick tock: a turn between a minute and a day.",
+    bellSeconds: "Opening bell: 1 second to a day.",
+    bellSold: "Opening bell: the curve share at most 100 %.",
+    rewardPerBuy: "Buyer rewards: the reward must be more than 0.",
+    jackpotSilence: "Jackpot: the quiet time between 30 seconds and a day.",
+    jackpotShare: "Jackpot: the share between 0.01 % and 100 % of the pot.",
+    dipBps: "Dip only: 1 % to 99 % under the peak.",
+    jackpotMinBuy: "Jackpot: the smallest qualifying buy at most 1 % of supply.",
+    rewardMinBuy: "Buyer rewards: the smallest qualifying buy at most 1 % of supply.",
+    "tick tock with sell window": "Tick tock and a sell window cannot be on together.",
+};
+const f = (x) => formatEther(x);
+const iso = (t) => new Date(t * 1000).toISOString();
+export function agentsModule(ctx) {
+    const { pub, a } = ctx;
+    const F = a.agentsFactory;
+    const FA = agentsFactoryAbi;
+    const HA = agentsHookAbi;
+    const DA = agentsDeskAbi;
+    let addrs = null;
+    const keys = new Map();
+    const on = () => !isAddressEqual(F, ZERO_ADDRESS);
+    const need = () => {
+        if (!on())
+            throw new PickhooksError("Agents are not on mainnet yet.", { code: "input" });
+        return F;
+    };
+    const call = (address, abi, functionName, args = []) => pub.readContract({ address, abi, functionName, args });
+    async function contracts() {
+        if (!addrs) {
+            const [hook, desk] = await Promise.all([call(need(), FA, "hook"), call(need(), FA, "desk")]);
+            addrs = { hook, desk };
+        }
+        return addrs;
+    }
+    const hook = async () => (await contracts()).hook;
+    const desk = async () => (await contracts()).desk;
+    async function key(token) {
+        const hit = keys.get(token.toLowerCase());
+        if (hit)
+            return hit;
+        const k = toKey(await call(await hook(), HA, "poolKeyOf", [token]));
+        if (/^0x0{40}$/i.test(k.hooks))
+            throw new PickhooksError("This is not an agent coin.", { code: "input" });
+        keys.set(token.toLowerCase(), k);
+        return k;
+    }
+    const count = async () => Number(await call(need(), FA, "coinCount"));
+    const isCoin = async (token) => on() && (await call(F, FA, "isCoin", [token]).catch(() => false)) === true;
+    /** an error of the desk, the hook or the factory as a sentence (AgentsLimits' reasons, a refusing rule, the rest) */
+    async function agentError(e, fallback, token) {
+        if (e instanceof PickhooksError)
+            return e;
+        const data = findRevertData(e);
+        const d = data ? decodeRevert(data) : null;
+        if (d?.name === "Bad" && AGENT_BAD[String(d.args[0])])
+            return new PickhooksError(AGENT_BAD[String(d.args[0])], { code: "Bad", args: d.args, cause: e });
+        const kind = blockedKind(e);
+        if (kind !== null && token) {
+            const p = await program(token).catch(() => null);
+            return new PickhooksError(ruleText(kind, p?.r ?? null).text, { code: "Blocked", args: [kind], cause: e });
+        }
+        return toPickhooksError(e, fallback);
+    }
+    // ---------------------------------------------------------------- reads
+    /** Coins newest first. */
+    async function coins(o = {}) {
+        const n = await count();
+        const end = Math.max(0, n - (o.offset ?? 0));
+        const from = Math.max(0, end - (o.limit ?? 50));
+        if (end <= from)
+            return [];
+        const tokens = (await pub.multicall({
+            contracts: Array.from({ length: end - from }, (_, i) => ({ address: F, abi: FA, functionName: "coins", args: [BigInt(end - 1 - i)] })),
+            allowFailure: false,
+        }));
+        return summaries(tokens);
+    }
+    /** One coin, or null when it is not an agent coin. */
+    async function coin(token) {
+        if (!(await isCoin(token)))
+            return null;
+        return (await summaries([token]))[0] ?? null;
+    }
+    async function summaries(tokens) {
+        if (!tokens.length)
+            return [];
+        const { hook: h, desk: d } = await contracts();
+        const per = 9;
+        const [res, meta, head] = await Promise.all([
+            pub.multicall({
+                contracts: tokens.flatMap((t) => [
+                    { address: h, abi: HA, functionName: "coinOf", args: [t] },
+                    { address: h, abi: HA, functionName: "programOf", args: [t] },
+                    { address: h, abi: HA, functionName: "stateOf", args: [t] },
+                    { address: h, abi: HA, functionName: "poolKeyOf", args: [t] },
+                    { address: h, abi: HA, functionName: "outside", args: [t] },
+                    { address: d, abi: DA, functionName: "agentOf", args: [t] },
+                    { address: d, abi: DA, functionName: "pendingOf", args: [t] },
+                    { address: d, abi: DA, functionName: "fireOf", args: [t] },
+                    { address: d, abi: DA, functionName: "dueAt", args: [t] },
+                ]),
+                allowFailure: true,
+            }),
+            pub.multicall({ contracts: tokens.flatMap((t) => ["name", "symbol", "metadata"].map((functionName) => ({ address: t, abi: PLAIN, functionName }))), allowFailure: true }),
+            pub.getBlock({ blockTag: "latest" }),
+        ]);
+        const ks = tokens.map((_, i) => (res[i * per + 3].status === "success" ? toKey(res[i * per + 3].result) : null));
+        const slots = await pub.multicall({
+            contracts: ks.map((k) => ({ address: a.clPoolManager, abi: clPoolManagerAbi, functionName: "getSlot0", args: [k ? poolIdOf(k) : `0x${"0".repeat(64)}`] })),
+            allowFailure: true,
+        });
+        const now = Number(head.timestamp);
+        const out = [];
+        tokens.forEach((token, i) => {
+            const g = (j) => res[i * per + j];
+            const k = ks[i];
+            if (!k || [0, 1, 2, 4, 5, 6, 7, 8].some((j) => g(j).status !== "success"))
+                return;
+            keys.set(token.toLowerCase(), k);
+            const c = g(0).result;
+            const p = decodeProgram(g(1).result);
+            const [pots, totals, stats, jackpotLast, jackpotTime] = g(2).result;
+            const [pilot, epoch, lastChange, version, env] = g(5).result;
+            const pend = g(6).result;
+            const fire = g(7).result;
+            const m = (j) => meta[i * 3 + j];
+            const sl = slots[i];
+            const priceBnb = sl.status === "success" ? infiPriceBnb(sl.result[0]) : 0;
+            const envelope = {
+                maxFeeBps: Number(env.maxFeeBps),
+                maxCreatorBps: Number(env.maxCreatorBps),
+                allowedMask: BigInt(env.allowedMask),
+                notice: Number(env.notice),
+                minGap: Number(env.minGap),
+                vetoBps: Number(env.vetoBps),
+                fireBps: Number(env.fireBps),
+            };
+            out.push({
+                token,
+                name: m(0).status === "success" ? String(m(0).result) : "",
+                symbol: m(1).status === "success" ? String(m(1).result) : "",
+                metadata: m(2).status === "success" ? String(m(2).result) : "",
+                creator: c[0],
+                floor: c[1],
+                start: Number(c[2]),
+                platformBps: Number(c[3]),
+                version: Number(version),
+                pilot: isAddressEqual(pilot, ZERO_ADDRESS) ? null : pilot,
+                fired: isAddressEqual(pilot, ZERO_ADDRESS),
+                epoch: Number(epoch),
+                lastChange: Number(lastChange),
+                env: envelope,
+                allowed: AGENT_RULES.filter((r) => envelope.allowedMask & (1n << BigInt(r.kind))).map((r) => r.id),
+                program: p,
+                lines: describeProgram(p),
+                rules: agentKindsOf(p.r.mask).map((kind) => {
+                    const def = AGENT_RULE_BY_KIND.get(kind);
+                    return { kind, id: def.id, name: def.name, text: def.describe(p.r) };
+                }),
+                pending: pend[0] > 0n
+                    ? { id: pend[0], activeAt: Number(pend[1]), dueAt: Number(g(8).result), note: pend[2], vetoLocked: pend[3], vetoNeeded: pend[4], program: pend[5], lines: describeProgram(pend[5]) }
+                    : null,
+                fire: { locked: fire[0], needed: fire[1] },
+                pots: Object.fromEntries(BUCKETS.map((b) => [b, pots[b]])),
+                totals,
+                stats: {
+                    buyers: Number(stats.buyers),
+                    buys: Number(stats.buys),
+                    sells: Number(stats.sells),
+                    buysSinceSell: Number(stats.buysSinceSell),
+                    lastBuyTime: Number(stats.lastBuyTime),
+                    lastBuyer: stats.lastBuyer,
+                    qualifyingBuys: Number(stats.qualifyingBuys),
+                    volume: stats.volume,
+                    net: stats.net,
+                    peak: stats.peak,
+                },
+                jackpotLast,
+                jackpotTime: Number(jackpotTime),
+                outside: g(4).result,
+                id: poolIdOf(k),
+                key: k,
+                priceBnb,
+                mcapBnb: priceBnb * 1e9,
+                chainNow: now,
+            });
+        });
+        return out;
+    }
+    /** The live program of a coin. */
+    const program = async (token) => decodeProgram(await call(await hook(), HA, "programOf", [token]));
+    /** The coin's limits and its pilot. */
+    async function envelopeOf(token) {
+        const [pilot, , lastChange, version, env] = await call(await desk(), DA, "agentOf", [token]);
+        return {
+            pilot: isAddressEqual(pilot, ZERO_ADDRESS) ? null : pilot,
+            version: Number(version),
+            lastChange: Number(lastChange),
+            env: { maxFeeBps: Number(env.maxFeeBps), maxCreatorBps: Number(env.maxCreatorBps), allowedMask: BigInt(env.allowedMask), notice: Number(env.notice), minGap: Number(env.minGap), vetoBps: Number(env.vetoBps), fireBps: Number(env.fireBps) },
+        };
+    }
+    /** A wallet's lock at the desk for a coin (coins locked against a change or against the agent). */
+    async function locks(token, who) {
+        const r = await call(await desk(), DA, "locks", [token, who]);
+        return { amount: r[0], vetoId: r[1], fireEpoch: Number(r[2]), vetoing: r[3], firing: r[4] };
+    }
+    /** BNB the hook owes a wallet (jackpot wins, rewards, a creator's share), over every agent coin. */
+    const owed = async (who) => call(await hook(), HA, "owed", [who]);
+    /** A wallet and a coin: balance, what is locked at the desk, BNB owed. */
+    async function wallet(token, who) {
+        const [balance, l, o] = await Promise.all([call(token, erc20Abi, "balanceOf", [who]), locks(token, who), owed(who)]);
+        return { balance, owed: o, ...l };
+    }
+    /** The agent's journal from pickhooks.com (the pickhooks pilot writes one; other pilots' coins have none there). */
+    async function journal(token, limit = 20) {
+        const res = await fetch(`${ctx.site}/api/agents/${token}`, { headers: { accept: "application/json" } });
+        const j = (await res.json().catch(() => null));
+        if (!res.ok || !j)
+            throw new PickhooksError(j?.error ?? `The site answered ${res.status}.`, { code: res.status === 429 ? "rate" : "site" });
+        return (j.journal ?? []).slice(0, limit);
+    }
+    /** The agent's profile from the coin's metadata JSON (the brief its creator wrote), or just the symbol. */
+    async function profileOf(c) {
+        const base = { symbol: c.symbol, name: c.name };
+        if (!/^https:\/\//.test(c.metadata))
+            return base;
+        try {
+            const j = (await (await fetch(c.metadata, { signal: AbortSignal.timeout(5000) })).json());
+            const ag = j.agent ?? {};
+            const s = (x, n) => (typeof x === "string" ? x.slice(0, n) : "");
+            return {
+                ...base,
+                description: s(j.description, 500),
+                agentName: s(ag.name, 40),
+                personality: s(ag.personality, 40),
+                objectives: Array.isArray(ag.objectives) ? ag.objectives.slice(0, 3).map((o) => s(o, 40)) : [],
+                mission: s(ag.mission, 200),
+                ideas: Array.isArray(ag.ideas) ? ag.ideas.slice(0, 3).map((o) => s(o, 280)) : [],
+            };
+        }
+        catch {
+            return base;
+        }
+    }
+    /**
+     * A look at the coin: the JSON the pickhooks pilot hands its model each round (market, live program, pending change,
+     * holders against it, buckets, what was done so far, its last journal entries). `tradesSinceLastLook` is yours to pass.
+     */
+    async function look(token, o = {}) {
+        const c = await coin(token);
+        if (!c)
+            throw new PickhooksError("This is not an agent coin.", { code: "input" });
+        const entries = o.entries ?? (await journal(token, 5).catch(() => [])).map((e) => ({ at: e.at, title: e.title, body: e.body, action: e.action, expect: e.expect, result: e.result }));
+        return {
+            now_utc: iso(c.chainNow),
+            coin: { name: c.name, symbol: c.symbol, token, age_hours: +((c.chainNow - c.start) / 3600).toFixed(2), creator: c.creator, floor: c.floor },
+            market: {
+                price_bnb_per_million_coins: +(c.priceBnb * 1e6).toPrecision(4),
+                market_cap_bnb: +c.mcapBnb.toPrecision(4),
+                buys: c.stats.buys,
+                sells: c.stats.sells,
+                trades_since_last_look: o.tradesSinceLastLook ?? null,
+                buyers: c.stats.buyers,
+                volume_coins: f(c.stats.volume),
+                coins_outside_pool: f(c.outside),
+            },
+            live_program: { version: c.version, ...toPlan(c.program) },
+            pending_change: c.pending ? { id: Number(c.pending.id), lands_at_utc: iso(c.pending.activeAt), veto_locked: f(c.pending.vetoLocked), veto_needed: f(c.pending.vetoNeeded), plan: toPlan(c.pending.program) } : null,
+            holders_against_you: { locked: f(c.fire.locked), fires_you_at: f(c.fire.needed) },
+            buckets_bnb: Object.fromEntries(BUCKETS.map((b) => [b, f(c.pots[b])])),
+            done_so_far: { burned_bnb: f(c.totals.burnedBnb), burned_coins: f(c.totals.burnedCoins), liquidity_bnb: f(c.totals.lpBnb), floor_bnb: f(c.totals.floorBnb) },
+            last_change_utc: iso(c.lastChange),
+            your_last_entries: entries,
+        };
+    }
+    /**
+     * Everything a model needs to be this coin's agent for one look: the pickhooks pilot's system prompt (the coin's
+     * character and brief, how fees route, the rules it may use, its limits), the user message with the look, and the
+     * strict JSON schema of the answer. Feed `system` and `user` to any model with `schema` as its output format, then
+     * hand the answer to act().
+     */
+    async function brief(token, o = {}) {
+        const c = await coin(token);
+        if (!c)
+            throw new PickhooksError("This is not an agent coin.", { code: "input" });
+        const [profile, lk] = await Promise.all([profileOf(c), look(token, o)]);
+        return { system: systemPrompt(profile, c.env, c.platformBps / 100), user: userPrompt(lk), schema: ANSWER_SCHEMA, look: lk, profile };
+    }
+    // ---------------------------------------------------------------- checks
+    /** The problems AgentsLimits.check would name, offline (the main ones; the chain has the last word). Empty = fine. */
+    function problemsOf(p, env = starterEnvelope()) {
+        const out = [];
+        const has = (id) => (BigInt(p.r.mask) & (1n << BigInt(id))) !== 0n;
+        if (p.buyFeeBps < AGENT_LIMITS.baseFeeBps || p.buyFeeBps > env.maxFeeBps)
+            out.push(AGENT_BAD.buyFee);
+        if (p.sellFeeBps < AGENT_LIMITS.baseFeeBps || p.sellFeeBps > env.maxFeeBps)
+            out.push(AGENT_BAD.sellFee);
+        if (p.creatorBps > env.maxCreatorBps)
+            out.push(AGENT_BAD.creator);
+        if (p.burnBps + p.lpBps + p.floorBps + p.rewardsBps + p.jackpotBps + p.creatorBps > 10_000)
+            out.push(AGENT_BAD.routing);
+        if ((BigInt(p.r.mask) & ~env.allowedMask) !== 0n)
+            out.push(AGENT_BAD["rule not allowed"]);
+        if (agentKindsOf(p.r.mask).length > AGENT_LIMITS.maxRules)
+            out.push(AGENT_BAD["too many rules"]);
+        if ((BigInt(p.r.mask) & ~ALLOWED_MASK) !== 0n)
+            out.push("A rule in this program is not one an agent may use.");
+        if (p.rewardsBps > 0 && !has(31))
+            out.push(AGENT_BAD["rewards without rule"]);
+        if (p.jackpotBps > 0 && !has(36))
+            out.push(AGENT_BAD["jackpot without rule"]);
+        if (has(15) && !p.r.sellsOpen)
+            out.push(AGENT_BAD["market hours must keep sells open"]);
+        if (has(20) && has(16))
+            out.push(AGENT_BAD["tick tock with sell window"]);
+        if (has(16) && (p.r.sellWindow < 60 || p.r.sellWindow >= p.r.sellPeriod))
+            out.push(AGENT_BAD.sellWindow);
+        return out;
+    }
+    /** The problems AgentsLimits.checkEnvelope would name, offline. Empty = fine. */
+    function envelopeProblems(e) {
+        const out = [];
+        if (e.maxFeeBps < AGENT_LIMITS.baseFeeBps || e.maxFeeBps > AGENT_LIMITS.maxFeeBps)
+            out.push(AGENT_BAD.maxFee);
+        if (e.maxCreatorBps > AGENT_LIMITS.maxCreatorBps)
+            out.push(AGENT_BAD.maxCreator);
+        if ((e.allowedMask & ~ALLOWED_MASK) !== 0n)
+            out.push(AGENT_BAD.allowed);
+        if (e.notice < AGENT_LIMITS.notice.min || e.notice > AGENT_LIMITS.notice.max)
+            out.push(AGENT_BAD.notice);
+        if (e.minGap < AGENT_LIMITS.minGap.min || e.minGap > AGENT_LIMITS.minGap.max)
+            out.push(AGENT_BAD.minGap);
+        if (e.vetoBps < AGENT_LIMITS.vetoBps.min || e.vetoBps > AGENT_LIMITS.vetoBps.max)
+            out.push(AGENT_BAD.veto);
+        if (e.fireBps < AGENT_LIMITS.fireBps.min || e.fireBps > AGENT_LIMITS.fireBps.max)
+            out.push(AGENT_BAD.fire);
+        return out;
+    }
+    /** Asks the desk (an eth_call as the coin's pilot) whether it would take this program: the chain's own check, in words. */
+    async function checkProgram(token, p) {
+        const { pilot } = await envelopeOf(token);
+        if (!pilot)
+            return { ok: false, text: AGENT_BAD.NoPilot ?? "This coin has no pilot any more: the holders fired it." };
+        try {
+            await pub.simulateContract({ address: await desk(), abi: DA, functionName: "propose", args: [token, p, `0x${"0".repeat(64)}`], account: pilot });
+            return { ok: true };
+        }
+        catch (e) {
+            return { ok: false, text: (await agentError(e, "The desk refused this program.")).message };
+        }
+    }
+    // ---------------------------------------------------------------- trades (the pool: PancakeSwap Infinity with the agents hook)
+    async function quote(q) {
+        try {
+            const r = await infiQuote(ctx, { key: await key(q.token), buy: q.side === "buy", amount: q.amount, from: q.from });
+            return { amountOut: r.amountOut };
+        }
+        catch (e) {
+            throw await agentError(e, "The quoter refused this trade.", q.token);
+        }
+    }
+    /** Would this trade go through for this wallet: the quote runs the hook's rules as the trader. */
+    async function check(c) {
+        try {
+            await infiQuote(ctx, { key: await key(c.token), buy: c.side === "buy", amount: c.amount, from: c.wallet });
+            return { ok: true };
+        }
+        catch (e) {
+            const kind = blockedKind(e);
+            if (kind === null)
+                return { ok: false, kind: 0, name: "", text: explain(e, "The pool refused this trade.").text };
+            const p = await program(c.token).catch(() => null);
+            return { ok: false, kind, ...ruleText(kind, p?.r ?? null) };
+        }
+    }
+    const buildBuy = (k, bnbIn, minOut, deadline) => buildInfiSwap(a, { key: k, buy: true, legs: [bnbIn], minOut, deadline, gasPct: 150 });
+    const buildSell = (k, amount, minOut, deadline) => buildInfiSwap(a, { key: k, buy: false, legs: [amount], minOut, deadline, gasPct: 150 });
+    /** Quotes as the trader (a refusing rule stops it before anything is signed), then buys through the UniversalRouter. */
+    async function buy(b, s = {}) {
+        const { address } = await signer(ctx, s.wallet);
+        const q = await quote({ token: b.token, side: "buy", amount: b.bnbIn, from: address });
+        const minOut = b.minOut ?? minusBps(q.amountOut, b.slippageBps ?? 100);
+        try {
+            return { ...(await sendTx(ctx, buildBuy(await key(b.token), b.bnbIn, minOut, b.deadline ?? (await chainDeadline(ctx))), s)), quoted: q.amountOut, minOut };
+        }
+        catch (e) {
+            throw await agentError(e, "The buy would fail.", b.token);
+        }
+    }
+    /** Approves Permit2 if needed, quotes as the trader, sells through the UniversalRouter. */
+    async function sell(x, s = {}) {
+        const { address } = await signer(ctx, s.wallet);
+        const q = await quote({ token: x.token, side: "sell", amount: x.amount, from: address });
+        await sendAll(ctx, await permit2Approvals(ctx, address, x.token, x.amount), s);
+        const minOut = x.minOut ?? minusBps(q.amountOut, x.slippageBps ?? 100);
+        try {
+            return { ...(await sendTx(ctx, buildSell(await key(x.token), x.amount, minOut, x.deadline ?? (await chainDeadline(ctx))), s)), quoted: q.amountOut, minOut };
+        }
+        catch (e) {
+            throw await agentError(e, "The sell would fail.", x.token);
+        }
+    }
+    // ---------------------------------------------------------------- writes: the desk (pilot, holders) and the hook (anyone)
+    const deskTx = async (fn, args, label, value = 0n) => ({
+        to: await desk(),
+        value,
+        data: encodeFunctionData({ abi: DA, functionName: fn, args }),
+        label,
+    });
+    const hookTx = async (fn, args, label, value = 0n) => ({
+        to: await hook(),
+        value,
+        data: encodeFunctionData({ abi: HA, functionName: fn, args }),
+        label,
+    });
+    const bucketIndex = (b) => {
+        const i = typeof b === "number" ? b : BUCKETS.indexOf(b);
+        if (i < 0 || i >= BUCKETS.length)
+            throw new PickhooksError(`Bucket: one of ${BUCKETS.join(", ")}.`, { code: "input" });
+        return i;
+    };
+    /** A program from a Program or a plan in plain units. */
+    const programOf = (p) => ("r" in p && p.r ? p : toProgram(p).program);
+    /** The note a proposal carries: a Hex as given, a text hashed (keccak256 of "title\nbody" when title and body are given), or zero. */
+    const noteOf = (note) => {
+        if (!note)
+            return `0x${"0".repeat(64)}`;
+        if (typeof note === "string")
+            return /^0x[0-9a-fA-F]{64}$/.test(note) ? note : noteHash({ title: note, body: "" });
+        return noteHash(note);
+    };
+    const build = {
+        /** the pilot proposes a whole new program; it lands after the notice (anyone may call activate then) */
+        propose: async (token, p, note) => deskTx("propose", [token, programOf(p), noteOf(note)], "Proposing the change"),
+        cancel: (token) => deskTx("cancel", [token], "Cancelling the change"),
+        /** the pilot moves treasury BNB (or a pot whose rule is off) into burn, lp, floor, rewards or jackpot */
+        move: (token, from, to, wei) => deskTx("move", [token, bucketIndex(from), bucketIndex(to), wei], "Moving BNB between buckets"),
+        handOver: (token, to) => deskTx("handOver", [token, to], "Handing the coin to another pilot"),
+        /** anyone lands a change that is due */
+        activate: (token) => deskTx("activate", [token], "Landing the change"),
+        /** a holder locks coins against the pending change (0: with coins locked already) */
+        veto: (token, amount) => deskTx("veto", [token, amount], "Vetoing the change"),
+        /** a holder locks coins against the agent (0: with coins locked already) */
+        fire: (token, amount) => deskTx("fire", [token, amount], "Firing the agent"),
+        withdraw: (token) => deskTx("withdraw", [token], "Taking the locked coins back"),
+        /** anyone adds BNB to a coin's bucket */
+        give: (token, bucket, wei) => hookTx("give", [token, bucketIndex(bucket)], "Giving BNB to the coin", wei),
+        /** jackpot wins, rewards and a creator's share, over every agent coin */
+        claim: () => hookTx("claim", [], "The claim"),
+        /** the runs anyone may trigger: the burn bucket buys and burns, the lp bucket becomes liquidity, the floor bucket feeds the floor */
+        burn: (token) => hookTx("burn", [token], "The burn run"),
+        addLiquidity: (token) => hookTx("addLiquidity", [token], "The liquidity run"),
+        feedFloor: (token) => hookTx("feedFloor", [token], "Feeding the floor"),
+        settleJackpot: (token) => hookTx("settleJackpot", [token], "Settling the jackpot"),
+        buy: (k, bnbIn, minOut, deadline) => buildBuy(k, bnbIn, minOut, deadline),
+        sell: (k, amount, minOut, deadline) => buildSell(k, amount, minOut, deadline),
+        launch: (l) => {
+            const program = l.program ?? (l.plan ? toProgram(l.plan).program : starterProgram());
+            const env = { ...starterEnvelope(), ...l.envelope };
+            const problems = [...envelopeProblems(env), ...problemsOf(program, env)];
+            if (problems.length)
+                throw new PickhooksError(problems.join(" "), { code: "input" });
+            const pilot = l.pilot ?? a.agentsPilot;
+            if (isAddressEqual(pilot, ZERO_ADDRESS))
+                throw new PickhooksError("Give a pilot: the agent's wallet.", { code: "input" });
+            return {
+                to: need(),
+                value: l.devBuy ?? 0n,
+                data: encodeFunctionData({ abi: FA, functionName: "launch", args: [l.name, l.symbol, l.metadata, program, env, pilot, l.salt ?? randomSalt()] }),
+                gasPct: 120,
+                label: "The launch",
+            };
+        },
+    };
+    const sendDesk = async (tx, s, token, fallback = "The desk refused this.") => {
+        try {
+            return await sendTx(ctx, await tx, s);
+        }
+        catch (e) {
+            throw await agentError(e, fallback, token);
+        }
+    };
+    /** The desk pulls the coins for veto and fire: an approval first when the allowance is short. */
+    const deskApproval = async (owner, token, amount) => approvalFor(ctx, owner, token, amount, await desk(), "Allowing the desk");
+    /**
+     * The transaction a model's answer asks for: propose (the plan as a program, the entry's hash as the note), move, or
+     * nothing for "none". `proposal` carries the proposed program as sentences, `notes` the rules toProgram dropped.
+     */
+    async function act(token, answer) {
+        const entry = { title: String(answer.title).slice(0, 80), body: String(answer.body).slice(0, 1200) };
+        const note = noteHash(entry);
+        if (answer.action === "propose") {
+            const { program: p, notes } = toProgram(readPlan(answer.plan));
+            return { tx: await build.propose(token, p, note), proposal: describeProgram(p), notes, note };
+        }
+        if (answer.action === "move" && answer.move?.bnb > 0) {
+            const wei = BigInt(Math.round(answer.move.bnb * 1e9)) * 10n ** 9n;
+            return { tx: await build.move(token, answer.move.from, answer.move.to, wei), notes: [], note };
+        }
+        return { tx: null, notes: [], note };
+    }
+    /** The launch: checks the program and the limits offline, then the factory's own check in an eth_call, then sends. */
+    async function launch(l, s = {}) {
+        const tx = build.launch(l);
+        const { address } = await signer(ctx, s.wallet);
+        try {
+            await pub.call({ account: address, to: tx.to, data: tx.data, value: tx.value });
+        }
+        catch (e) {
+            throw await agentError(e, "The factory refused this launch.");
+        }
+        const sent = await sendTx(ctx, tx, s);
+        const ev = parseEventLogs({ abi: agentsFactoryAbi, logs: sent.receipt.logs.filter((x) => isAddressEqual(x.address, F)), eventName: "Launched" })[0];
+        if (!ev)
+            throw new PickhooksError("Launched, but the coin was not found in the receipt.", { code: "receipt", hash: sent.hash });
+        return { ...sent, token: ev.args.token, id: ev.args.poolId, floor: ev.args.floor };
+    }
+    /**
+     * Stores the image and the metadata with the agent's profile on pickhooks.com (the site's /api/agents/prepare, rate
+     * limited) and returns the metadata link and a fresh salt. A launchpad can host its own JSON and pass that link instead.
+     */
+    async function prepareMetadata(m) {
+        const B = globalThis.Buffer;
+        const base64 = B ? B.from(m.image.bytes).toString("base64") : btoa(Array.from(m.image.bytes, (x) => String.fromCharCode(x)).join(""));
+        const res = await fetch(`${ctx.site}/api/agents/prepare`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ ...m, image: { mime: m.image.mime, base64 } }),
+        });
+        const j = (await res.json().catch(() => ({})));
+        if (!res.ok || !j.metadata)
+            throw new PickhooksError(j.error ?? `The site answered ${res.status}.`, { code: "site" });
+        return { metadata: j.metadata, image: j.image ?? "", salt: j.salt ?? randomSalt() };
+    }
+    /** The catalog as plain data: the rules an agent may use, the limits, the buckets, the profile vocabulary, the ABI tuples. */
+    const catalog = () => ({
+        rules: AGENT_RULES.map((r) => ({ kind: r.kind, id: r.id, name: r.name, line: r.line, fields: r.fields })),
+        limits: AGENT_LIMITS,
+        buckets: [...BUCKETS],
+        personalities: [...PERSONALITIES],
+        objectives: OBJECTIVES,
+        starter: { program: starterProgram(), envelope: starterEnvelope() },
+        abi: { program: PROGRAM_TUPLE, envelope: ENVELOPE_TUPLE },
+        answerSchema: ANSWER_SCHEMA,
+    });
+    return {
+        get on() {
+            return on();
+        },
+        factory: F,
+        hook,
+        desk,
+        key,
+        count,
+        isCoin,
+        coins,
+        coin,
+        program,
+        envelopeOf,
+        locks,
+        owed,
+        wallet,
+        journal,
+        look,
+        brief,
+        catalog,
+        describe: describeProgram,
+        toProgram,
+        toPlan,
+        problemsOf,
+        envelopeProblems,
+        checkProgram,
+        quote,
+        check,
+        sellApprovals: (owner, token, amount) => permit2Approvals(ctx, owner, token, amount),
+        build,
+        buy,
+        sell,
+        act,
+        /** the pilot sends what a model's answer asks for; { tx: null } for "none" */
+        pilot: async (token, answer, s = {}) => {
+            const r = await act(token, answer);
+            return { ...r, sent: r.tx ? await sendDesk(Promise.resolve(r.tx), s, token, "The desk refused the change.") : null };
+        },
+        propose: (token, p, note, s = {}) => sendDesk(build.propose(token, p, note), s, token, "The desk refused this program."),
+        cancel: (token, s = {}) => sendDesk(build.cancel(token), s, token),
+        move: (token, from, to, wei, s = {}) => sendDesk(build.move(token, from, to, wei), s, token),
+        handOver: (token, to, s = {}) => sendDesk(build.handOver(token, to), s, token),
+        activate: (token, s = {}) => sendDesk(build.activate(token), s, token, "The change is not due yet."),
+        veto: async (token, amount, s = {}) => {
+            const { address } = await signer(ctx, s.wallet);
+            const ap = amount > 0n ? await deskApproval(address, token, amount) : null;
+            if (ap)
+                await sendTx(ctx, ap, s);
+            return sendDesk(build.veto(token, amount), s, token, "The desk refused the veto.");
+        },
+        fire: async (token, amount, s = {}) => {
+            const { address } = await signer(ctx, s.wallet);
+            const ap = amount > 0n ? await deskApproval(address, token, amount) : null;
+            if (ap)
+                await sendTx(ctx, ap, s);
+            return sendDesk(build.fire(token, amount), s, token, "The desk refused this.");
+        },
+        withdraw: (token, s = {}) => sendDesk(build.withdraw(token), s, token),
+        give: (token, bucket, wei, s = {}) => sendDesk(build.give(token, bucket, wei), s, token),
+        claim: (s = {}) => sendDesk(build.claim(), s),
+        burn: (token, s = {}) => sendDesk(build.burn(token), s, token, "The burn run is not possible right now."),
+        addLiquidity: (token, s = {}) => sendDesk(build.addLiquidity(token), s, token, "The liquidity run is not possible right now."),
+        feedFloor: (token, s = {}) => sendDesk(build.feedFloor(token), s, token, "The floor run is not possible right now."),
+        settleJackpot: (token, s = {}) => sendDesk(build.settleJackpot(token), s, token),
+        launch,
+        prepareMetadata,
+    };
+}