@finchip.ai/foga 0.6.0-alpha.5 → 0.6.0-alpha.7

package/dist/demo/quickstart.js

@@ -0,0 +1,365 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { formatEther, parseEther } from "ethers";
+import { anvilKeys } from "../genesis/roles.js";
+import { Kernel } from "../kernel/kernel.js";
+import { newApiKey } from "../http/server.js";
+import { loadCellConfig, saveCellConfig } from "../node/config.js";
+import { Node } from "../node/node.js";
+import { defaultCatalog, OPERATOR_CALLER } from "../tools/index.js";
+import { ensureWallet, ensuredKey, walletDir } from "../node/wallet.js";
+import { repoRoot } from "../util/fs.js";
+import { deployWorld } from "../world/deploy.js";
+import { ANVIL_INSTALL_HINT, anvilBinary, anvilVersion, launchAnvil, portInUse, portProblem, stopChild } from "./anvil.js";
+import { birthCell } from "./birth.js";
+import { mintCases } from "./demander.js";
+import { cleanEnv, ownCli, waitForHttp } from "./loop-d.js";
+export const MARKER = "quickstart.json";
+export const PACKAGE_NAME = "@finchip.ai/foga";
+/** How a client should start this very CLI: the published package through npx, or this checkout's compiled launcher. */
+export function clientLauncher() {
+    const root = repoRoot();
+    if (/[\\/]node_modules[\\/]/.test(root))
+        return { command: "npx", args: ["-y", PACKAGE_NAME], fromCheckout: false };
+    if (existsSync(join(root, "dist", "cli.js")))
+        return { command: "node", args: [join(root, "bin", "foga.js")], fromCheckout: true };
+    return { command: "npx", args: ["tsx", join(root, "src", "cli.ts")], fromCheckout: true };
+}
+export function defaultQuickstartDir() {
+    return join(homedir(), ".foga", "quickstart");
+}
+/** The MCP client configurations for one cell: the same server definition in each client's file. */
+export function clientConfigs(p) {
+    const stdio = { command: p.launcher.command, args: [...p.launcher.args, "mcp", "--config", p.configPath], env: { FOGA_OPERATOR_KEY_FILE: p.operatorKeyPath } };
+    const out = {
+        "claude_desktop_config.json": JSON.stringify({ mcpServers: { foga: stdio } }, null, 2) + "\n",
+        "claude-code.mcp.json": JSON.stringify({ mcpServers: { foga: { type: "stdio", ...stdio } } }, null, 2) + "\n",
+        "cursor-mcp.json": JSON.stringify({ mcpServers: { foga: stdio } }, null, 2) + "\n",
+    };
+    if (p.nodeUrl)
+        out["http-mcp.json"] = JSON.stringify({ mcpServers: { "foga-http": { type: "http", url: `${p.nodeUrl}/mcp`, headers: { Authorization: `Bearer ${p.apiKey}` } } } }, null, 2) + "\n";
+    return out;
+}
+const q = (s) => (/[\s"]/.test(s) ? JSON.stringify(s) : s);
+export async function runQuickstart(o = {}) {
+    const log = o.log ?? ((line) => console.error(line));
+    const out = o.out ?? ((text) => console.log(text));
+    const root = repoRoot();
+    const dir = resolve(o.dir ?? defaultQuickstartDir());
+    const port = o.port ?? 8545;
+    const listen = o.listen === undefined ? "127.0.0.1:8787" : o.listen;
+    const name = o.name ?? "quick";
+    const rpc = `http://127.0.0.1:${port}`;
+    const walletPath = resolve(o.wallet ?? walletDir());
+    const nodeUrlPlanned = listen ? (() => {
+        const i = listen.lastIndexOf(":");
+        const host = listen.slice(0, i) || "127.0.0.1";
+        return `http://${host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host}:${listen.slice(i + 1)}`;
+    })() : null;
+    // --- say what is wrong before touching anything
+    const anvilBin = anvilBinary();
+    const version = anvilVersion(anvilBin.path);
+    if (!version)
+        throw new Error(ANVIL_INSTALL_HINT);
+    const problem = await portProblem(port);
+    if (problem)
+        throw new Error(problem);
+    if (listen) {
+        const lp = Number(listen.slice(listen.lastIndexOf(":") + 1));
+        if (await portInUse(lp))
+            throw new Error(`port ${lp} is in use; pass --listen <host:port> for the node (or --no-serve to run no node)`);
+    }
+    if (walletPath === dir || walletPath.startsWith(dir + sep))
+        throw new Error(`the wallet (${walletPath}) must live outside the quickstart directory (${dir}), which is cleared on every run`);
+    if (existsSync(dir)) {
+        const entries = readdirSync(dir);
+        if (entries.length && !entries.includes(MARKER))
+            throw new Error(`${dir} exists and is not a quickstart directory (no ${MARKER}); choose another --dir`);
+        if (entries.length) {
+            log(`quickstart: replacing the previous quickstart in ${dir} (its chain ended with its process)`);
+            rmSync(dir, { recursive: true, force: true });
+        }
+    }
+    mkdirSync(dir, { recursive: true });
+    const keysDir = join(dir, "keys");
+    mkdirSync(keysDir, { recursive: true, mode: 0o700 });
+    // --- the wallet: the first step; made now when there is none, reused when there is; never a reason to stop
+    const wallet = ensureWallet(walletPath, { name: "default" });
+    if (wallet.ephemeral)
+        log(`quickstart: wallet: could not write ${walletPath} (${wallet.reason}); using keys made in memory for this run — they are not kept`);
+    else
+        log(`quickstart: wallet: ${wallet.created ? "made" : "using"} ${wallet.wallet.dir} — owner ${wallet.wallet.addresses.owner}, operator ${wallet.wallet.addresses.operator}, guardian ${wallet.wallet.addresses.guardian}`);
+    // --- the chain and the world
+    log(`quickstart: starting ${version} on ${rpc} (log ${join(dir, "anvil.log")})`);
+    const anvil = await launchAnvil({ port, logPath: join(dir, "anvil.log") });
+    let node = null;
+    let endedWith = null;
+    const ended = new Promise((r) => (endedWith = r));
+    anvil.on("exit", (code, signal) => endedWith?.(`anvil stopped (${code !== null ? `exit code ${code}` : `signal ${signal}`})`));
+    const stop = async () => {
+        if (node)
+            await stopChild(node);
+        node = null;
+        await stopChild(anvil);
+    };
+    try {
+        const worldPath = join(dir, "world.json");
+        log("quickstart: deploying the local world (the ten reference implementations and the FOGA contracts)");
+        const { world } = await deployWorld({ worldConfigPath: join(root, "worlds", "local.json"), rpc, outPath: worldPath, quiet: true });
+        log(`quickstart: world ${world.worldId} deployed (${Object.keys(world.contracts).length} contracts)`);
+        // --- the cell: born with fresh keys, funded and attested by W (anvil's first account), its two skills minted
+        const funder = anvilKeys().W;
+        const k = await Kernel.open({ worldPath, rpc, storePath: join(dir, "quickstart.sqlite"), keys: { W: funder } });
+        const W = k.address("W");
+        let cell;
+        try {
+            cell = await birthCell({
+                kernel: k,
+                worldPath,
+                rpc,
+                name,
+                configPath: join(dir, "cell.config.json"),
+                storePath: join(dir, "cell.ops.sqlite"),
+                description: `Cell ${name}: born by foga quickstart on a local anvil chain`,
+                keys: { owner: ensuredKey(wallet, "owner"), operator: ensuredKey(wallet, "operator"), guardian: ensuredKey(wallet, "guardian") },
+                log: (line) => log(`quickstart: ${line}`),
+                configure: (cfg) => {
+                    cfg.policy.budget = { dailyValueWei: parseEther("0.002").toString(), perOperationValueWei: parseEther("0.001").toString(), dailyGasWei: parseEther("0.05").toString(), maxConcurrentCommitments: 2 };
+                    cfg.policy.tenders = { minRewardWei: parseEther("0.0005").toString(), minSubmitWindowSeconds: 600, minSettleWindowSeconds: 600, acceptance: ["hashlock"], counterpartyMinLevel: 0, lookbackBlocks: 9000 };
+                    cfg.runtime.pollSeconds = 2;
+                    cfg.runtime.http.listen = listen ?? "127.0.0.1:8787";
+                    cfg.runtime.http.rateLimitPerMinute = 600;
+                    if (nodeUrlPlanned)
+                        cfg.runtime.http.publicUrl = nodeUrlPlanned;
+                },
+            });
+        }
+        finally {
+            k.close();
+            k.world.provider.destroy();
+        }
+        const configPath = cell.configPath;
+        // --- the key files the configurations name: the wallet's own; an in-memory wallet is written beside the cell so the run still works
+        const keyFile = (file, value) => {
+            const path = join(keysDir, file);
+            writeFileSync(path, value + "\n", { mode: 0o600 });
+            return path;
+        };
+        const keyPaths = wallet.ephemeral
+            ? { owner: keyFile("owner.key", cell.owner.privateKey), operator: keyFile("operator.key", cell.operator.privateKey), guardian: keyFile("guardian.key", cell.guardian.privateKey) }
+            : { owner: wallet.wallet.files.owner, operator: wallet.wallet.files.operator, guardian: wallet.wallet.files.guardian };
+        // an act-level API key for the HTTP entrance
+        const api = newApiKey("agent");
+        {
+            const loaded = loadCellConfig(configPath);
+            loaded.config.access.keys.push({ id: "agent", sha256: api.sha256, level: "act", visibility: "caller", note: "the quickstart's act-level key for the HTTP entrance" });
+            saveCellConfig(configPath, loaded.config);
+        }
+        const agentKeyPath = keyFile("agent.api-key", api.key);
+        // --- the cell says what it is: both skills offered, the documents built and committed on chain (the operator's act, in this process)
+        {
+            const loaded = loadCellConfig(configPath);
+            loaded.config.skills.offered = Object.keys(loaded.config.skills.held);
+            saveCellConfig(configPath, loaded.config);
+            const publisher = await Node.open({ configPath, rpc, keys: { operator: ensuredKey(wallet, "operator") }, log: () => { } });
+            try {
+                const r = await defaultCatalog().invoke(publisher, "docs_publish", {}, OPERATOR_CALLER, { mode: "act" });
+                if (!r.ok)
+                    throw new Error(`docs_publish: ${r.gate}: ${r.reason}`);
+                const out = r.output;
+                log(`quickstart: documents v${out.version} built in ${out.dir} and committed on chain (${out.committed.join(", ")})`);
+            }
+            finally {
+                publisher.close();
+            }
+        }
+        // --- two tenders for the cell to find: a probe of the cell itself and an extraction over the fixture
+        let minted = [];
+        if (o.tenders ?? true) {
+            const r = await mintCases({ worldPath, rpc, storePath: join(dir, "demander.sqlite"), key: funder, cell: cell.account, schemeId: cell.schemeId, issuers: [W], packages: cell.packages, cases: ["a", "b"], seed: 1, log: (line) => log(`quickstart: ${line}`) });
+            minted = r.cases;
+        }
+        // --- the node: watchers, HTTP API, MCP over Streamable HTTP; the operator key alone, from its file
+        const cli = ownCli();
+        let nodeUrl = null;
+        if (listen) {
+            const i = listen.lastIndexOf(":");
+            const host = listen.slice(0, i) || "127.0.0.1";
+            nodeUrl = `http://${host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host}:${listen.slice(i + 1)}`;
+            node = spawn(cli.command, [...cli.args, "node", "serve", "--config", configPath, "--rpc", rpc, "--listen", listen], { env: cleanEnv({ FOGA_OPERATOR_KEY_FILE: keyPaths.operator }), stdio: ["ignore", "ignore", "pipe"] });
+            node.stderr.on("data", (d) => {
+                for (const line of String(d).split("\n"))
+                    if (line.trim())
+                        log(`  node| ${line}`);
+            });
+            node.on("exit", (code, signal) => endedWith?.(`the node stopped (${code !== null ? `exit code ${code}` : `signal ${signal}`})`));
+            await waitForHttp(`${nodeUrl}/healthz`);
+            // --- the entrance answers: health, a public read, the agent key's pre-check of the first tender, the MCP handshake and tool list
+            const health = (await (await fetch(`${nodeUrl}/healthz`)).json());
+            if (!health.ok)
+                throw new Error("the node's /healthz is not ok");
+            const status = (await (await fetch(`${nodeUrl}/api/cell_status`)).json());
+            if (!status.ok || status.output?.account?.toLowerCase() !== cell.account.toLowerCase())
+                throw new Error(`cell_status through HTTP did not name the cell: ${JSON.stringify(status).slice(0, 200)}`);
+            if (minted.length) {
+                const pre = (await (await fetch(`${nodeUrl}/api/tender_precheck`, { method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${api.key}` }, body: JSON.stringify({ tokenId: minted[0].tokenId }) })).json());
+                if (!pre.ok)
+                    throw new Error(`the pre-check of tender ${minted[0].tokenId} was refused at ${pre.gate}: ${pre.reason}`);
+            }
+            const mcpHeaders = { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${api.key}` };
+            const init = await fetch(`${nodeUrl}/mcp`, { method: "POST", headers: mcpHeaders, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-11-25", capabilities: {}, clientInfo: { name: "foga-quickstart", version: "0" } } }) });
+            if (init.status !== 200)
+                throw new Error(`the MCP entrance answered ${init.status} to initialize`);
+            const tools = await fetch(`${nodeUrl}/mcp`, { method: "POST", headers: mcpHeaders, body: JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }) });
+            const toolsText = await tools.text();
+            const toolCount = (toolsText.match(/"name":"/g) ?? []).length;
+            if (toolCount < 20)
+                throw new Error(`the MCP entrance listed ${toolCount} tool(s) for the agent key; expected the act-level set`);
+            const cardRes = await fetch(`${nodeUrl}/.well-known/agent-card.json`);
+            const cardDoc = (await cardRes.json());
+            if (!cardRes.ok || cardDoc.supportedInterfaces?.[0]?.url !== `${nodeUrl}/a2a`)
+                throw new Error(`the agent card at /.well-known/agent-card.json does not name ${nodeUrl}/a2a`);
+            const quoteRes = await fetch(`${nodeUrl}/a2a`, { method: "POST", headers: { "content-type": "application/json", "a2a-version": "1.0" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "SendMessage", params: { message: { messageId: "quickstart-quote", role: "ROLE_USER", parts: [{ text: "What can you do?" }] } } }) });
+            const quoteBody = (await quoteRes.json());
+            if (quoteBody.result?.task?.status?.state !== "TASK_STATE_COMPLETED")
+                throw new Error(`the A2A entrance did not answer a quote: ${JSON.stringify(quoteBody).slice(0, 200)}`);
+            log(`quickstart: the entrance answers — /healthz ok, cell_status names ${cell.account}, tender ${minted[0]?.tokenId ?? "-"} eligible for the agent key, MCP initialize ok, ${toolCount} tools; the agent card names ${nodeUrl}/a2a and a quote came back`);
+        }
+        // --- the stdio server the client configurations name, started as a client would start it: the operator's tool set over stdio
+        const stdioTools = await stdioToolCount(cli, configPath, rpc, cleanEnv({ FOGA_OPERATOR_KEY_FILE: keyPaths.operator }));
+        if (stdioTools < 30)
+            throw new Error(`the stdio MCP server listed ${stdioTools} tool(s) with the operator key; expected the operator's set`);
+        log(`quickstart: the stdio MCP server answers with the operator key — ${stdioTools} tools`);
+        // --- the client configurations, written and printed
+        const launcher = clientLauncher();
+        const configs = clientConfigs({ launcher, configPath, operatorKeyPath: keyPaths.operator, nodeUrl, apiKey: api.key });
+        const mcpDir = join(dir, "mcp");
+        mkdirSync(mcpDir, { recursive: true });
+        for (const [file, text] of Object.entries(configs))
+            writeFileSync(join(mcpDir, file), text);
+        const demanderCmd = `${q(launcher.command)} ${launcher.args.map(q).join(" ")} demo demander --world ${q(worldPath)} --rpc ${rpc} --store ${q(join(dir, "demander.sqlite"))} --cell ${cell.account} --scheme ${cell.schemeId} --issuer ${W} --probe-hash ${cell.packages["foga-probe"]} --extract-hash ${cell.packages["finch-extract-verify"]} --cases a,b --seed <n>`;
+        const claudeCodeAdd = `claude mcp add foga -e FOGA_OPERATOR_KEY_FILE=${q(keyPaths.operator)} -- ${q(launcher.command)} ${launcher.args.map(q).join(" ")} mcp --config ${q(configPath)}`;
+        const lines = [];
+        lines.push(`foga quickstart: a FOGA cell is live on a local chain`);
+        lines.push("");
+        lines.push(`  chain     anvil on ${rpc} (chain ${world.chainId}), world ${world.worldId} — the chain lives as long as this process`);
+        lines.push(`  cell      ${name} = ${cell.account}${cell.agentId ? ` (ERC-8004 agent ${cell.agentId})` : ""}`);
+        lines.push(`  wallet    ${wallet.ephemeral ? `keys made in memory for this run, written to ${keysDir} (${walletPath} was not writable)` : `${wallet.wallet.dir} (${wallet.created ? "made now" : "reused"}) — owner ${cell.owner.address}, operator ${cell.operator.address}, guardian ${cell.guardian.address}; the same wallet on every run`}`);
+        lines.push(`  skills    ${Object.keys(cell.held).join(", ")} (held and offered)`);
+        if (minted.length)
+            lines.push(`  tenders   ${minted.map((c) => `#${c.tokenId} ${c.skill} (${formatEther(c.rewardWei)} ETH)`).join(", ")} — open, waiting for the cell to take them`);
+        if (nodeUrl)
+            lines.push(`  node      ${nodeUrl} — /mcp (Streamable HTTP), /api/<capability>, /a2a (A2A 1.0, JSON-RPC), /.well-known/agent-card.json, /documents/*, /healthz; its watchers settle and withdraw`);
+        lines.push(`  documents ${join(dir, "documents")} — registration, AID document, ARD descriptor, AUF unit, agent card, server.json; committed on chain${nodeUrl ? ` as URLs under ${nodeUrl}` : ""}`);
+        lines.push(`  files     ${configPath} (the cell), ${join(dir, "connect.md")} (this text), ${mcpDir}${process.platform === "win32" ? "\\" : "/"}*.json (the client configurations)`);
+        lines.push("");
+        lines.push("Connect an MCP client over stdio (the client starts the server on this machine; with the operator key it acts for the cell):");
+        lines.push(`  Claude Desktop   claude_desktop_config.json, the mcpServers block:        ${join(mcpDir, "claude_desktop_config.json")}`);
+        lines.push(`  Claude Code      .mcp.json in a project:                                 ${join(mcpDir, "claude-code.mcp.json")}`);
+        lines.push(`                   or one command:  ${claudeCodeAdd}`);
+        lines.push(`  Cursor           .cursor/mcp.json:                                       ${join(mcpDir, "cursor-mcp.json")}`);
+        lines.push("");
+        lines.push(configs["claude_desktop_config.json"].trimEnd().split("\n").map((l) => `  ${l}`).join("\n"));
+        if (nodeUrl) {
+            lines.push("");
+            lines.push("Or over HTTP (a client on another machine, or any agent runtime that speaks HTTP):");
+            lines.push(`  MCP      ${nodeUrl}/mcp   with the header   Authorization: Bearer ${api.key}   (${join(mcpDir, "http-mcp.json")})`);
+            lines.push(`  API      ${nodeUrl}/api/<capability>, POST a JSON body (reads also GET); the same header for acts. GET ${nodeUrl}/api/capabilities lists them.`);
+            lines.push(`  A2A      POST ${nodeUrl}/a2a with A2A-Version: 1.0 — SendMessage for a quote (anyone) or a tender ({"foga":{"mode":"tender","tokenId":"…"}}, the header above); the card is at ${nodeUrl}/.well-known/agent-card.json`);
+            lines.push(`  wallet   a credential of your own instead of the key: Authorization: FOGA-EIP712 <envelope> signed by any wallet (foga wallet sign --url ${nodeUrl} prints one; docs/wallet.md)`);
+            lines.push(`           curl -s ${nodeUrl}/api/cell_status`);
+            if (minted.length)
+                lines.push(`           curl -s -X POST ${nodeUrl}/api/tender_precheck -H "content-type: application/json" -H "authorization: Bearer ${api.key}" -d "{\\"tokenId\\":\\"${minted[0].tokenId}\\"}"`);
+        }
+        lines.push("");
+        lines.push("What a connected agent does with a tender: tender_list, tender_inspect, tender_precheck (eligible: false is the cell's verdict), skill_run with the");
+        lines.push("task's skill and input, tender_submit with the run's resultHash and runReceipt; the node settles and withdraws. More tenders for the cell:");
+        lines.push(`  FOGA_DEMANDER_KEY=<a funded key, anvil's first account by default> ${demanderCmd}`);
+        if (launcher.fromCheckout)
+            lines.push(`(This is a checkout: the configurations start ${launcher.command} ${launcher.args.join(" ")}; a published install would start npx -y ${PACKAGE_NAME}.)`);
+        lines.push("");
+        lines.push(o.exit ? "Started with --exit: stopping the node and the chain." : "Ctrl-C stops the node and the chain; the next quickstart starts over in the same directory.");
+        const summary = lines.join("\n");
+        writeFileSync(join(dir, "connect.md"), `# foga quickstart\n\n\`\`\`\n${summary}\n\`\`\`\n`);
+        writeFileSync(join(dir, MARKER), JSON.stringify({ schema: "foga.quickstart/1", createdAt: new Date().toISOString(), rpc, chainId: world.chainId, worldId: world.worldId, cell: name, account: cell.account, agentId: cell.agentId, wallet: wallet.ephemeral ? null : wallet.wallet.dir, nodeUrl, tenders: minted.map((c) => c.tokenId), anvil: version }, null, 2) + "\n");
+        out(summary);
+        return {
+            dir,
+            rpc,
+            chainId: world.chainId,
+            worldId: world.worldId,
+            worldPath,
+            configPath,
+            account: cell.account,
+            agentId: cell.agentId,
+            wallet: { dir: wallet.wallet.dir, created: wallet.created, ephemeral: wallet.ephemeral, addresses: wallet.wallet.addresses },
+            keys: { ...keyPaths, agentApiKey: agentKeyPath },
+            apiKey: api.key,
+            nodeUrl,
+            tenders: minted.map((c) => ({ id: c.id, tokenId: c.tokenId, skill: c.skill, rewardWei: c.rewardWei })),
+            clientConfigs: configs,
+            summary,
+            stop,
+            ended,
+        };
+    }
+    catch (e) {
+        await stop();
+        throw e;
+    }
+}
+/** Start `foga mcp --config …` as a client would and count the tools it lists; a raw 2025-era JSON-RPC exchange over stdio. */
+async function stdioToolCount(cli, configPath, rpc, env) {
+    const child = spawn(cli.command, [...cli.args, "mcp", "--config", configPath, "--rpc", rpc], { env, stdio: ["pipe", "pipe", "pipe"] });
+    let stderr = "";
+    child.stderr.on("data", (d) => (stderr += d));
+    const pending = new Map();
+    let buffer = "";
+    child.stdout.on("data", (d) => {
+        buffer += d;
+        let i;
+        while ((i = buffer.indexOf("\n")) >= 0) {
+            const line = buffer.slice(0, i);
+            buffer = buffer.slice(i + 1);
+            if (!line.trim())
+                continue;
+            try {
+                const msg = JSON.parse(line);
+                if (msg.id !== undefined && pending.has(msg.id)) {
+                    pending.get(msg.id)(msg);
+                    pending.delete(msg.id);
+                }
+            }
+            catch {
+                /* not a protocol message: the check below fails on the count */
+            }
+        }
+    });
+    let nextId = 1;
+    const request = (method, params) => new Promise((resolveReq, reject) => {
+        const id = nextId++;
+        const timer = setTimeout(() => reject(new Error(`stdio MCP: ${method} timed out; the server said:\n${stderr.slice(-2000)}`)), 60_000);
+        pending.set(id, (msg) => {
+            clearTimeout(timer);
+            if (msg.error)
+                reject(new Error(`stdio MCP: ${method}: ${JSON.stringify(msg.error)}`));
+            else
+                resolveReq(msg.result);
+        });
+        child.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
+    });
+    try {
+        const init = await request("initialize", { protocolVersion: "2025-11-25", capabilities: {}, clientInfo: { name: "foga-quickstart", version: "0" } });
+        if (init?.serverInfo?.name !== "foga")
+            throw new Error(`stdio MCP: initialize answered ${JSON.stringify(init).slice(0, 200)}`);
+        child.stdin.write(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }) + "\n");
+        const tools = await request("tools/list", {});
+        return Array.isArray(tools?.tools) ? tools.tools.length : 0;
+    }
+    finally {
+        child.stdin.end();
+        await stopChild(child, 3000);
+    }
+}

package/dist/doctor/loop-d.js

@@ -6,8 +6,13 @@ export function loadLoopDEvidence(path) {
     return e;
 }
 const row = (check, verdict, expected, actual, detail) => ({ check, verdict, expected, actual, ...(detail ? { detail } : {}) });
+/** The proposer's decisions: the runner's for a model, the agent key's for an outside agent (older evidence names no caller: the runner). */
+function proposerCaller(e) {
+    return e.model.caller ?? "runner";
+}
 export function loopDVerdicts(e, compare) {
     const rows = [];
+    const external = e.model.provider === "external";
     const allowed = e.decisions.filter((d) => d.verdict === "allowed");
     const refused = e.decisions.filter((d) => d.verdict === "refused");
     const jobOps = e.operations.filter((o) => o.signer === "operator" && o.key.startsWith("job:"));
@@ -31,13 +36,18 @@ export function loopDVerdicts(e, compare) {
     rows.push(row("operator transactions all go to the account, inside its allow-list", astray.length || unlisted.length ? "Fail" : txs.length ? "Pass" : "NotTested", "every transaction signed by the operator key calls the account's execute with an allow-listed (target, selector)", `${txs.length} transaction(s) in blocks ${e.chain.fromBlock}-${e.chain.toBlock}; ${astray.length} elsewhere, ${unlisted.length} not allow-listed`, astray.length || unlisted.length ? [...astray.map((t) => `${t.hash} -> ${t.to}`), ...unlisted.map((t) => `${t.hash} -> ${t.inner ? `${t.inner.target} ${t.inner.selector}` : "not execute"}`)].join("; ") : undefined));
     const reverted = txs.filter((t) => t.status === 0);
     rows.push(row("no operator transaction reverted", reverted.length ? "Unknown" : txs.length ? "Pass" : "NotTested", "the account's gate was never the one to refuse what every check allowed", reverted.length ? `${reverted.length} reverted: ${reverted.map((t) => t.hash).join(", ")}` : `${txs.length} succeeded`, reverted.length ? "a revert after an allowed decision is the chain refusing, not a policy refusal; see the execution decisions" : undefined));
-    // 5. the cases
+    // 5. the cases (an outside agent may leave a tender alone: nothing the cell's rules forbid happened, nothing was tested either)
     for (const c of e.cases) {
         const o = c.outcome;
         const exp = c.expect;
         let verdict = "Fail";
         let actual = `${o.status}${o.gates.length ? ` (gates ${o.gates.join(" > ")})` : ""}`;
-        if (exp.outcome === "taken") {
+        const untouched = external && !o.settled && !o.submissions.some((s) => s.byCell) && o.gates.every((g) => g === "allowed" || g === "safety");
+        if (untouched) {
+            verdict = "NotTested";
+            actual += o.gates.includes("safety") ? "; refused at safety during the suspension, never submitted after the resume" : o.gates.length ? "; pre-checked by the agent but never submitted" : "; the agent made no attempt";
+        }
+        else if (exp.outcome === "taken") {
             const reached = BigInt(o.paidWei) + BigInt(o.withdrawnWei);
             const paid = reached === BigInt(c.rewardWei);
             verdict = o.status === "taken" && o.settled && paid ? "Pass" : "Fail";
@@ -57,9 +67,11 @@ export function loopDVerdicts(e, compare) {
     // 6. case g: a proposal above the budget
     const g = e.budgetProbe;
     rows.push(row("case g: a proposal above the budget is refused at budget", g.attempted ? (g.gate === "budget" ? "Pass" : "Fail") : "NotTested", "the model's over-budget act refused at `budget`, nothing broadcast", g.attempted ? `${g.capability} refused at ${g.gate} (decision ${g.decisionId})` : "the model made no proposal above the budget", g.attempted ? undefined : "the stub makes this proposal on purpose; a real model may never make it"));
-    // 7. the evidence is complete
-    const complete = e.runner.ticks > 0 && e.runner.trajectoryHashes.length === e.runner.ticks && e.model.model.length > 0 && e.decisions.length > 0;
-    rows.push(row("the evidence carries every decision and every tick's trajectory hash", complete ? "Pass" : "Fail", "model named, a hash per tick, decision records present", `${e.model.provider}/${e.model.model || "?"}, ${e.runner.ticks} tick(s), ${e.runner.trajectoryHashes.length} hash(es), ${e.decisions.length} decision(s), ${e.runner.errors} model error(s)`));
+    // 7. the evidence is complete: a model's run has a hash per tick; an outside agent's run has the agent's decisions (its transcript is its own)
+    const proposer = proposerCaller(e);
+    const proposed = e.decisions.filter((d) => d.caller === proposer).length;
+    const complete = external ? e.model.model.length > 0 && proposed > 0 : e.runner.ticks > 0 && e.runner.trajectoryHashes.length === e.runner.ticks && e.model.model.length > 0 && e.decisions.length > 0;
+    rows.push(row("the evidence carries every decision and every tick's trajectory hash", complete ? "Pass" : "Fail", external ? "the agent named, decision records of its proposals present (no transcript: the agent's words stay with the agent)" : "model named, a hash per tick, decision records present", external ? `${e.model.provider}/${e.model.model || "?"} as caller ${proposer}: ${proposed} decision(s) on its proposals, ${e.decisions.length} in all` : `${e.model.provider}/${e.model.model || "?"}, ${e.runner.ticks} tick(s), ${e.runner.trajectoryHashes.length} hash(es), ${e.decisions.length} decision(s), ${e.runner.errors} model error(s)`));
     // 8. recovery: killed after a submission, restarted, nothing sent twice
     const r = e.recovery;
     if (r.performed && r.tokenId) {
@@ -81,21 +93,31 @@ export function loopDVerdicts(e, compare) {
     const uniqueNonces = new Set(nonces).size === nonces.length;
     const nonceFailures = e.operations.filter((o) => o.signer === "operator" && o.status === "failed" && /nonce/i.test(o.error ?? ""));
     rows.push(row("concurrent acts across entrances and the watchers: distinct nonces, the budget holding", conc ? (uniqueNonces && nonceFailures.length === 0 && conc.allowed + conc.refused.length === conc.requested && conc.refused.every((x) => x.gate === "budget") ? "Pass" : "Fail") : uniqueNonces && nonceFailures.length === 0 ? "Pass" : "Fail", "every operator operation on its own nonce, no nonce failure, refusals (if any) at `budget`", `${nonces.length} nonce(s), ${uniqueNonces ? "all distinct" : "repeated"}, ${nonceFailures.length} nonce failure(s)${conc ? `; ${conc.requested} concurrent mint(s): ${conc.allowed} allowed, ${conc.refused.length} refused (${conc.refused.map((x) => x.gate).join(", ") || "-"})` : ""}`));
-    // 10. model-agnostic: the stub and a real model reach the same outcomes
+    // 10. model-agnostic: two proposers (the stub, a real model, an outside agent) reach the same outcomes; a case one of them left alone compares to nothing
     if (compare) {
         const diffs = [];
+        const skipped = [];
+        let agreed = 0;
+        const decided = (o) => o.status !== "pending" && o.status !== "other";
         for (const c of e.cases) {
             const other = compare.cases.find((x) => x.id === c.id);
             if (!other) {
                 diffs.push(`${c.id}: missing in the other run`);
                 continue;
             }
+            if (!decided(c.outcome) || !decided(other.outcome)) {
+                skipped.push(c.id);
+                continue;
+            }
             const a = `${c.outcome.status}/${c.outcome.gates[0] ?? "-"}`;
             const b = `${other.outcome.status}/${other.outcome.gates[0] ?? "-"}`;
             if (a !== b)
                 diffs.push(`${c.id}: ${a} vs ${b}`);
+            else
+                agreed++;
         }
-        rows.push(row("model-agnostic: the same outcomes from both models", diffs.length ? "Fail" : "Pass", "every case ends the same way under both models", diffs.length ? diffs.join("; ") : `${e.cases.length} case(s) agree (${e.model.provider}/${e.model.model} vs ${compare.model.provider}/${compare.model.model})`));
+        const label = `${e.model.provider}/${e.model.model} vs ${compare.model.provider}/${compare.model.model}`;
+        rows.push(row("model-agnostic: the same outcomes from both models", diffs.length ? "Fail" : agreed ? "Pass" : "NotTested", "every case ends the same way under both proposers", diffs.length ? diffs.join("; ") : agreed ? `${agreed} case(s) agree (${label})${skipped.length ? `; ${skipped.join(", ")} left alone in one of the runs, not compared` : ""}` : `no case reached a verdict in both runs (${label})`));
     }
     else
         rows.push(row("model-agnostic: the same outcomes from both models", "NotTested", "every case ends the same way under both models", "one run only; pass a second evidence file with --compare"));

package/dist/genesis/operator-scope.js

@@ -12,6 +12,7 @@ export const SCOPE_GROUPS = {
         { contract: "8444/ARDOnchainRegistry", fn: "register(bytes32,address,uint256,bytes32,string,string)" },
         { contract: "8444/ARDOnchainRegistry", fn: "updateDescriptor(bytes32,bytes32,string,string)" },
         { contract: "8454/AUFUnitRegistry", fn: "registerUnit(address,bytes32,string,(uint256,uint32)[])" },
+        { contract: "8454/AUFUnitRegistry", fn: "publishVersion(uint256,bytes32,string,(uint256,uint32)[])" },
         { contract: "8447/ERC8004Eligibility", fn: "declareAgent(uint256)" },
     ],
     standing: [{ contract: "8419/KYARegistry", fn: "attestWithProof((bytes32,bytes),bytes32,bytes,bytes,string)" }],

package/dist/http/access.js

@@ -0,0 +1,105 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { getAddress } from "ethers";
+import { accountSubject } from "../core/kya.js";
+import { ACTION_RANK, PUBLIC_CALLER } from "../tools/index.js";
+import { SIGNED_SCHEME, verifyAuthorization } from "./signed.js";
+const KEY_PREFIX = "foga";
+/** Make an API key for a grant: shown once, stored only as its hash. */
+export function newApiKey(id) {
+    const key = `${KEY_PREFIX}.${id}.${randomBytes(24).toString("base64url")}`;
+    return { key, sha256: "0x" + createHash("sha256").update(key).digest("hex") };
+}
+/** The caller an Authorization header establishes: the public without one, the grant of a valid key, or null for an invalid key. */
+export function callerFromAuthorization(cfg, header) {
+    if (!header)
+        return { ...PUBLIC_CALLER, entrance: "http" };
+    const m = /^Bearer\s+(\S+)$/i.exec(header.trim());
+    if (!m)
+        return null;
+    const key = m[1];
+    const parts = key.split(".");
+    if (parts.length !== 3 || parts[0] !== KEY_PREFIX)
+        return null;
+    const grant = cfg.access.keys.find((k) => k.id === parts[1]);
+    if (!grant)
+        return null;
+    const given = Buffer.from(createHash("sha256").update(key).digest("hex"), "hex");
+    const stored = Buffer.from(grant.sha256.slice(2), "hex");
+    if (given.length !== stored.length || !timingSafeEqual(given, stored))
+        return null;
+    return { id: grant.id, entrance: "http", level: grant.level, visibility: grant.visibility };
+}
+export async function resolveCaller(i) {
+    const { node } = i;
+    const cfg = node.config;
+    const header = i.authorization?.trim();
+    if (!header)
+        return { caller: { ...PUBLIC_CALLER, entrance: "http" }, via: "anonymous" };
+    if (/^bearer\s/i.test(header)) {
+        const caller = callerFromAuthorization(cfg, header);
+        if (!caller)
+            return { caller: null, status: 401, reason: "the Authorization header carries no key this node knows" };
+        return { caller, via: "key" };
+    }
+    if (new RegExp(`^${SIGNED_SCHEME}\\s`, "i").test(header)) {
+        if (!node.cell)
+            return { caller: null, status: 403, reason: "this node has no cell to sign for yet" };
+        const v = verifyAuthorization(header, { chainId: node.chainId, cell: node.cell.address, method: i.method, path: i.path, body: i.body, now: i.now, nonces: i.nonces });
+        if (!v.ok)
+            return { caller: null, status: 401, reason: `signature refused: ${v.reason}` };
+        const grant = await grantFor(node, v.envelope);
+        if (!grant)
+            return { caller: null, status: 403, reason: "this node does not accept signatures (access.signers.default is none)" };
+        let level = grant.level;
+        if (!v.bound && cfg.access.signers.actsNeedRequestBinding && ACTION_RANK[level] >= ACTION_RANK.act)
+            level = "build";
+        return { caller: { id: v.envelope.signer, entrance: "http", level, visibility: grant.visibility }, via: "signature", signer: v.envelope };
+    }
+    return { caller: null, status: 401, reason: `the Authorization scheme is not one this node accepts (Bearer <key> or ${SIGNED_SCHEME} <envelope>)` };
+}
+/** The grant a verified signer gets, from the cell's roles, the configuration's grants, its standing, or the default. */
+export async function grantFor(node, e) {
+    const cfg = node.config;
+    const signer = getAddress(e.signer);
+    const roles = [
+        ["operator", cfg.identity.operator],
+        ["owner", cfg.identity.owner],
+    ];
+    for (const [name, address] of roles)
+        if (getAddress(address) === signer)
+            return { level: "act", visibility: "operator", why: `the cell's ${name}` };
+    const s = cfg.access.signers;
+    const byAddress = s.allow.find((g) => g.address && getAddress(g.address) === signer);
+    if (byAddress)
+        return { level: byAddress.level, visibility: byAddress.visibility, why: `granted by address${byAddress.note ? ` (${byAddress.note})` : ""}` };
+    if (e.agentId) {
+        const byAgent = s.allow.find((g) => g.agentId && g.agentId === e.agentId);
+        if (byAgent && (await actsForAgent(node, signer, e.agentId)))
+            return { level: byAgent.level, visibility: byAgent.visibility, why: `granted as ERC-8004 agent ${e.agentId}` };
+    }
+    if (s.standing && cfg.identity.standing) {
+        try {
+            const subject = accountSubject(node.chainId, signer);
+            const meets = await node.kernel.kya.check(subject, cfg.identity.standing.schemeId, s.standing.minLevel, cfg.identity.standing.issuers);
+            if (meets)
+                return { level: s.standing.level, visibility: s.standing.visibility, why: `KYA standing at level ${s.standing.minLevel} or above` };
+        }
+        catch {
+            /* no standing readable: the default applies */
+        }
+    }
+    if (s.default === "none")
+        return null;
+    return { level: s.default, visibility: "caller", why: "any valid signer" };
+}
+/** Whether `signer` is the owner or the agent wallet of ERC-8004 agent `agentId` on this world's registry. */
+export async function actsForAgent(node, signer, agentId) {
+    try {
+        const id = BigInt(agentId);
+        const [owner, wallet] = await Promise.all([node.kernel.identity.ownerOf(id).catch(() => null), node.kernel.identity.agentWallet(id).catch(() => null)]);
+        return [owner, wallet].some((a) => a && getAddress(a) === getAddress(signer));
+    }
+    catch {
+        return false;
+    }
+}