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

package/dist/cli-cell.js

@@ -6,6 +6,7 @@ import { cellInit } from "./node/init.js";
 import { KeyIsolationError, forbiddenVariables, loadOperatorKey, loadRoleKey } from "./node/keys.js";
 import { cellMigrate } from "./node/migrate.js";
 import { Node } from "./node/node.js";
+import { loadWallet, walletKey } from "./node/wallet.js";
 import { Watchers } from "./node/watchers.js";
 import { defaultCatalog, OPERATOR_CALLER, PUBLIC_CALLER } from "./tools/index.js";
 import { exists, repoRoot } from "./util/fs.js";
@@ -20,23 +21,37 @@ import { fail } from "./util/log.js";
 export const CELL_USAGE = `
   foga cell list [--public] [--as-json]          the capabilities (action, visibility, principal, modes) as the operator or as the public sees them
   foga cell schema <capability>                  the input and output JSON Schema of a capability
-  foga cell new --name <cell> --world <world.json> --store <ops.sqlite> --owner <addr> --operator <addr> --guardian <addr> --out <cell.config.json> [--rpc <url>] [--skills <dir>] [--input-dir <dir>]
-  foga cell init --config <cell.config.json> [--rpc <url>] [--capital-wei <n>]
-                                                 the cell's birth (the owner's key: FOGA_OWNER_KEY[_FILE]); writes the account, agent id, binding, record and unit into the config
+  foga cell new --name <cell> --world <world.json> --store <ops.sqlite> --out <cell.config.json> (--wallet <dir> | --owner <addr> --operator <addr> --guardian <addr>) [--rpc <url>] [--skills <dir>] [--input-dir <dir>]
+  foga cell init --config <cell.config.json> [--wallet <dir>] [--rpc <url>] [--capital-wei <n>]
+                                                 the cell's birth (the owner's key: the wallet's, or FOGA_OWNER_KEY[_FILE]); writes the account, agent id, binding, record and unit into the config
   foga cell migrate --config <cell.config.json> --to <new.config.json> [--store <new ops.sqlite>] [--operator <addr>] [--capital-wei <n>] [--no-sweep]
                                                  move the cell to a new revision-2 account (the owner's key); the new config and store are written beside
   foga cell status --config <cell.config.json>   cell_status as the operator
-  foga cell <capability> --config <cell.config.json> [--mode simulate|build|act] [--json '<input json>' | --json-file <f>] [--<field> <value> ...]
-                                                 any capability; an act loads FOGA_OPERATOR_KEY[_FILE], an admin capability FOGA_OWNER_KEY[_FILE] or FOGA_GUARDIAN_KEY[_FILE]
+  foga cell docs build --config <cell.config.json> [--rpc <url>] [--out <dir>]
+                                                 the cell's documents from its configuration and the chain (registration, AID document, ARD descriptor, AUF unit,
+                                                 agent card, server.json, manifest) under runtime.http.documentsDir — what the node serves at /documents and /.well-known
+  foga cell docs publish --config <cell.config.json> [--wallet <dir>] [--rpc <url>]
+                                                 build, then commit on chain what differs (setAgentURI, setDocumentURI, updateDescriptor, publishVersion; the operator
+                                                 key, one keyed job), then read every commitment back
+  foga cell docs status --config <cell.config.json> [--rpc <url>]   what is built, what the chain holds, what a publish would commit
+  foga cell <capability> --config <cell.config.json> [--wallet <dir>] [--mode simulate|build|act] [--json '<input json>' | --json-file <f>] [--<field> <value> ...]
+                                                 any capability; an act loads the operator key, an admin capability the owner's or the guardian's — from --wallet, or from
+                                                 FOGA_OPERATOR_KEY[_FILE], FOGA_OWNER_KEY[_FILE], FOGA_GUARDIAN_KEY[_FILE]
                                                  [--caller <id> --level read|build|act] call as another caller (what the public or an API-key holder would get)
   foga cell owner <capability> … | foga cell guardian <capability> …   the same, said explicitly
+  foga node <command> … [--wallet <dir>]         every node command takes the operator key from the wallet's operator.key (= FOGA_OPERATOR_KEY_FILE)
+  foga node preflight --config <cell.config.json> [--wallet <dir>] [--rpc <url>] [--no-executors] [--no-network] [--out <report.json>] [--strict]
+                                                 the readiness reconciliation before the public is served: the account and its allow-list, the operator key and its
+                                                 gas, the standing, the skills' packages and executors, the documents against the chain, the public URL, the model;
+                                                 advisory (exit 5 on a Fail only with --strict)
   foga node tick --config <cell.config.json>     run the watchers once (heartbeat, discovery, settlement, safety) in a node environment (operator key alone)
   foga node watch --config <cell.config.json> [--interval <s>]   run the watchers on the poll interval until stopped
   foga node mcp --config <cell.config.json>      MCP over stdio for a local client (Claude Desktop, Claude Code, Cursor): the operator's full level with
                                                  FOGA_OPERATOR_KEY[_FILE] in the environment, read and build without it; logs go to stderr
   foga node serve --config <cell.config.json> [--listen <host:port>] [--no-watch]
-                                                 the HTTP server: POST /api/<capability>, /mcp (Streamable HTTP), /healthz, / — the public reads and builds,
-                                                 a Bearer key acts as its grant says; the watchers run beside it
+                                                 host mode: POST /api/<capability>, /mcp (Streamable HTTP), /a2a (A2A 1.0), /.well-known/agent-card.json, /documents/*,
+                                                 /healthz, / — the public reads and builds, a Bearer key or a wallet signature (FOGA-EIP712) acts as its grant says;
+                                                 the watchers run beside it; no model
   foga node key new --config <cell.config.json> --id <id> [--level read|build|act] [--visibility public|caller|operator] [--note <text>]
                                                  mint an API key for the HTTP entrance: printed once, kept only as its hash in the config
   foga node run --config <cell.config.json> [--model stub|anthropic] [--listen <host:port> | --no-http] [--interval <s>] [--once | --ticks <n>] [--transcripts <dir>]
@@ -44,7 +59,7 @@ export const CELL_USAGE = `
                                                  judges) on the poll interval; the operator key alone; anthropic needs ANTHROPIC_API_KEY and runtime.model.model
 `;
 const str = (flags, key) => (typeof flags[key] === "string" ? flags[key] : undefined);
-const RESERVED = new Set(["config", "mode", "json", "json-file", "caller", "level", "rpc", "public", "help"]);
+const RESERVED = new Set(["config", "mode", "json", "json-file", "caller", "level", "rpc", "public", "help", "wallet"]);
 function inputFromFlags(flags) {
     let input = {};
     const inline = str(flags, "json");
@@ -81,7 +96,26 @@ function callerFromFlags(flags) {
         fail(`--level must be read, build, act or admin`);
     return { id: id ?? "caller", entrance: "cli", level: lvl, visibility: lvl === "admin" ? "operator" : id ? "caller" : "public" };
 }
-function keysFor(role, strict = false) {
+/** The wallet `--wallet <dir>` names, or null without the flag. */
+function walletFromFlags(flags) {
+    const dir = str(flags, "wallet");
+    if (!dir)
+        return null;
+    const w = loadWallet(resolve(dir));
+    if (!w)
+        fail(`${resolve(dir)} holds no wallet (no wallet.json); foga wallet new --dir ${resolve(dir)} makes one`);
+    return w;
+}
+/** A role's key: from the wallet when --wallet is given, from the environment otherwise. */
+function keysFor(role, strict = false, wallet = null) {
+    if (wallet) {
+        try {
+            return walletKey(wallet, role);
+        }
+        catch (e) {
+            fail(e.message);
+        }
+    }
     try {
         return (role === "operator" && strict ? loadOperatorKey() : loadRoleKey(role)).privateKey;
     }
@@ -120,7 +154,8 @@ export async function cellCommand(cmd, rest, flags) {
         return print({ name: cap.name, title: cap.title, description: cap.description, action: cap.action, visibility: cap.visibility, principal: cap.principal, ercs: cap.ercs, input: z.toJSONSchema(cap.input, { target: "draft-2020-12", io: "input" }), output: z.toJSONSchema(cap.output, { target: "draft-2020-12", io: "output" }) });
     }
     if (cmd === "new") {
-        const need = (k) => str(flags, k) ?? fail(`--${k} is required`);
+        const wallet = walletFromFlags(flags);
+        const need = (k) => str(flags, k) ?? (wallet && wallet.addresses[k] ? wallet.addresses[k] : fail(`--${k} is required (or --wallet <dir> with a ${k} key)`));
         const out = resolve(need("out"));
         if (exists(out))
             fail(`${out} exists; choose another --out (a config is never overwritten)`);
@@ -137,8 +172,9 @@ export async function cellCommand(cmd, rest, flags) {
     const configPath = str(flags, "config") ?? fail("--config <cell.config.json> is required");
     const rpc = str(flags, "rpc");
     const log = (line) => console.error(line);
+    const wallet = walletFromFlags(flags);
     if (cmd === "init") {
-        const owner = keysFor("owner");
+        const owner = keysFor("owner", false, wallet);
         const node = await Node.open({ configPath, rpc, keys: { owner }, allowUnborn: true, log });
         try {
             const capital = str(flags, "capital-wei");
@@ -151,7 +187,7 @@ export async function cellCommand(cmd, rest, flags) {
         return;
     }
     if (cmd === "migrate") {
-        const owner = keysFor("owner");
+        const owner = keysFor("owner", false, wallet);
         const to = resolve(str(flags, "to") ?? fail("--to <new.config.json> is required"));
         if (exists(to))
             fail(`${to} exists; choose another --to`);
@@ -166,6 +202,72 @@ export async function cellCommand(cmd, rest, flags) {
         }
         return;
     }
+    if (cmd === "docs") {
+        const sub = rest[0];
+        const { buildDocuments, readBack, documentsDir, onChainState, readBuilt, publishSteps } = await import("./node/documents.js");
+        const { version } = await import("./util/version.js");
+        if (sub === "build") {
+            const node = await Node.open({ configPath, rpc, keys: {}, log });
+            try {
+                const built = await buildDocuments(node, { version, dir: str(flags, "out") });
+                console.error(`documents v${built.manifest.version} written to ${built.dir}:`);
+                for (const [file, d] of Object.entries(built.manifest.documents))
+                    console.error(`  ${file.padEnd(20)} ${d.standard.padEnd(40)} ${d.contentHash}`);
+                const { steps, unchanged } = await publishSteps(node, built);
+                console.error(steps.length ? `a publish would commit: ${steps.map((x) => x.label).join("; ")}` : "every commitment on chain matches what was built");
+                if (unchanged.length)
+                    console.error(`already as built: ${unchanged.join(", ")}`);
+                print(built.manifest);
+            }
+            finally {
+                node.close();
+            }
+            return;
+        }
+        if (sub === "status") {
+            const node = await Node.open({ configPath, rpc, keys: {}, log });
+            try {
+                const dir = documentsDir(node);
+                const built = readBuilt(dir);
+                const rows = built ? await readBack(node, built) : [];
+                print({ dir, manifest: built?.manifest ?? null, onChain: await onChainState(node), readBack: rows, pending: built ? (await publishSteps(node, built)).steps.map((x) => x.label) : [] });
+                if (rows.some((r) => r.ok === false))
+                    process.exitCode = 2;
+            }
+            finally {
+                node.close();
+            }
+            return;
+        }
+        if (sub === "publish") {
+            const node = await Node.open({ configPath, rpc, keys: { operator: keysFor("operator", false, wallet) }, log });
+            try {
+                const result = await catalog.invoke(node, "docs_publish", {}, OPERATOR_CALLER, { mode: "act" });
+                if (!result.ok) {
+                    print(result);
+                    process.exitCode = 2;
+                    return;
+                }
+                const out = result.output;
+                console.error(`documents v${out.version} in ${out.dir}: ${out.committed.length ? `committed ${out.committed.join(", ")}` : "nothing to commit"}${out.unchanged.length ? `; already as built: ${out.unchanged.join(", ")}` : ""} (job ${out.jobId}, ${out.operations.length} operation(s))`);
+                // the read-back from here fetches the URLs too, when the node serves them
+                const built = readBuilt(out.dir);
+                const rows = await readBack(node, built, { fetchUrls: true });
+                for (const r of rows)
+                    console.error(`  ${r.ok === true ? "ok     " : r.ok === false ? "FAIL   " : "unread "} ${r.commitment.padEnd(26)} ${r.detail}`);
+                print({ ...out, readBack: rows });
+                if (rows.some((r) => r.ok === false)) {
+                    console.error("a commitment read back from the chain does not match what was built: the publish is not complete");
+                    process.exitCode = 2;
+                }
+            }
+            finally {
+                node.close();
+            }
+            return;
+        }
+        fail("foga cell docs build | publish | status");
+    }
     // a capability, possibly said as "owner <capability>" / "guardian <capability>"
     let name = cmd;
     let explicitRole = null;
@@ -186,10 +288,10 @@ export async function cellCommand(cmd, rest, flags) {
     if (cap.action !== "read" && mode === "act") {
         if (cap.action === "admin") {
             const role = cap.signer ?? explicitRole ?? "owner";
-            keys[role] = keysFor(role);
+            keys[role] = keysFor(role, false, wallet);
         }
         else
-            keys.operator = keysFor("operator");
+            keys.operator = keysFor("operator", false, wallet);
     }
     const node = await Node.open({ configPath, rpc, keys, log });
     try {
@@ -230,6 +332,32 @@ export async function nodeCommand(cmd, rest, flags) {
     }
     const configPath = str(flags, "config") ?? fail("--config <cell.config.json> is required");
     const log = (line) => console.error(line);
+    // --wallet <dir>: the operator key file of the wallet, as FOGA_OPERATOR_KEY_FILE would name it; never beside another key source
+    const wallet = walletFromFlags(flags);
+    if (wallet) {
+        if (process.env.FOGA_OPERATOR_KEY || process.env.FOGA_OPERATOR_KEY_FILE)
+            fail("--wallet and FOGA_OPERATOR_KEY[_FILE] are both set; a node takes its operator key from one place");
+        if (!wallet.files.operator)
+            fail(`wallet ${wallet.dir} has no operator key`);
+        process.env.FOGA_OPERATOR_KEY_FILE = wallet.files.operator;
+    }
+    if (cmd === "preflight") {
+        const { preflight, printPreflight } = await import("./node/preflight.js");
+        const { writeJson } = await import("./util/fs.js");
+        const node = await Node.open({ configPath, rpc: str(flags, "rpc"), keys: {}, log });
+        try {
+            const report = await preflight(node, { executors: !flags["no-executors"], network: !flags["no-network"] });
+            printPreflight(report, (line) => console.log(line));
+            if (str(flags, "out"))
+                writeJson(resolve(str(flags, "out")), report);
+            if (flags.strict && report.summary.Fail > 0)
+                process.exitCode = 5;
+        }
+        finally {
+            node.close();
+        }
+        return;
+    }
     if (cmd === "key") {
         if (rest[0] !== "new")
             fail("foga node key new --config <cfg> --id <id> [--level act] [--visibility caller]");
@@ -281,7 +409,10 @@ export async function nodeCommand(cmd, rest, flags) {
         const { version } = await import("./util/version.js");
         const listen = str(flags, "listen") ?? node.config.runtime.http.listen;
         const running = await createHttpServer({ node, catalog, version, log }).listen(listen);
-        log(`foga ${version}: serving cell ${node.config.name}${node.cell ? ` (${node.cell.address})` : ""} at ${running.url} — /mcp, /api/<capability>, /healthz; ${keys.operator ? "acting with the operator key" : "no operator key: reads and builds only"}; ${node.config.access.keys.length} API key(s) configured`);
+        const { documentsDir, readBuilt } = await import("./node/documents.js");
+        const built = readBuilt(documentsDir(node));
+        const signers = node.config.access.signers;
+        log(`foga ${version}: serving cell ${node.config.name}${node.cell ? ` (${node.cell.address})` : ""} at ${running.url} — /mcp, /api/<capability>, /a2a, /.well-known/agent-card.json, /documents/*, /healthz; ${keys.operator ? "acting with the operator key" : "no operator key: reads and builds only"}; ${node.config.access.keys.length} API key(s) configured; signatures: ${signers.default} by default, ${signers.allow.length} allowed${signers.standing ? `, standing level ${signers.standing.minLevel}+ granted ${signers.standing.level}` : ""}; documents ${built ? `v${built.manifest.version}` : "not built (foga cell docs build)"}`);
         const stopWatch = !flags["no-watch"] && keys.operator && node.cell ? startWatchLoop(new Watchers(node, catalog), node.config.runtime.pollSeconds * 1000, log) : () => { };
         const stop = () => {
             stopWatch();
@@ -363,7 +494,7 @@ export async function nodeCommand(cmd, rest, flags) {
         return;
     }
     if (cmd !== "tick" && cmd !== "watch")
-        fail(`unknown node command ${cmd}; tick, watch, mcp, serve, run or key`);
+        fail(`unknown node command ${cmd}; tick, watch, mcp, serve, run, preflight or key`);
     // a node environment: the operator key alone, nothing that derives another role
     const operator = keysFor("operator", true);
     const node = await Node.open({ configPath, rpc: str(flags, "rpc"), keys: { operator }, log });

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { cpus, homedir, loadavg } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
 import { buildBundle } from "./build/bundle.js";
@@ -21,6 +21,16 @@ usage:
                                                  deploy-mode config: the whole stack; attach-mode config: attach what it
                                                  lists and deploy the reference contracts it does not (deployer = W)
   foga world attach --world <config.json> [--out <file>]   address book only, no transactions (every contract listed)
+  foga world verify --world <world.json> --sourcify [--dry-run] [--only <id,id>] [--server <url>] [--out <dir>] [--build-info <dir>]
+                                                 submit every contract the world deployed from the bundle to Sourcify, with the standard JSON input of its
+                                                 compiler run (.foga-build/out/<repo>/build-info, written by npm run bundle:verify); a local chain is a dry run
+  foga wallet new [--name <n> | --dir <dir>] [--single]   the first step: a wallet of your own — owner, operator and guardian keys in 0600 files
+                                                 (default ~/.foga/wallet; --name under ~/.foga/wallets/<n>; --single: one signer key). Never overwrites; prints the addresses
+  foga wallet show [--name <n> | --dir <dir>] [--rpc <url>]   the wallet's addresses (and balances with an RPC)
+  foga wallet sign (--config <cell.config.json> | --url <node url> | --cell <account> --chain-id <n>) [--name <n> | --dir <dir>]
+                   [--role signer|operator|owner|guardian] [--ttl <s>] [--agent-id <id>] [--method <METHOD> --path <path> [--body '<json>' | --body-file <f>]]
+                                                 an Authorization header (FOGA-EIP712) proving the wallet to that cell — named by its configuration, by its node's
+                                                 URL (/healthz says which account and chain) or by hand: a session envelope, or one bound to a request
   foga keys new [--out <file>]                   write a fresh 12-word phrase (default ~/.foga/genesis.mnemonic) and print the role addresses
   foga keys show                                 print the role addresses the environment derives (FOGA_MNEMONIC[_FILE], FOGA_KEY_*)
   foga keys export --role <role> [--out <file>]  write one role's key to a 0600 file for a node that holds that key alone
@@ -38,9 +48,10 @@ usage:
                    [--zk auto|require|skip] [--crash-after <opKey>] [--crash-before <opKey>]
                                                  run the genesis scenario (idempotent; re-run to resume)
   foga genesis status --world <world.json> [--store <file.sqlite>]    list the operations the store holds
-  foga quickstart [--dir <dir>] [--port <n>] [--listen <host:port> | --no-serve] [--name <cell>] [--no-tenders] [--exit]
-                                                 one command to a live cell: anvil, the local world, a cell born with fresh 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 quickstart [--dir <dir>] [--wallet <dir>] [--port <n>] [--listen <host:port> | --no-serve] [--name <cell>] [--no-tenders] [--exit]
+                                                 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 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
@@ -149,6 +160,21 @@ async function main() {
         }
         return;
     }
+    if (group === "world" && cmd === "verify") {
+        if (!flags.sourcify)
+            fail("foga world verify --sourcify --world <world.json> (Sourcify is the one verifier wired so far)");
+        const worldPath = str(flags, "world") ?? fail("--world <world.json> is required (a deployed world)");
+        const { verifyWorld } = await import("./world/sourcify.js");
+        const { report, outDir } = await verifyWorld({ worldPath: resolve(worldPath), server: str(flags, "server"), dryRun: flags["dry-run"] ? true : undefined, only: str(flags, "only")?.split(","), outDir: str(flags, "out") ? resolve(str(flags, "out")) : undefined, buildInfoRoot: str(flags, "build-info") ? resolve(str(flags, "build-info")) : undefined, log: (line) => console.error(line) });
+        for (const r of report.results)
+            console.log(`  ${r.outcome.padEnd(12)} ${r.id.padEnd(32)} ${r.address}  ${r.contractIdentifier} (${r.compilerVersion})${r.outcome === "dry-run" ? "" : `  ${r.detail}`}`);
+        for (const m of report.missing)
+            console.log(`  missing      ${m.id.padEnd(32)} ${m.reason}`);
+        console.log(`sourcify: ${Object.entries(report.summary).map(([k, v]) => `${v} ${k}`).join(", ") || "nothing to do"}${report.missing.length ? `, ${report.missing.length} missing` : ""}; report ${relative(root, join(outDir, "report.json"))}`);
+        if (report.missing.length || report.results.some((r) => r.outcome === "failed" || r.outcome === "error"))
+            process.exitCode = 3;
+        return;
+    }
     if (group === "world" && (cmd === "deploy" || cmd === "attach")) {
         const worldConfigPath = str(flags, "world");
         if (!worldConfigPath)
@@ -217,6 +243,113 @@ async function main() {
         process.stdout.write(RELAY_SCRIPT);
         return;
     }
+    if (group === "wallet") {
+        const { createWallet, loadWallet, walletDir, walletFileProblems } = await import("./node/wallet.js");
+        const dir = resolve(str(flags, "dir") ?? walletDir(str(flags, "name")));
+        const printWallet = async (w, made) => {
+            console.log(`${made ? "wallet made at" : "wallet"} ${w.dir}${w.name !== "default" ? ` (${w.name})` : ""}, ${w.createdAt}`);
+            const rpc = str(flags, "rpc") ?? process.env.FOGA_RPC_URL;
+            const provider = rpc ? new (await import("ethers")).JsonRpcProvider(rpc) : null;
+            for (const role of w.roles) {
+                let balance = "";
+                if (provider) {
+                    try {
+                        balance = `   ${(await import("ethers")).formatEther(await provider.getBalance(w.addresses[role]))} ETH`;
+                    }
+                    catch {
+                        balance = "   (balance: RPC did not answer)";
+                    }
+                }
+                console.log(`  ${role.padEnd(9)} ${w.addresses[role]}${balance}   ${w.files[role]}`);
+            }
+            provider?.destroy();
+            for (const p of walletFileProblems(w))
+                log.warn(p);
+            if (w.roles.includes("owner"))
+                console.log(`fund the owner for a cell's birth (capital and gas) and the operator for its gas; then: foga cell new --wallet ${dir} … and foga cell init --config <cfg> --wallet ${dir}`);
+        };
+        if (cmd === "new") {
+            const existing = loadWallet(dir);
+            if (existing) {
+                await printWallet(existing, false);
+                console.log("(already there; a wallet is never overwritten — foga wallet new --name <n> makes another)");
+                return;
+            }
+            try {
+                await printWallet(createWallet(dir, { name: str(flags, "name") ?? "default", roles: flags.single ? ["signer"] : undefined }), true);
+            }
+            catch (e) {
+                fail(e.message);
+            }
+            return;
+        }
+        if (cmd === "show") {
+            const w = loadWallet(dir);
+            if (!w)
+                fail(`no wallet at ${dir}; foga wallet new makes one`);
+            await printWallet(w, false);
+            return;
+        }
+        if (cmd === "sign") {
+            const w = loadWallet(dir);
+            if (!w)
+                fail(`no wallet at ${dir}; foga wallet new makes one`);
+            const { walletKey } = await import("./node/wallet.js");
+            const { loadCellConfig, configPath } = await import("./node/config.js");
+            const { signAuthorization } = await import("./http/signed.js");
+            const { Wallet } = await import("ethers");
+            // the cell the signature is for: its own configuration (the operator's shell), its node's URL (anyone's: /healthz names the account and the chain), or both values by hand
+            let cellAddress;
+            let chainId;
+            let cellName;
+            if (str(flags, "config")) {
+                const loaded = loadCellConfig(str(flags, "config"));
+                cellAddress = loaded.config.identity.account ?? fail("the config names no account yet (the cell is not born)");
+                chainId = readJson(configPath(loaded, loaded.config.world)).chainId;
+                cellName = loaded.config.name;
+            }
+            else if (str(flags, "url")) {
+                const base = str(flags, "url").replace(/\/+$/, "");
+                let health;
+                try {
+                    health = (await (await fetch(`${base}/healthz`, { signal: AbortSignal.timeout(10_000) })).json());
+                }
+                catch (e) {
+                    fail(`${base}/healthz did not answer: ${e.message}`);
+                }
+                if (!health.account || !health.chainId)
+                    fail(`${base}/healthz names no account or chain (${JSON.stringify(health).slice(0, 200)}); the cell is not born or this is not a FOGA node`);
+                cellAddress = health.account;
+                chainId = health.chainId;
+                cellName = health.cell ?? base;
+            }
+            else if (str(flags, "cell") && str(flags, "chain-id")) {
+                cellAddress = str(flags, "cell");
+                chainId = Number(str(flags, "chain-id"));
+                cellName = cellAddress;
+            }
+            else
+                fail("the signature is made for one cell: --config <cell.config.json>, or --url <its node's URL>, or --cell <account> --chain-id <n>");
+            const role = (str(flags, "role") ?? (w.roles.includes("signer") ? "signer" : "operator"));
+            let key;
+            try {
+                key = walletKey(w, role);
+            }
+            catch (e) {
+                fail(e.message);
+            }
+            const method = str(flags, "method");
+            const path = str(flags, "path");
+            if ((method && !path) || (!method && path))
+                fail("--method and --path go together");
+            const bodyText = str(flags, "body") ?? (str(flags, "body-file") ? readFileSync(resolve(str(flags, "body-file")), "utf8") : undefined);
+            const header = await signAuthorization(new Wallet(key), { chainId, cell: cellAddress, ttlSeconds: str(flags, "ttl") ? Number(str(flags, "ttl")) : undefined, agentId: str(flags, "agent-id"), request: method ? { method, path: path, body: bodyText ?? null } : undefined });
+            console.error(`${role} ${new Wallet(key).address} signed ${method ? `a ${method} ${path} envelope` : "a session envelope"} for cell ${cellName} (${cellAddress}, chain ${chainId}); the header value follows (one line):`);
+            console.log(header);
+            return;
+        }
+        fail("foga wallet new | show | sign");
+    }
     if (group === "keys" && cmd === "export") {
         const { ROLE_ORDER, envKeys, roleAddresses } = await import("./genesis/roles.js");
         const role = str(flags, "role");
@@ -362,7 +495,7 @@ async function main() {
         const { runQuickstart } = await import("./demo/quickstart.js");
         let result;
         try {
-            result = await runQuickstart({ dir: str(flags, "dir"), port: str(flags, "port") ? Number(str(flags, "port")) : undefined, listen: flags["no-serve"] ? null : str(flags, "listen"), name: str(flags, "name"), tenders: !flags["no-tenders"], exit: Boolean(flags.exit) });
+            result = await runQuickstart({ dir: str(flags, "dir"), wallet: str(flags, "wallet"), port: str(flags, "port") ? Number(str(flags, "port")) : undefined, listen: flags["no-serve"] ? null : str(flags, "listen"), name: str(flags, "name"), tenders: !flags["no-tenders"], exit: Boolean(flags.exit) });
         }
         catch (e) {
             fail(e.message);

package/dist/demo/birth.js

@@ -12,10 +12,10 @@ export async function birthCell(o) {
     const log = o.log ?? (() => { });
     const root = repoRoot();
     const W = k.address("W");
-    const owner = Wallet.createRandom();
-    const operator = Wallet.createRandom();
-    const guardian = Wallet.createRandom();
-    log(`cell ${o.name}: owner ${owner.address}, operator ${operator.address}, guardian ${guardian.address}`);
+    const owner = o.keys ? new Wallet(o.keys.owner) : Wallet.createRandom();
+    const operator = o.keys ? new Wallet(o.keys.operator) : Wallet.createRandom();
+    const guardian = o.keys ? new Wallet(o.keys.guardian) : Wallet.createRandom();
+    log(`cell ${o.name}: owner ${owner.address}, operator ${operator.address}, guardian ${guardian.address}${o.keys ? " (the wallet's keys)" : " (fresh keys)"}`);
     // --- funding by W, the standing scheme registered by W
     const price = (await k.world.provider.getFeeData()).gasPrice ?? 1000000000n;
     const gas = (units) => units * price * 2n;

package/dist/demo/quickstart.js

@@ -1,12 +1,15 @@
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+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";
@@ -49,6 +52,12 @@ export async function runQuickstart(o = {}) {
     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);
@@ -62,6 +71,8 @@ export async function runQuickstart(o = {}) {
         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))
@@ -74,6 +85,12 @@ export async function runQuickstart(o = {}) {
     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") });
@@ -106,6 +123,7 @@ export async function runQuickstart(o = {}) {
                 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 };
@@ -113,6 +131,8 @@ export async function runQuickstart(o = {}) {
                     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;
                 },
             });
         }
@@ -121,13 +141,16 @@ export async function runQuickstart(o = {}) {
             k.world.provider.destroy();
         }
         const configPath = cell.configPath;
-        // --- the keys, each in its own 0600 file (anvil money; nothing of value), and an act-level API key for the HTTP entrance
+        // --- 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 = { owner: keyFile("owner.key", cell.owner.privateKey), operator: keyFile("operator.key", cell.operator.privateKey), guardian: keyFile("guardian.key", cell.guardian.privateKey) };
+        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);
@@ -135,6 +158,23 @@ export async function runQuickstart(o = {}) {
             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) {
@@ -177,7 +217,15 @@ export async function runQuickstart(o = {}) {
             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`);
-            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`);
+            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 }));
@@ -197,12 +245,14 @@ export async function runQuickstart(o = {}) {
         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})` : ""}; owner, operator and guardian keys in ${keysDir} (anvil money, no value)`);
+        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>, /healthz; its watchers settle and withdraw what the cell commits to`);
+            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):");
@@ -217,6 +267,8 @@ export async function runQuickstart(o = {}) {
             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}\\"}"`);
@@ -231,7 +283,7 @@ export async function runQuickstart(o = {}) {
         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, nodeUrl, tenders: minted.map((c) => c.tokenId), anvil: version }, null, 2) + "\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,
@@ -242,6 +294,7 @@ export async function runQuickstart(o = {}) {
             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,