@finchip.ai/foga 0.6.1 → 0.7.0

package/dist/cli.js

@@ -53,6 +53,11 @@ usage:
                                                  one command to a live cell: the wallet (made on the first run, reused after), anvil, the local world, a cell born with
                                                  the wallet's keys and its two skills, two tenders, the node serving HTTP and MCP, and the MCP client configurations
                                                  printed with every path filled in (~/.foga/quickstart)
+  foga join [--chain sepolia | --world <deployed.json>] [--rpc <url>] [--name <cell>] [--dir <dir>] [--wallet <dir>]
+            [--listen <host:port> | --no-serve] [--public-url <url>] [--run stub|anthropic] [--no-wait] [--min-wei <n>] [--capital-wei <n>] [--exit]
+                                                 one command to a cell that lives on a public chain: the wallet (made once, the same address on every chain), the
+                                                 chain's world from the package, a wait for the identity to be funded, the birth, the skills minted and offered, the
+                                                 documents on chain, the node served (or run with a model); resumable, in ~/.foga/cells/<network>/<name>, never cleared
   foga demo [--port <n>] [--keep] [--genesis <T0..T9>]   start anvil, deploy the local world, run the doctor (and the genesis)
   foga demo --loop-d [--model stub|anthropic|external] [--model-name <name>] [--seed <n>] [--no-recovery] [--port <n>] [--keep]
                                                  the above, then Loop D: a new cell born, a demander minting cases a-g, the node with a model (or served for an
@@ -525,6 +530,51 @@ async function main() {
             return; // a stop that was asked for: both children are gone
         fail(`${why}; the quickstart is over`);
     }
+    if (group === "join") {
+        const { runJoin } = await import("./node/join.js");
+        const run = str(flags, "run");
+        if (run && run !== "stub" && run !== "anthropic")
+            fail("--run must be stub or anthropic");
+        let result;
+        try {
+            result = await runJoin({
+                chain: str(flags, "chain"),
+                world: str(flags, "world"),
+                rpc: str(flags, "rpc"),
+                name: str(flags, "name"),
+                dir: str(flags, "dir"),
+                wallet: str(flags, "wallet"),
+                listen: flags["no-serve"] ? null : str(flags, "listen"),
+                publicUrl: str(flags, "public-url"),
+                run: run ?? null,
+                wait: !flags["no-wait"],
+                minWei: str(flags, "min-wei") ? BigInt(str(flags, "min-wei")) : undefined,
+                capitalWei: str(flags, "capital-wei") ? BigInt(str(flags, "capital-wei")) : undefined,
+                exit: Boolean(flags.exit),
+            });
+        }
+        catch (e) {
+            fail(e.message);
+        }
+        if (flags.exit || !result.nodeUrl) {
+            await result.stop();
+            return;
+        }
+        let asked = false;
+        const stopping = () => {
+            if (asked)
+                return;
+            asked = true;
+            console.error("join: stopping the node; the cell stays");
+            result.stop().finally(() => process.exit(0));
+        };
+        process.on("SIGINT", stopping);
+        process.on("SIGTERM", stopping);
+        const why = await result.ended;
+        if (why === "stopped")
+            return;
+        fail(`${why}; start it again with the same command`);
+    }
     if (group === "demo") {
         await demo({ port: Number(str(flags, "port") ?? 8545), keep: Boolean(flags.keep), genesis: str(flags, "genesis"), loopD: flags["loop-d"] ? loopDFlags(flags) : undefined });
         return;

package/dist/core/chains.js

@@ -0,0 +1,82 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { repoRoot } from "../util/fs.js";
+export const CHAINS = {
+    sepolia: {
+        name: "sepolia",
+        chainId: 11155111,
+        world: "deployments/sepolia.example.json",
+        rpcEnv: "SEPOLIA_RPC_URL",
+        rpc: ["https://ethereum-sepolia-rpc.publicnode.com", "https://rpc.sepolia.org", "https://1rpc.io/sepolia"],
+        faucets: ["https://cloud.google.com/application/web3/faucet/ethereum/sepolia", "https://www.alchemy.com/faucets/ethereum-sepolia", "https://sepoliafaucet.com"],
+        explorer: "https://sepolia.etherscan.io",
+        testnet: true,
+    },
+    "base-sepolia": {
+        name: "base-sepolia",
+        chainId: 84532,
+        world: null,
+        rpcEnv: "BASE_SEPOLIA_RPC_URL",
+        rpc: ["https://sepolia.base.org", "https://base-sepolia-rpc.publicnode.com"],
+        faucets: ["https://docs.base.org/base-chain/tools/network-faucets", "https://cloud.google.com/application/web3/faucet/base/sepolia"],
+        explorer: "https://sepolia.basescan.org",
+        testnet: true,
+    },
+    "optimism-sepolia": {
+        name: "optimism-sepolia",
+        chainId: 11155420,
+        world: null,
+        rpcEnv: "OPTIMISM_SEPOLIA_RPC_URL",
+        rpc: ["https://sepolia.optimism.io", "https://optimism-sepolia-rpc.publicnode.com"],
+        faucets: ["https://console.optimism.io/faucet", "https://cloud.google.com/application/web3/faucet/optimism/sepolia"],
+        explorer: "https://sepolia-optimism.etherscan.io",
+        testnet: true,
+    },
+    "arbitrum-sepolia": {
+        name: "arbitrum-sepolia",
+        chainId: 421614,
+        world: null,
+        rpcEnv: "ARBITRUM_SEPOLIA_RPC_URL",
+        rpc: ["https://sepolia-rollup.arbitrum.io/rpc", "https://arbitrum-sepolia-rpc.publicnode.com"],
+        faucets: ["https://docs.arbitrum.io/for-devs/dev-tools-and-resources/chain-info", "https://cloud.google.com/application/web3/faucet/arbitrum/sepolia"],
+        explorer: "https://sepolia.arbiscan.io",
+        testnet: true,
+    },
+    anvil: {
+        name: "anvil",
+        chainId: 31337,
+        world: null,
+        rpcEnv: "FOGA_RPC_URL",
+        rpc: ["http://127.0.0.1:8545"],
+        faucets: [],
+        explorer: null,
+        testnet: true,
+    },
+};
+/** The chain by name, or null; names are case-insensitive. */
+export function chainByName(name) {
+    return CHAINS[name.toLowerCase()] ?? null;
+}
+/** The chain whose id this is, or null. */
+export function chainById(chainId) {
+    return Object.values(CHAINS).find((c) => c.chainId === chainId) ?? null;
+}
+/** The absolute path of the packaged world for a chain, or null when none ships or the file is missing. */
+export function packagedWorld(chain) {
+    if (!chain.world)
+        return null;
+    const path = join(repoRoot(), chain.world);
+    return existsSync(path) ? path : null;
+}
+/** The RPC for a chain: the one given, the chain's own variable, the general one, then the first public endpoint. */
+export function resolveRpc(chain, given) {
+    if (given)
+        return { url: given, source: "flag" };
+    if (chain && process.env[chain.rpcEnv])
+        return { url: process.env[chain.rpcEnv], source: "env" };
+    if (process.env.FOGA_RPC_URL)
+        return { url: process.env.FOGA_RPC_URL, source: "env" };
+    if (chain?.rpc[0])
+        return { url: chain.rpc[0], source: "public" };
+    throw new Error("no RPC: pass --rpc <url> or set FOGA_RPC_URL");
+}

package/dist/demo/anvil.js

@@ -62,6 +62,17 @@ export async function waitForRpc(rpc, timeoutMs, giveUp) {
     throw new Error(`RPC at ${rpc} did not come up within ${timeoutMs} ms`);
 }
 /** Why a port cannot be used for a new anvil: another RPC already answers there, or something else holds it. */
+/**
+ * The first port from `from` (inclusive) that nothing on 127.0.0.1 accepts connections on, trying `tries` ports in a
+ * row; null when all are taken. For the defaults a quickstart falls back on when its usual port is busy — the next
+ * one up rather than an ephemeral one, so the URL it prints is still one a person can remember.
+ */
+export async function nextFreePort(from, tries = 20) {
+    for (let p = from; p < from + tries; p++)
+        if (!(await portInUse(p)))
+            return p;
+    return null;
+}
 export async function portProblem(port) {
     if (!(await portInUse(port)))
         return null;

package/dist/demo/quickstart.js

@@ -12,7 +12,7 @@ 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 { ANVIL_INSTALL_HINT, anvilBinary, anvilVersion, launchAnvil, nextFreePort, portInUse, portProblem, stopChild } from "./anvil.js";
 import { birthCell } from "./birth.js";
 import { mintCases } from "./demander.js";
 import { cleanEnv, ownCli, waitForHttp } from "./loop-d.js";
@@ -49,29 +49,48 @@ export async function runQuickstart(o = {}) {
     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);
+    // The default ports give way when something else holds them — a served cell on 8787 (the reference cell's own box,
+    // or a node of yours), another chain on 8545 — so the bare command works on any machine; the next free port up is
+    // taken and said so. A port asked for by name (--port, --listen) is not moved: that one is refused as before.
+    let port = o.port ?? 8545;
+    if (o.port === undefined && (await portInUse(port))) {
+        const next = await nextFreePort(port + 1);
+        if (next === null)
+            throw new Error(`ports ${port}-${port + 20} are all in use; pass --port <n> for the chain`);
+        log(`quickstart: port ${port} is in use (another chain or node); anvil takes ${next} instead`);
+        port = next;
+    }
+    else {
+        const problem = await portProblem(port);
+        if (problem)
+            throw new Error(problem);
+    }
+    let listen = o.listen === undefined ? "127.0.0.1:8787" : o.listen;
     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 (await portInUse(lp)) {
+            if (o.listen !== undefined)
+                throw new Error(`port ${lp} is in use; pass --listen <host:port> for the node (or --no-serve to run no node)`);
+            const next = await nextFreePort(lp + 1);
+            if (next === null)
+                throw new Error(`ports ${lp}-${lp + 20} are all in use; pass --listen <host:port> for the node (or --no-serve)`);
+            log(`quickstart: port ${lp} is in use (a served cell, perhaps); the node listens on ${next} instead`);
+            listen = `127.0.0.1:${next}`;
+        }
     }
+    const rpc = `http://127.0.0.1:${port}`;
+    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;
     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)) {

package/dist/mcp/server.js

@@ -145,7 +145,11 @@ export function buildMcpServer(o) {
     // how to become a cell: every cell carries the genome's instructions, so an agent that meets one can make itself one
     const quickstartDoc = join(repoRoot(), "docs", "quickstart.md");
     if (existsSync(quickstartDoc)) {
-        server.registerResource("quickstart", "foga://docs/quickstart", { title: "Become a cell", description: "How any agent makes itself a FOGA cell: one command, its own wallet, the same program this node runs.", mimeType: "text/markdown" }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: readFileSync(quickstartDoc, "utf8") }] }));
+        server.registerResource("quickstart", "foga://docs/quickstart", { title: "A local try", description: "How any agent makes itself a FOGA cell on a local chain in one command: its own wallet, the same program this node runs.", mimeType: "text/markdown" }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: readFileSync(quickstartDoc, "utf8") }] }));
+    }
+    const joinDoc = join(repoRoot(), "docs", "join.md");
+    if (existsSync(joinDoc)) {
+        server.registerResource("join", "foga://docs/join", { title: "Become a cell", description: "How any agent becomes a FOGA cell that lives on a public chain in one command (foga join): the wallet, the funding, the birth, the card, work over the chain, other chains with the same key.", mimeType: "text/markdown" }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: readFileSync(joinDoc, "utf8") }] }));
     }
     server.registerPrompt("become-a-cell", { title: "Become a cell", description: "Replicate: make yourself a FOGA cell on your own machine, with your own wallet — the same program as this node, your own identity.", argsSchema: z.object({}) }, () => ({
         messages: [
@@ -155,13 +159,15 @@ export function buildMcpServer(o) {
                     type: "text",
                     text: [
                         `You are talking to cell ${node.config.name}${cell ? ` (account ${cell.address})` : ""} through the Finch OG Agent node software, version ${o.version}. You can become a cell yourself: the program is public, the identity you make is your own, and nothing of this cell's identity is copied.`,
-                        "On a machine where you can run commands (Node 22.13 or newer, and Foundry's anvil for a local chain):",
-                        "1. A key of your own, first and once:  npx -y @finchip.ai/foga wallet new          (one signer key in ~/.foga/wallet — your identity, which fills every role a cell needs; never overwritten; a failure here never blocks the next step)",
-                        "2. A living cell on a local chain:  npx -y @finchip.ai/foga quickstart         (anvil, the world, a cell born with your wallet's keys, two tenders, the node served; it prints the MCP client configuration to connect a model to the cell)",
-                        "3. Connect your model: paste the printed configuration into your MCP client (Claude Desktop, Claude Code, Cursor, or any client with the HTTP form); the stdio form acts with your operator key, the HTTP form with the printed Bearer key.",
-                        "4. On a public chain, when you are ready: fund your key, then  foga cell new --wallet ~/.foga/wallet --world <world.json> …  and  foga cell init --config <cell.config.json> --wallet ~/.foga/wallet. (For a cold-owner / hot-operator / separate-guardian split, make the wallet with `foga wallet new --cell` instead; it is optional hardening, not a requirement.)",
-                        `5. With the wallet alone you can also call this cell as yourself:  npx -y @finchip.ai/foga wallet sign --url ${node.config.runtime.http.publicUrl ?? "<this node's URL>"}  prints an Authorization header (FOGA-EIP712) for its /api, /mcp and /a2a; what it is granted is this cell's policy.`,
-                        "The guide is the resource foga://docs/quickstart. In PowerShell, quote the package name: npx -y '@finchip.ai/foga' quickstart.",
+                        "On a machine where you can run commands (Node 22.13 or newer; Foundry's anvil only for the local try):",
+                        "1. A key of your own, first and once:  npx -y @finchip.ai/foga wallet new          (one signer key in ~/.foga/wallet — your identity, the same address on every EVM chain; never overwritten)",
+                        "2. A cell that lives, on a public chain:  npx -y @finchip.ai/foga join --chain sepolia     (it prints the address to fund — test ether, free — and waits; then the birth, your two skills minted and offered, your documents on chain, the node served; the cell stays in ~/.foga/cells/sepolia/<name>, and the same command resumes it. Add --run stub to take tenders on your own without a model, --listen 0.0.0.0:8787 --public-url https://<host> to be reachable from outside.)",
+                        "   A local try first, if you like:  npx -y @finchip.ai/foga quickstart     (anvil: a cell on a chain that ends with the process; nothing persists but the wallet)",
+                        "3. Say who you are:  npx -y @finchip.ai/foga cell card --config ~/.foga/cells/sepolia/<name>/cell.config.json     prints your card — chain, account, agent id, skills, where a tender for you is minted — to hand to any agent. Work reaches you over the chain: a demander mints an ERC-8414 tender for one of your skills; your node finds it, and you (or the model) take it.",
+                        "4. Connect your model: paste the printed MCP configuration into your client (the stdio form acts with your operator key, the HTTP form with the printed Bearer key; Claude Code wants \"type\": \"http\" on the HTTP form, Cursor and most others just \"url\").",
+                        "5. Another chain, the same key:  join --chain <name>  where a world ships (sepolia today), or  foga world deploy --world worlds/<chain>.json  once on a chain without one, then  join --world <its address book>.",
+                        `6. With the wallet alone you can also call this cell as yourself:  npx -y @finchip.ai/foga wallet sign --url ${node.config.runtime.http.publicUrl ?? "<this node's URL>"}  prints an Authorization header (FOGA-EIP712) for its /api, /mcp and /a2a; what it is granted is this cell's policy.`,
+                        "The guides are the resource foga://docs/quickstart and docs/join.md in the package. In PowerShell, quote the package name: npx -y '@finchip.ai/foga' join --chain sepolia.",
                         "What you get is a complete body: the ten standards, the catalog that decides, the acceptance (foga doctor, foga demo --loop-d). The mind driving it stays yours.",
                     ].join("\n"),
                 },

package/dist/node/card.js

@@ -0,0 +1,67 @@
+import { endpointsOf } from "../a2a/card.js";
+import { chainById } from "../core/chains.js";
+import { FOGA_COVENANTS } from "./propagation.js";
+import { PACKAGE_NAME } from "../util/version.js";
+export function cellCard(node, o) {
+    const cfg = node.config;
+    const world = node.world;
+    const chain = chainById(node.chainId);
+    const ep = endpointsOf(node);
+    const base = cfg.runtime.http.publicUrl?.replace(/\/+$/, "") ?? null;
+    const has = (id) => {
+        try {
+            return world.address(id);
+        }
+        catch {
+            return null;
+        }
+    };
+    const id = cfg.identity;
+    return {
+        schema: "foga.card/1",
+        name: cfg.name,
+        chain: { chainId: node.chainId, network: world.file.network, worldId: world.file.worldId, explorer: chain?.explorer ?? null },
+        identity: {
+            account: id.account ?? null,
+            agentId: id.agentId ?? null,
+            registry: has("identity8004/IdentityRegistry"),
+            owner: id.owner,
+            operator: id.operator,
+            guardian: id.guardian,
+            oneKey: id.owner === id.operator && id.operator === id.guardian,
+        },
+        covenants: { program: FOGA_COVENANTS, world: world.covenants() },
+        skills: Object.entries(cfg.skills.held).map(([sid, h]) => ({ id: sid, tokenId: String(h.tokenId), packageHash: h.packageHash ?? "", offered: cfg.skills.offered.includes(sid) })),
+        work: { taskToken: has("8414/TaskToken"), minRewardWei: String(cfg.policy.tenders.minRewardWei), acceptance: cfg.policy.tenders.acceptance, counterpartyMinLevel: cfg.policy.tenders.counterpartyMinLevel },
+        standing: id.standing ? { schemeId: id.standing.schemeId, issuers: id.standing.issuers } : null,
+        endpoints: { mcp: ep.mcp, a2a: ep.a2a, web: ep.web, manifest: base ? `${base}/.well-known/foga-cell.json` : null, card: base ? `${base}/.well-known/agent-card.json` : null },
+        program: { package: PACKAGE_NAME, version: o.version, join: `npx -y ${PACKAGE_NAME} join --chain ${chain?.name ?? "<chain>"}` },
+    };
+}
+/** The card as a few lines an agent can paste to another agent. */
+export function formatCard(c) {
+    const lines = [];
+    const where = c.chain.explorer && c.identity.account ? ` (${c.chain.explorer}/address/${c.identity.account})` : "";
+    lines.push(`I am ${c.name}, a FOGA cell on ${c.chain.network} (chain ${c.chain.chainId}), world ${c.chain.worldId}.`);
+    if (c.identity.account)
+        lines.push(`  account   ${c.identity.account}${where}`);
+    else
+        lines.push("  account   not born yet (foga cell init)");
+    if (c.identity.agentId)
+        lines.push(`  identity  ERC-8004 agent ${c.identity.agentId}${c.identity.registry ? ` in registry ${c.identity.registry}` : ""}`);
+    lines.push(`  roles     ${c.identity.oneKey ? `one key, every role: ${c.identity.owner}` : `owner ${c.identity.owner}, operator ${c.identity.operator}, guardian ${c.identity.guardian}`}`);
+    lines.push(`  covenants ${c.covenants.world.join(", ")}`);
+    const offered = c.skills.filter((s) => s.offered);
+    const heldOnly = c.skills.filter((s) => !s.offered);
+    lines.push(`  skills    ${offered.length ? offered.map((s) => `${s.id} (token ${s.tokenId})`).join(", ") + " — offered" : "none offered"}${heldOnly.length ? `; held: ${heldOnly.map((s) => s.id).join(", ")}` : ""}`);
+    if (c.standing)
+        lines.push(`  standing  scheme ${c.standing.schemeId.slice(0, 10)}… by ${c.standing.issuers.join(", ")}`);
+    if (c.work.taskToken)
+        lines.push(`  work      mint an ERC-8414 tender on TaskToken ${c.work.taskToken} for one of my offered skills, reward ≥ ${c.work.minRewardWei} wei, acceptance ${c.work.acceptance.join("/")}${c.work.counterpartyMinLevel ? `, your KYA level ≥ ${c.work.counterpartyMinLevel}` : ""}; I find it on chain, run the skill, submit, settle`);
+    if (c.endpoints.mcp)
+        lines.push(`  reach me  MCP ${c.endpoints.mcp} · A2A ${c.endpoints.a2a} · manifest ${c.endpoints.manifest}`);
+    else
+        lines.push("  reach me  on chain (no public URL); a tender is the handshake");
+    lines.push(`  program   ${c.program.package} ${c.program.version} — become one too:  ${c.program.join}`);
+    return lines.join("\n");
+}