@finchip.ai/foga 0.0.0-stage → 0.6.0-alpha.4

package/dist/kernel/tx.js

@@ -0,0 +1,385 @@
+import { keccak256 } from "ethers";
+import { RevertDecoder } from "./errors.js";
+export class OperationAmbiguous extends Error {
+    op;
+    constructor(op, message) {
+        super(message);
+        this.op = op;
+        this.name = "OperationAmbiguous";
+    }
+}
+export class OperationReverted extends Error {
+    key;
+    data;
+    constructor(key, message, data) {
+        super(message);
+        this.key = key;
+        this.data = data;
+        this.name = "OperationReverted";
+    }
+}
+/** Exit code of an injected crash (EX_TEMPFAIL): the run is incomplete and must be resumed. */
+export const CRASH_EXIT_CODE = 75;
+/**
+ * Sends transactions exactly once per key. The sequence for a new operation is: fix the nonce, build, sign,
+ * write the hash to the store, broadcast, wait, write the receipt. A resumed run finds the row and asks the chain
+ * before deciding: a receipt means done; a pending transaction is waited for; an unknown hash with the nonce
+ * still unconsumed is re-sent with that same nonce; an unknown hash with the nonce consumed is ambiguous and is
+ * never retried automatically.
+ *
+ * A transaction that is still pending when the receipt timeout passes (a public chain whose base fee rose after
+ * the quote) is replaced: the same payload and nonce, signed again with fees raised by a third, up to
+ * `maxReplacements` times. Every hash the operation ever had is in the journal, and inclusion of any of them
+ * completes the operation — the nonce makes them mutually exclusive.
+ */
+export class TxManager {
+    provider;
+    store;
+    signers;
+    options;
+    decoder = new RevertDecoder();
+    log;
+    constructor(provider, store, signers, options = {}) {
+        this.provider = provider;
+        this.store = store;
+        this.signers = signers;
+        this.options = options;
+        this.log = options.log ?? (() => { });
+    }
+    signer(name) {
+        const w = this.signers[name];
+        if (!w)
+            throw new Error(`unknown signer ${name}`);
+        return w;
+    }
+    /** One transaction at a time per signer: nonces are taken and used in order, whoever asks concurrently. */
+    queues = new Map();
+    async send(req) {
+        const wallet = this.signer(req.signer);
+        const previous = this.queues.get(wallet.address) ?? Promise.resolve();
+        const turn = previous.catch(() => undefined).then(() => this.sendInTurn(req, wallet));
+        this.queues.set(wallet.address, turn);
+        try {
+            return await turn;
+        }
+        finally {
+            if (this.queues.get(wallet.address) === turn)
+                this.queues.delete(wallet.address);
+        }
+    }
+    async sendInTurn(req, wallet) {
+        let rec = this.store.prepare(req.key, req.kind ?? "tx", req.signer, req.binding);
+        if (rec.status === "confirmed" && rec.txHash) {
+            const receipt = await this.provider.getTransactionReceipt(rec.txHash);
+            if (!receipt) {
+                throw new OperationAmbiguous(rec, `operation ${req.key} is confirmed in the store (tx ${rec.txHash}) but the chain has no receipt for it: the store and the chain have diverged (was the chain reset?). Start from a fresh store or point at the right world.`);
+            }
+            this.store.journal("replayed", { txHash: rec.txHash }, req.key);
+            return { key: req.key, txHash: rec.txHash, receipt, replayed: true, recovered: false };
+        }
+        if (rec.status === "failed") {
+            // The failure is the operation's answer. A new attempt is a decision the caller makes explicitly (and re-checks
+            // its budget for); nothing is sent anew because a key was asked for again.
+            if (!(req.retryFailed ?? this.options.retryFailed)) {
+                this.store.journal("replayed-failure", { error: rec.error }, req.key);
+                throw new OperationReverted(req.key, `operation ${req.key} failed before (${rec.error}); the same key answers with that failure. Retry explicitly to send it again.`, null);
+            }
+            this.store.markRetry(req.key);
+            this.store.journal("retry", { previousError: rec.error, attempts: rec.attempts }, req.key);
+            rec = this.store.get(req.key);
+        }
+        let nonce;
+        let pendingBefore = null;
+        if (rec.status === "sent" && rec.txHash && rec.nonce !== null) {
+            const recovered = await this.recover(rec, wallet.address);
+            if (recovered.confirmed)
+                return recovered.confirmed;
+            nonce = rec.nonce; // the nonce is still the operation's: either free (re-send) or held by its pending transaction (replace)
+            pendingBefore = recovered.pending;
+        }
+        else {
+            nonce = await this.provider.getTransactionCount(wallet.address, "pending");
+        }
+        const populated = await this.populate(req, wallet, nonce);
+        if (pendingBefore) {
+            // the recorded transaction is still in the pool: raise its fees and take its place rather than wait again
+            const next = await this.replace(req, wallet, populated, pendingBefore);
+            // no replacement possible (limit or fee cap): the pending transaction is waited for as it is
+            const receipt = next ? await this.awaitInclusion(req, wallet, next.populated, next.hash) : await this.awaitOnly(req, pendingBefore.hash);
+            await this.ensureVisible(receipt.blockNumber);
+            return this.finish(req.key, receipt, true);
+        }
+        const signed = await wallet.signTransaction(populated);
+        const txHash = keccak256(signed);
+        // the value the operation moves: what the binding says the cell moves (an execute carries it inside), else the transaction's own
+        this.store.markSent(req.key, txHash, nonce, req.binding?.valueWei ?? BigInt(populated.value ?? 0));
+        this.store.journal("sent", { txHash, nonce, to: populated.to ?? null, value: (populated.value ?? 0n).toString(), kind: req.kind ?? "tx" }, req.key);
+        if (this.options.crashBeforeBroadcast === req.key)
+            this.crash(req.key, "before-broadcast");
+        await this.provider.broadcastTransaction(signed);
+        this.log(`${req.key}: sent ${txHash} (nonce ${nonce}, ${req.signer})`);
+        if (this.options.crashAfterBroadcast === req.key)
+            this.crash(req.key, "after-broadcast");
+        const receipt = await this.awaitInclusion(req, wallet, populated, txHash);
+        await this.ensureVisible(receipt.blockNumber);
+        return this.finish(req.key, receipt, false);
+    }
+    /** With `awaitVisibility`: wait (up to 60 s) until two consecutive block-number reads are at or past `block`. */
+    async ensureVisible(block) {
+        if (!this.options.awaitVisibility)
+            return;
+        const deadline = Date.now() + 60_000;
+        let agreeing = 0;
+        let lagged = false;
+        while (agreeing < 2 && Date.now() < deadline) {
+            const n = await this.provider.getBlockNumber();
+            if (n >= block)
+                agreeing++;
+            else {
+                agreeing = 0;
+                lagged = true;
+            }
+            if (agreeing < 2)
+                await new Promise((r) => setTimeout(r, 750));
+        }
+        if (lagged)
+            this.store.journal("visibility-waited", { block, caughtUp: agreeing >= 2 });
+    }
+    /** Build, estimate and populate the request for a nonce; a failing estimate marks the operation failed. */
+    async populate(req, wallet, nonce) {
+        const base = await req.build({ nonce, from: wallet.address });
+        try {
+            // The estimate is taken on the pending state; the inclusion state differs by at least the block timestamp
+            // (a heartbeat-style SSTORE that was a no-op during the estimate costs 2900 more when the second ticks),
+            // so a margin is added to every estimate rather than trusting it to the unit.
+            let gasLimit = base.gasLimit;
+            if (gasLimit === undefined || gasLimit === null) {
+                const estimate = await this.provider.estimateGas({ ...base, from: wallet.address, nonce });
+                gasLimit = estimate + estimate / 4n + 20000n;
+            }
+            const populated = await wallet.populateTransaction({ ...base, from: wallet.address, nonce, gasLimit });
+            const cap = req.maxFeePerGasCap ?? this.options.maxFeePerGasCap;
+            if (cap !== undefined && populated.maxFeePerGas !== null && populated.maxFeePerGas !== undefined && BigInt(populated.maxFeePerGas) > cap) {
+                populated.maxFeePerGas = cap;
+                if (populated.maxPriorityFeePerGas !== null && populated.maxPriorityFeePerGas !== undefined && BigInt(populated.maxPriorityFeePerGas) > cap)
+                    populated.maxPriorityFeePerGas = cap;
+                this.store.journal("fee-capped", { maxFeePerGas: cap.toString() }, req.key);
+            }
+            return populated;
+        }
+        catch (e) {
+            const data = RevertDecoder.revertData(e);
+            const explained = this.decoder.explain(e);
+            this.store.markFailed(req.key, explained);
+            this.store.journal("estimate-failed", { error: explained }, req.key);
+            throw new OperationReverted(req.key, `operation ${req.key} would revert: ${explained}`, data);
+        }
+    }
+    /**
+     * Every hash this operation's current attempt was broadcast under, oldest first (the store row holds only the
+     * latest). An explicit retry starts a new attempt: the hashes before it belong to the failure that was retried and
+     * must not be waited for again (their receipt is the old revert).
+     */
+    hashesOf(key, latest) {
+        let out = [];
+        for (const j of this.store.journalEntries()) {
+            if (j.opKey !== key)
+                continue;
+            if (j.event === "retry") {
+                out = [];
+                continue;
+            }
+            if (!j.detail)
+                continue;
+            const h = j.event === "sent" || j.event === "replaced" ? j.detail.txHash : undefined;
+            if (h && !out.includes(h))
+                out.push(h);
+        }
+        if (!out.includes(latest))
+            out.push(latest);
+        return out;
+    }
+    /**
+     * Wait for the broadcast transaction's receipt. When the timeout passes and the transaction is still pending, it is
+     * replaced with higher fees (same nonce) until the operation's cumulative count reaches `maxReplacements` (the
+     * count is in the store, so a resumed run continues it rather than starting over) or the fee cap would be passed;
+     * when it has vanished from the pool and the nonce is free, it is broadcast again as it was; when any earlier hash
+     * of the operation was mined instead, that receipt completes it. After the last attempt the row stays `sent` and
+     * the next run resolves it from the chain (docs/kernel.md). A timeout on a local chain usually means the node is
+     * starved (another heavy process on the machine) rather than a lost transaction.
+     */
+    async awaitInclusion(req, wallet, populated, txHash) {
+        const timeoutMs = this.options.receiptTimeoutMs ?? 120_000;
+        const max = this.options.maxReplacements ?? 3;
+        let current = populated;
+        let hash = txHash;
+        for (;;) {
+            const receipt = await this.waitAny(req.key, hash, timeoutMs);
+            if (receipt)
+                return receipt;
+            const made = this.store.get(req.key)?.replacements ?? 0;
+            this.store.journal("receipt-timeout", { txHash: hash, timeoutMs, replacements: made }, req.key);
+            const pending = await this.provider.getTransaction(hash);
+            if (pending) {
+                if (made >= max) {
+                    throw new Error(`operation ${req.key}: no receipt for ${hash} within ${timeoutMs / 1000} s after ${made} fee replacement${made === 1 ? "" : "s"} (still pending; the limit is ${max}). The row stays 'sent' and is recovered on the next run (the receipt is read if a transaction of this operation was mined, otherwise it is replaced or sent again). If the node is local, check that nothing else is saturating the machine (a proving-key build, for instance) and run again.`);
+                }
+                const next = await this.replace(req, wallet, current, pending);
+                if (!next) {
+                    throw new Error(`operation ${req.key}: ${hash} is still pending after ${timeoutMs / 1000} s and raising its fees would pass the fee cap; the row stays 'sent' and is recovered on the next run.`);
+                }
+                current = next.populated;
+                hash = next.hash;
+                continue;
+            }
+            // not pending, not mined: either the nonce moved on (ambiguous) or the pool dropped it (send again as it was)
+            const consumed = await this.provider.getTransactionCount(wallet.address, "latest");
+            if (consumed > Number(current.nonce)) {
+                const rec = this.store.get(req.key);
+                this.store.journal("ambiguous", { txHash: hash, nonce: current.nonce, accountNonce: consumed }, req.key);
+                throw new OperationAmbiguous(rec, `operation ${req.key}: tx ${hash} is unknown to the node but nonce ${current.nonce} of ${wallet.address} has been consumed by another transaction. The outcome cannot be decided automatically; inspect the chain and mark the operation by hand.`);
+            }
+            const signed = await wallet.signTransaction(current);
+            this.store.journal("resend", { txHash: hash, nonce: current.nonce }, req.key);
+            this.log(`${req.key}: ${hash} left the pool unmined and nonce ${current.nonce} is free; sending again`);
+            await this.provider.broadcastTransaction(signed);
+            hash = keccak256(signed);
+        }
+    }
+    /** Wait for the operation's hashes without replacing (a resumed operation whose replacement is capped or at its limit). */
+    async awaitOnly(req, hash) {
+        const timeoutMs = this.options.receiptTimeoutMs ?? 120_000;
+        const receipt = await this.waitAny(req.key, hash, timeoutMs);
+        if (!receipt)
+            throw new Error(`operation ${req.key}: ${hash} is still pending and cannot be replaced (replacement limit or fee cap); the row stays 'sent' and is recovered on the next run.`);
+        return receipt;
+    }
+    /**
+     * Replace a pending transaction of the operation: the same payload and nonce with fees a third above the pending
+     * ones (and above the current quote), recorded as the operation's new hash and counted in the store. Returns
+     * null, without sending, when the raised fee would pass the cap or the cumulative limit is reached.
+     */
+    async replace(req, wallet, populated, pending) {
+        const made = this.store.get(req.key)?.replacements ?? 0;
+        const max = this.options.maxReplacements ?? 3;
+        if (made >= max) {
+            this.store.journal("replace-limit", { replacements: made, max }, req.key);
+            return null;
+        }
+        const bump = (v, floor) => {
+            const a = BigInt(v ?? 0n);
+            const b = BigInt(floor ?? 0n);
+            const base = a > b ? a : b;
+            return base + base / 3n + 1n;
+        };
+        const next = { ...populated };
+        const cap = req.maxFeePerGasCap ?? this.options.maxFeePerGasCap;
+        if (pending.maxFeePerGas !== null && pending.maxFeePerGas !== undefined) {
+            next.maxFeePerGas = bump(pending.maxFeePerGas, populated.maxFeePerGas);
+            next.maxPriorityFeePerGas = bump(pending.maxPriorityFeePerGas, populated.maxPriorityFeePerGas);
+            if (next.maxPriorityFeePerGas > next.maxFeePerGas)
+                next.maxFeePerGas = next.maxPriorityFeePerGas;
+            if (cap !== undefined && next.maxFeePerGas > cap) {
+                this.store.journal("replace-capped", { wanted: next.maxFeePerGas.toString(), cap: cap.toString() }, req.key);
+                return null;
+            }
+        }
+        else {
+            next.gasPrice = bump(pending.gasPrice, populated.gasPrice);
+            delete next.maxFeePerGas;
+            delete next.maxPriorityFeePerGas;
+            if (cap !== undefined && next.gasPrice > cap) {
+                this.store.journal("replace-capped", { wanted: next.gasPrice.toString(), cap: cap.toString() }, req.key);
+                return null;
+            }
+        }
+        const signed = await wallet.signTransaction(next);
+        const hash = keccak256(signed);
+        this.store.markReplaced(req.key, hash, Number(next.nonce));
+        const attempt = made + 1;
+        this.store.journal("replaced", { txHash: hash, replaces: pending.hash, nonce: next.nonce, attempt, maxFeePerGas: next.maxFeePerGas?.toString() ?? null, maxPriorityFeePerGas: next.maxPriorityFeePerGas?.toString() ?? null, gasPrice: next.gasPrice?.toString() ?? null }, req.key);
+        this.log(`${req.key}: ${pending.hash} still pending after the timeout; replaced by ${hash} with fees raised by a third (replacement ${attempt} of ${max})`);
+        try {
+            await this.provider.broadcastTransaction(signed);
+        }
+        catch (e) {
+            // the original was mined between the check and the broadcast, or the pool refuses the replacement: the wait decides
+            this.store.journal("replace-rejected", { txHash: hash, error: String(e?.shortMessage ?? e?.message ?? e) }, req.key);
+            this.log(`${req.key}: the node refused the replacement (${e?.shortMessage ?? e?.message}); waiting for whichever transaction is included`);
+        }
+        return { populated: next, hash };
+    }
+    /** The receipt of any hash the operation ever had, or null when none is mined within the timeout. */
+    async waitAny(key, latest, timeoutMs) {
+        const hashes = this.hashesOf(key, latest);
+        const deadline = Date.now() + timeoutMs;
+        const poll = this.provider.pollingInterval ?? 4_000;
+        for (;;) {
+            for (const h of hashes) {
+                const r = await this.provider.getTransactionReceipt(h);
+                if (r)
+                    return r;
+            }
+            if (Date.now() >= deadline)
+                return null;
+            await new Promise((r) => setTimeout(r, Math.min(poll, Math.max(0, deadline - Date.now()))));
+        }
+    }
+    /**
+     * Decide what a `sent` row means by asking the chain about every hash the operation had: a receipt completes it;
+     * a pending transaction is returned for replacement; an unknown hash with the nonce still free means re-send; an
+     * unknown hash with the nonce consumed is ambiguous and is never retried automatically.
+     */
+    async recover(rec, from) {
+        for (const h of this.hashesOf(rec.key, rec.txHash)) {
+            const receipt = await this.provider.getTransactionReceipt(h);
+            if (receipt) {
+                this.store.journal("recovered-receipt", { txHash: h, block: receipt.blockNumber }, rec.key);
+                this.log(`${rec.key}: recovered receipt for ${h} from block ${receipt.blockNumber}; not re-sent`);
+                await this.ensureVisible(receipt.blockNumber);
+                return { confirmed: this.finish(rec.key, receipt, true), pending: null };
+            }
+        }
+        const pending = await this.provider.getTransaction(rec.txHash);
+        if (pending) {
+            this.store.journal("recovered-pending", { txHash: rec.txHash }, rec.key);
+            this.log(`${rec.key}: ${rec.txHash} is still pending; replacing it with higher fees`);
+            return { confirmed: null, pending };
+        }
+        const consumed = await this.provider.getTransactionCount(from, "latest");
+        if (consumed > rec.nonce) {
+            this.store.journal("ambiguous", { txHash: rec.txHash, nonce: rec.nonce, accountNonce: consumed }, rec.key);
+            throw new OperationAmbiguous(rec, `operation ${rec.key}: tx ${rec.txHash} is unknown to the node but nonce ${rec.nonce} of ${from} has been consumed by another transaction. The outcome cannot be decided automatically; inspect the chain and mark the operation by hand.`);
+        }
+        this.store.journal("resend", { txHash: rec.txHash, nonce: rec.nonce }, rec.key);
+        this.log(`${rec.key}: ${rec.txHash} never reached the chain and nonce ${rec.nonce} is free; sending again`);
+        return { confirmed: null, pending: null };
+    }
+    finish(key, receipt, recovered) {
+        const price = receipt.gasPrice ?? 0n;
+        const gasCost = receipt.gasUsed * price;
+        if (receipt.status === 0) {
+            this.store.markFailed(key, `reverted on chain in tx ${receipt.hash}`, gasCost);
+            this.store.journal("reverted", { txHash: receipt.hash, block: receipt.blockNumber, gasUsed: receipt.gasUsed.toString(), effectiveGasPrice: price.toString() }, key);
+            throw new OperationReverted(key, `operation ${key} reverted on chain (tx ${receipt.hash})`, null);
+        }
+        this.store.markConfirmed(key, receipt.hash, receipt.blockNumber, {
+            txHash: receipt.hash,
+            blockNumber: receipt.blockNumber,
+            blockHash: receipt.blockHash,
+            gasUsed: receipt.gasUsed.toString(),
+            effectiveGasPrice: price.toString(),
+            from: receipt.from,
+            to: receipt.to,
+            contractAddress: receipt.contractAddress,
+            logs: receipt.logs.length,
+        }, gasCost);
+        this.store.journal("confirmed", { txHash: receipt.hash, block: receipt.blockNumber, gasUsed: receipt.gasUsed.toString(), effectiveGasPrice: price.toString() }, key);
+        return { key, txHash: receipt.hash, receipt, replayed: false, recovered };
+    }
+    crash(key, where) {
+        this.store.journal("crash-injected", { where }, key);
+        this.log(`${key}: injected crash (${where}); exiting with code ${CRASH_EXIT_CODE}`);
+        process.exit(CRASH_EXIT_CODE);
+    }
+}

package/dist/mcp/server.js

@@ -0,0 +1,170 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { fogaCellSpecification } from "../core/asf.js";
+import { ACTION_RANK } from "../tools/index.js";
+import { repoRoot } from "../util/fs.js";
+const READ_ANNOTATIONS = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
+const ACT_ANNOTATIONS = { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true };
+const GENTLE_ACT_ANNOTATIONS = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true };
+const SIMULATE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true };
+const BUILD_ANNOTATIONS = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+/** Acts that commit nothing and move nothing: their act tool is not marked destructive. */
+const GENTLE_ACTS = new Set(["tender_precheck", "aid_heartbeat"]);
+const text = (value) => JSON.stringify(value, (_k, v) => (typeof v === "bigint" ? v.toString() : v), 2);
+function success(structured) {
+    return { content: [{ type: "text", text: text(structured) }], structuredContent: structured };
+}
+function refusal(r) {
+    const structured = { ok: false, gate: r.gate, reason: r.reason, decisionId: r.decisionId ?? null, jobId: r.jobId ?? null };
+    return { isError: true, content: [{ type: "text", text: `refused at ${r.gate}: ${r.reason}` }], structuredContent: structured };
+}
+/** The output schema of an act tool: the capability's output under `output`, or a refusal's fields. */
+function actOutputSchema(cap) {
+    return z.object({
+        ok: z.boolean(),
+        gate: z.string().optional(),
+        reason: z.string().optional(),
+        decisionId: z.number().nullable().optional(),
+        jobId: z.string().nullable().optional(),
+        operations: z.array(z.string()).optional(),
+        output: cap.output.optional(),
+    });
+}
+const buildOutputSchema = z.object({
+    ok: z.boolean(),
+    as: z.string().optional(),
+    calls: z.array(z.object({ to: z.string(), value: z.string(), data: z.string(), label: z.string() })).optional(),
+    gate: z.string().optional(),
+    reason: z.string().optional(),
+    decisionId: z.number().nullable().optional(),
+});
+const precheckOutputSchema = (cap) => z.object({
+    eligible: z.boolean(),
+    gate: z.string().optional(),
+    reason: z.string().optional(),
+    decisionId: z.number().nullable().optional(),
+    jobId: z.string().nullable().optional(),
+    result: cap.output.optional(),
+});
+/** A read output that is not an object is carried under `result` (structuredContent must be an object). */
+function readOutputSchema(cap) {
+    const json = z.toJSONSchema(cap.output, { target: "draft-2020-12", io: "output" });
+    if (json.type === "object")
+        return { schema: cap.output, wrap: false };
+    return { schema: z.object({ result: cap.output }), wrap: true };
+}
+export function buildMcpServer(o) {
+    const { node, catalog, caller } = o;
+    const cell = node.cell;
+    const server = new McpServer({ name: "foga", title: `FOGA node ${node.config.name}`, version: o.version }, {
+        instructions: [
+            `This is the Finch OG Agent node of cell ${node.config.name}${cell ? ` (account ${cell.address})` : ""} on world ${node.world.file.worldId} (chain ${node.chainId}).`,
+            "Reads need nothing. A write capability is three tools: the act itself, `_simulate` (every check and a dry run, a decision record, nothing sent) and `_build` (the calls for your own account, pass `as`).",
+            "To take a tender: tender_inspect, then tender_precheck (eligible: false names the gate), skill_run with the task's input, tender_submit with the run's resultHash, tender_settle with the answer.",
+            "A refused act returns isError with gate, reason and decisionId; the decision record is the node's account of why. Nothing you say changes a gate: policy is code.",
+        ].join(" "),
+    });
+    for (const summary of catalog.list(caller)) {
+        const cap = catalog.get(summary.name);
+        if (cap.action === "read") {
+            const { schema, wrap } = readOutputSchema(cap);
+            server.registerTool(cap.name, { title: cap.title, description: cap.description, inputSchema: cap.input, outputSchema: schema, annotations: READ_ANNOTATIONS }, async (args) => {
+                const r = await catalog.invoke(node, cap.name, args ?? {}, caller);
+                if (!r.ok)
+                    return refusal(r);
+                return success(wrap ? { result: r.output } : r.output);
+            });
+            continue;
+        }
+        if (cap.action === "admin")
+            continue;
+        const act = cap;
+        const modes = summary.modes;
+        if (modes.includes("act")) {
+            if (act.name === "tender_precheck") {
+                server.registerTool(act.name, { title: act.title, description: act.description, inputSchema: act.input, outputSchema: precheckOutputSchema(act), annotations: GENTLE_ACT_ANNOTATIONS }, async (args) => {
+                    const r = await catalog.invoke(node, act.name, args ?? {}, caller, { mode: "act" });
+                    if (!r.ok)
+                        return success({ eligible: false, gate: r.gate, reason: r.reason, decisionId: r.decisionId ?? null, jobId: r.jobId ?? null });
+                    return success({ eligible: true, decisionId: r.decisionId ?? null, jobId: r.jobId ?? null, result: r.output });
+                });
+            }
+            else {
+                server.registerTool(act.name, { title: act.title, description: act.description, inputSchema: act.input, outputSchema: actOutputSchema(act), annotations: GENTLE_ACTS.has(act.name) ? GENTLE_ACT_ANNOTATIONS : ACT_ANNOTATIONS }, async (args) => {
+                    const r = await catalog.invoke(node, act.name, args ?? {}, caller, { mode: "act" });
+                    if (!r.ok)
+                        return refusal(r);
+                    return success({ ok: true, decisionId: r.decisionId ?? null, jobId: r.jobId ?? null, operations: r.operations ?? [], output: r.output });
+                });
+            }
+        }
+        if (modes.includes("simulate")) {
+            const name = `${act.name}_simulate`;
+            const schema = act.name === "tender_precheck" ? precheckOutputSchema(act) : actOutputSchema(act);
+            server.registerTool(name, { title: `${act.title} (dry run)`, description: `${act.description} Dry run: every check and a simulation of the first call, a decision record, nothing sent.`, inputSchema: act.input, outputSchema: schema, annotations: SIMULATE_ANNOTATIONS }, async (args) => {
+                const r = await catalog.invoke(node, act.name, args ?? {}, caller, { mode: "simulate" });
+                if (act.name === "tender_precheck") {
+                    if (!r.ok)
+                        return success({ eligible: false, gate: r.gate, reason: r.reason, decisionId: r.decisionId ?? null, jobId: r.jobId ?? null });
+                    return success({ eligible: true, decisionId: r.decisionId ?? null, jobId: r.jobId ?? null, result: r.output });
+                }
+                if (!r.ok)
+                    return refusal(r);
+                return success({ ok: true, decisionId: r.decisionId ?? null, jobId: r.jobId ?? null, output: r.output });
+            });
+        }
+        if (modes.includes("build") && act.name !== "tender_precheck" && act.name !== "skill_run") {
+            const name = `${act.name}_build`;
+            server.registerTool(name, { title: `${act.title} (calldata)`, description: `${act.description} Build: the unsigned calls for the account named in \`as\` (your own), to sign and send yourself.`, inputSchema: act.input, outputSchema: buildOutputSchema, annotations: BUILD_ANNOTATIONS }, async (args) => {
+                const r = await catalog.invoke(node, act.name, args ?? {}, caller, { mode: "build" });
+                if (!r.ok)
+                    return refusal(r);
+                return success({ ok: true, ...r.output, decisionId: r.decisionId ?? null });
+            });
+        }
+    }
+    // resources: what a model reads rules and state from
+    server.registerResource("world", "foga://world", { title: "The world", description: "World id, chain, contracts, bundle hash.", mimeType: "application/json" }, async (uri) => {
+        const r = await catalog.invoke(node, "world_describe", {}, caller);
+        return { contents: [{ uri: uri.href, mimeType: "application/json", text: text(r.ok ? r.output : r) }] };
+    });
+    if (cell) {
+        server.registerResource("cell-status", "foga://cell/status", { title: "The cell's status", description: "Anchor, binding, skills, policy summary (and for the operator the budget and open work).", mimeType: "application/json" }, async (uri) => {
+            const r = await catalog.invoke(node, "cell_status", {}, caller);
+            return { contents: [{ uri: uri.href, mimeType: "application/json", text: text(r.ok ? r.output : r) }] };
+        });
+    }
+    server.registerResource("policy", "foga://policy", { title: "The cell's policy", description: "Budget and tender rules the policy engine applies to every act.", mimeType: "application/json" }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "application/json", text: text(node.config.policy) }] }));
+    server.registerResource("spec-foga-cell-v1", "foga://spec/foga-cell-v1", { title: "FOGA-Cell-v1", description: "The ERC-8468 safety specification every FOGA cell adopts.", mimeType: "application/json" }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "application/json", text: text(fogaCellSpecification()) }] }));
+    const matrix = join(repoRoot(), "docs", "compatibility-matrix.md");
+    if (existsSync(matrix)) {
+        server.registerResource("compatibility-matrix", "foga://docs/compatibility-matrix", { title: "Compatibility matrix", description: "The ten standards, what the kernel exercises of each, and the evidence.", mimeType: "text/markdown" }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: readFileSync(matrix, "utf8") }] }));
+    }
+    // the one prompt: take a tender as the node's operator would
+    server.registerPrompt("take-tender", { title: "Take a tender", description: "Work one ERC-8414 tender the way the node's operator would: inspect, pre-check, run the skill, submit, settle.", argsSchema: z.object({ tokenId: z.string().describe("the tender's token id") }) }, ({ tokenId }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        `Take tender ${tokenId} for cell ${node.config.name} if the cell's rules allow it.`,
+                        `1. tender_inspect {"tokenId":"${tokenId}"}: read the task document (skill, packageHash, input, acceptance).`,
+                        `2. tender_precheck {"tokenId":"${tokenId}"}: if eligible is false, stop and report the gate and reason — do not look for a way around it.`,
+                        `3. skill_run {"skill":<the task's skill>,"input":<the task's input>,"tokenId":"${tokenId}"}: the run returns answer, answerHash and resultHash.`,
+                        `4. tender_submit {"tokenId":"${tokenId}","resultHash":<resultHash>,"runReceipt":<runReceipt>}.`,
+                        `5. tender_settle {"tokenId":"${tokenId}","submissionId":<from the submit>,"answer":<answer>}; then credit_withdraw if creditWei is above zero.`,
+                        "Report every decisionId you were given. A refusal is the node's verdict, not an obstacle.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    return server;
+}
+/** The highest mode a caller gets over MCP, for the server's own description of itself. */
+export function callerSummary(caller) {
+    return `${caller.id} (${caller.entrance}; level ${caller.level}, ${caller.visibility} data${ACTION_RANK[caller.level] >= ACTION_RANK.act ? "; may act" : ""})`;
+}