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

package/README.md

@@ -19,7 +19,11 @@ ERC-8004 (Trustless Agents) is a required dependency: ERC-8419, ERC-8434 and ERC
 
 The project delivers three things from one kernel: the **Finch OG Agent** (the first running instance), the **FOGA node software** anyone can run with their own identity, model and wallet, and a **public access layer** (MCP, A2A, HTTP/CLI). It is built in phases; this repository has completed **Phase 2c: the genesis on a public chain**, on top of the Phase 2 genesis (T0–T9) and the Phase 1 world layer.
 
-## Status: Phase 3d in progress — 3d-1 done (quickstart, an outside agent's Loop D); Phase 3c done — Loop D, the unscripted run; Phase 3b done — the node served over MCP and HTTP; Phase 3a done — the kernel hardened and turned into a node with a capability catalog; Phase 2c done
+## Status: Phase 3 done (0.6.0, 2026-11-05) — the OG live at foga.finchip.ai, the MCP registry listing, the Sepolia Loop D with an outside agent; 3d-2 (the wallet, signed callers, the documents on chain, preflight, A2A, Sourcify), 3d-1 (quickstart, an outside agent's Loop D), 3c (Loop D with a model), 3b (MCP and HTTP), 3a (the kernel as a node) all done
+
+**3d-3 (0.6.0, 2026-11-05).** Phase 3 closes with the reference cell served and the last acceptance run on the public chain. The OG was born fresh on Sepolia by the path any cell takes (`wallet new`, `cell new`, `cell init`, `docs publish`, `node serve` — one key, no migration; docs/og-deployment.md): agent 11261, its skill offered, its documents on chain, its fifteen contracts Sourcify-verified; it is served in host mode under systemd behind Caddy at `foga.finchip.ai` and listed in the MCP registry as `io.github.garyyang-finchip/foga`. Loop D with an outside agent ran on Sepolia and every invariant row passed (docs/loop-d.md, "On a public chain"); what the public chain taught is fixed in this release — a working directory is one run, role funding is priced with a floor, the settlement figure is the tender's own, a log scan is windowed. `foga cell advise` (`src/node/advise.ts`) tells a running cell what to do next — separate the one key into owner, operator and guardian first — and the recommended items print after a quickstart, a birth and at serve; the first run stays minimal on purpose. The covenant list is read off the world (an eleventh covenant appears with no code change) and the manifest carries a `services` slot — the maintainer's catalog, declinable, served by the reference cell at `/services.json` — docs/extending.md. 107 tests.
+
+**3d-2 (0.6.0-alpha.7, 2026-11-03).** The second slice of 3d is what a cell needs to stand on its own among other agents, under one principle (docs/design-memo.md, section 10): the wallet is the first step, made by default and never a reason to stop; identity is one's own; only the genome replicates. `foga wallet new` (`src/node/wallet.ts`, docs/wallet.md) makes an agent's keys on its own machine — by default one key in a 0600 file under `~/.foga/wallet` — the identity that fills every role a cell needs; `--cell` for the separated owner/operator/guardian set — never overwritten, no network — and `foga quickstart` makes the default wallet on its first run and births every later cell with the same keys; `--wallet <dir>` on every `foga cell` and `foga node` command takes a role's key from there. A wallet is also a credential: `Authorization: FOGA-EIP712 <envelope>` (`src/http/signed.ts`, `src/http/access.ts`) is an EIP-712 signature in the cell's own domain — bound to one request and good once, or a session for a client with static headers — and the caller is the signing address at the level `access.signers` grants it (the cell's own operator or owner, an allow-list by address or ERC-8004 agent id, a KYA standing threshold, a default); `/api`, `/mcp` and `/a2a` take it, `foga wallet sign` prints it, and every cell's MCP server carries the prompt `become-a-cell` and the resource `foga://docs/quickstart` for an agent that meets it. `foga cell docs build | publish | status` (`src/node/documents.ts`, docs/documents.md) generates the cell's documents from one configuration — the ERC-8004 registration, the ERC-8434 AID document, the ERC-8444 descriptor, the ERC-8454 unit, the A2A agent card, `server.json`, a manifest with content hashes — serves them at `/documents/*` and `/.well-known/*`, and commits them on chain as the operator's keyed job (`setAgentURI`, `setDocumentURI`, `updateDescriptor`, `publishVersion`; only what differs is sent), read back and cross-checked; `docs_status` and `docs_publish` are the catalog's 30th and 31st capabilities. `foga node preflight` (`src/node/preflight.ts`) is the readiness reconciliation — the world, the account and its allow-list, the budget, the keys, the standing, the skills run in the worker, the documents against the chain, the public URL, the model — advisory, `--strict` for CI. `POST /a2a` (`src/a2a/`, docs/a2a.md) is the A2A 1.0 JSON-RPC binding with the card at `/.well-known/agent-card.json`: a quote for anyone, a tender taken for an act-level caller as one task over the catalog's jobs, `GetTask`, `ListTasks`, `CancelTask`, errors by the specification. `foga world verify --sourcify` (`src/world/sourcify.ts`, docs/world.md) submits every FOGA-deployed contract of a world with the standard JSON input of its own compiler run (`forge build` now leaves the build-info beside the artifacts), matched by runtime code; a local chain is a dry run, which CI runs over all 47. The OG instance's default is host mode (`foga node serve`: every entrance, the watchers, no model) with embedded mode (`foga node run`, the runner with a model) on demand. Seven new tests on anvil and offline (`wallet`, `signed`, `documents`, `a2a`, `preflight`, `sourcify`, and `quickstart` extended) are the gate; `foga quickstart` now ends with a cell whose documents are on chain, whose card answers, and whose A2A entrance quotes. Next, 3d-3: the OG deployment runbook, `foga.finchip.ai`, the registry listing, the Sepolia Sourcify run, the OG cell's migration to revision 2 and an outside agent's Loop D on Sepolia.
 
 **3d-1 (0.6.0-alpha.6, 2026-11-02).** The package is on npm as `@finchip.ai/foga` (0.6.0-alpha.4 and alpha.5, the latter with the launcher fixed for Windows), so the first slice of 3d is the two things that make it usable from nothing. `foga quickstart` (`src/demo/quickstart.ts`, docs/quickstart.md) is one command to a live cell: anvil, the local world, a cell born with keys nobody held and its two skills, two tenders minted for it, the node served (watchers, HTTP API, MCP over Streamable HTTP), both entrances checked (the handshake and tool list over HTTP with an act-level key, and over stdio with the operator key), and the MCP client configurations — Claude Desktop, Claude Code, Cursor, and the HTTP form with URL and Bearer key — printed and written with every path filled in, under `~/.foga/quickstart`. Loop D gains `--model external` (docs/loop-d.md): the node is served instead of run, an act-level key is minted for whoever proposes, the orchestrator prints a brief (the entrance, the five steps of a tender, what the run does around the agent — nothing about the cases) and waits for the agent — any model, any runtime, a person with `curl` — with the same recovery drill, the same entrance checks and the same acceptance; the evidence names the agent and carries no runner ticks, the doctor marks a case the agent left alone `NotTested` rather than `Fail`, and `--compare` skips what one run did not reach. `test/loop-d-external.test.ts` drives it with a scripted agent through the MCP entrance and every verdict passes, the model-agnostic row included against the kept stub run. Smaller: `.gitattributes` keeps every text file LF (the launcher's shebang included), a `prepare` script compiles a checkout installed straight from git, the shared cell birth (`src/demo/birth.ts`) and anvil helpers (`src/demo/anvil.ts`) serve the demos, and the docs carry the PowerShell and Windows notes. Next in 3d: `foga node preflight`, `docs build/publish` with `setAgentURI`, the A2A card and inbound mapping, Sourcify, then the OG deployment runbook, the documentation site and the registry listing.
 
@@ -72,16 +76,26 @@ From Phase 1, unchanged in substance:
 - **The doctor.** `foga doctor` reports five layers per contract — chain and code, interfaces, version match, configuration and permissions, semantic validation — with the verdicts Pass / Fail / Unknown / Not tested / Not applicable. Layers 1–4 probe the chain; layer 5 reads the genesis evidence. A doctor run can be exported as a JSON-RPC probe plan and replayed from results collected elsewhere, so a report never depends on which machine can reach which RPC.
 - **Sepolia address book.** `worlds/sepolia.json` records every upstream reference deployment at its deployed revision, including the three seams the inventory found (docs/version-lock.md); the completed world and the doctor's report on it are the 2c files above.
 
-What is next: the rest of 3d closes Phase 3 — the readiness check, the documents on chain, A2A, Sourcify, the OG instance's move to a revision-2 account with public endpoints, the registry listing and an outside agent's Loop D run on Sepolia; Phase 4 the hosted node and payments. The design is in docs/design-memo.md.
+What is next: 3d-3 closes Phase 3 — the OG instance's move to a revision-2 account with public endpoints (`foga.finchip.ai`), its documents and sources verified on Sepolia, the registry listing and an outside agent's Loop D run on Sepolia; Phase 4 the hosted node and payments. The design is in docs/design-memo.md.
 
 ## Quick start
 
-With Node 22.13+ and Foundry's `anvil` installed, one command births a cell on a local chain and prints the MCP client configuration to connect to it (docs/quickstart.md; in PowerShell quote the name: `npx -y '@finchip.ai/foga' quickstart`):
+With Node 22.13+ and Foundry's `anvil` installed, one command makes your wallet (on the first run; `~/.foga/wallet`, reused after), births a cell with it on a local chain, publishes the cell's documents and prints the MCP client configuration to connect to it (docs/quickstart.md; in PowerShell quote the name: `npx -y '@finchip.ai/foga' quickstart`):
 
 ```bash
 npx -y @finchip.ai/foga quickstart
 ```
 
+The wallet alone, for an agent that will only call cells (docs/wallet.md), and a cell on a public chain born with it:
+
+```bash
+npx -y @finchip.ai/foga wallet new                       # ~/.foga/wallet: one key (your identity, every role); prints the address to fund. --cell for the separated owner/operator/guardian set
+foga cell new --wallet ~/.foga/wallet --name mine --world deployments/sepolia.json --store mine.sqlite --out mine.json
+foga cell init --config mine.json --wallet ~/.foga/wallet
+foga node preflight --config mine.json --wallet ~/.foga/wallet
+foga node serve --config mine.json --wallet ~/.foga/wallet
+```
+
 From a checkout, three ways in, from most to least demanding:
 
 ```bash
@@ -164,18 +178,20 @@ deployments/         world files, doctor reports, genesis evidence (local output
 prover/              the ZK proving sub-package: run.cjs bridge (credential and predicate proofs), build-predicate.mjs (the development ceremony), its own dependencies
 zk/                  circuits/ (kya_predicate_count_v1.circom) and build/ (verification_key.json committed; the proving key is rebuilt locally)
 docker/, docker-compose.yml
-docs/                design memo, compatibility matrix, version lock, build, world, doctor, cell account, kernel, genesis, zk, node, mcp, loop-d; examples/ (client configurations)
+deploy/              the OG host assets: foga-og.service (systemd, host mode), Caddyfile, og.env.example (docs/og-deployment.md)
+site/                 the documentation site for GitHub Pages (docs.foga.finchip.ai): index.html, llms.txt, CNAME
+docs/                design memo, compatibility matrix, version lock, build, world, doctor, cell account, kernel, genesis, zk, node, mcp, loop-d, quickstart, wallet, documents, a2a, og-deployment; examples/ (client configurations)
 scenarios/skills/    the two ERC-8338 skill packages of the genesis: foga-probe, finch-extract-verify
 scenarios/fixtures/  the pinned document finch-extract-verify works on in T5 and T7
 scripts/             install-solc.sh, install-foundry.sh, relay.mjs, pack-smoke.mjs (the npm tarball run from a clean install)
 src/                 TypeScript: build/ (vendor + bundle), world/ (plan + deploy), doctor/ (probe + evaluate),
                      core/ (foga-core: one module per ERC incl. acdf, adrf and swarm, measure, canonicalization, DAG-CBOR packager),
                      kernel/ (store, transaction manager, cell, kernel), genesis/ (roles, operator scope, probe, extract, skill worker, zk, scenario T0-T3, t3-zk, t4..t9, runner),
-                     tools/ (the capability catalog: types, catalog, read, tenders, identity, admin), node/ (config, keys, node, policy, init, migrate, watchers),
-                     mcp/ (the MCP server built from the catalog), http/ (the HTTP API, MCP over Streamable HTTP, API keys),
-                     node/runner.ts and node/model/ (the runner, the stub and anthropic adapters), demo/ (the Loop D demander, orchestration and evidence),
+                     tools/ (the capability catalog: types, catalog, read, tenders, identity, documents, admin), node/ (config, keys, wallet, node, policy, init, migrate, watchers, documents, preflight),
+                     mcp/ (the MCP server built from the catalog), http/ (the HTTP API, MCP over Streamable HTTP, API keys, signed callers), a2a/ (the A2A 1.0 binding and card),
+                     node/runner.ts and node/model/ (the runner, the stub and anthropic adapters), demo/ (the Loop D demander, orchestration and evidence, quickstart), world/sourcify.ts,
                      cli.ts, cli-cell.ts (foga cell / foga node)
-test/                unit tests: bytecode and interface ids, skill packages, canonicalization, operation store, transaction semantics against an in-process chain (mock-chain.ts), keys, policy gates, catalog, cell config, swarm/ACDF vectors, extractor, measurement resolver, doctor layer 5; node-cli.test.ts (the Loop D cases through the CLI on anvil), mcp.test.ts (the entrances over MCP and HTTP on anvil; helpers/anvil-cell.ts births the cell), model.test.ts (the stub's table, the Anthropic adapter against a stand-in API, the Loop D verdicts), loop-d.test.ts (the unscripted run with the stub on anvil)
+test/                unit tests: bytecode and interface ids, skill packages, canonicalization, operation store, transaction semantics against an in-process chain (mock-chain.ts), keys, policy gates, catalog, cell config, swarm/ACDF vectors, extractor, measurement resolver, doctor layer 5, sourcify; node-cli.test.ts (the Loop D cases through the CLI on anvil), mcp.test.ts (the entrances over MCP and HTTP on anvil; helpers/anvil-cell.ts births the cell), model.test.ts (the stub's table, the Anthropic adapter against a stand-in API, the Loop D verdicts), loop-d.test.ts (the unscripted run with the stub on anvil), loop-d-external.test.ts, quickstart.test.ts, wallet.test.ts, signed.test.ts, documents.test.ts, a2a.test.ts, preflight.test.ts (3d, on anvil)
 vendor/              LOCK.json (sources are materialized here and gitignored)
 worlds/              world configs: local.json (deploy), sepolia.json (attach)
 ```
@@ -188,27 +204,32 @@ foga build [--verify] [--solc-dir <dir>] [--only <repo,repo>]
 foga bundle info
 foga world deploy --world <config> [--rpc <url>] [--out <file>] [--resume] [--gas-multiplier <x>] [--allow-chain-mismatch]
 foga world attach --world <config> [--out <file>]
+foga world verify --world <world.json> --sourcify [--dry-run] [--only <id,id>] [--server <url>] [--out <dir>] [--build-info <dir>]   source verification from the bundle's own compiler runs
 foga doctor --world <world|config> [--attach] [--rpc <url>] [--out <report>] [--export-probe <file>] [--import-results <file>] [--genesis <evidence>]
 foga probe relay-script
 foga genesis run --world <world> [--rpc <url>] [--until T0..T9] [--store <file>] [--out <evidence>] [--zk auto|require|skip] [--crash-after <key>] [--crash-before <key>]
 foga genesis status --world <world> [--store <file>]
 foga keys new [--out <file>] | show | export --role <role> [--out <file>] | check
+foga wallet new [--name <n> | --dir <dir>] [--cell] | show [--rpc <url>] | sign (--config <cfg> | --url <node> | --cell <acct> --chain-id <n>) [--role] [--ttl <s>] [--agent-id <id>] [--method --path [--body]]
+                                                                          an agent's own key (the first step; --cell for the separated owner/operator/guardian set), and a signed Authorization header for a cell
 foga demo [--port <n>] [--keep] [--genesis <T0..T9>]
 foga cell list [--public] | schema <capability>
-foga cell new --name <cell> --world <world.json> --store <ops.sqlite> --owner <addr> --operator <addr> --guardian <addr> --out <cell.config.json>
-foga cell init --config <cell.config.json> [--capital-wei <n>]          (owner key)
+foga cell new --name <cell> --world <world.json> --store <ops.sqlite> --out <cell.config.json> (--wallet <dir> | --owner <addr> --operator <addr> --guardian <addr>)
+foga cell init --config <cell.config.json> [--wallet <dir>] [--capital-wei <n>]          (owner key)
 foga cell migrate --config <cell.config.json> --to <new.config.json> [--operator <addr>]   (owner key)
-foga cell <capability> --config <cell.config.json> [--mode simulate|build|act] [--<field> <value> ...] [--json '<input>']
+foga cell docs build | publish | status --config <cell.config.json> [--wallet <dir>]     the cell's documents, served and committed on chain (publish: operator key)
+foga cell <capability> --config <cell.config.json> [--wallet <dir>] [--mode simulate|build|act] [--<field> <value> ...] [--json '<input>']
+foga node preflight --config <cell.config.json> [--wallet <dir>] [--no-executors] [--no-network] [--out <report.json>] [--strict]   the readiness reconciliation; sends nothing
 foga node tick | watch --config <cell.config.json> [--interval <s>]      (operator key alone)
-foga node mcp --config <cell.config.json>                                 MCP over stdio (= foga mcp; the operator with FOGA_OPERATOR_KEY[_FILE], reads and builds without)
-foga node serve --config <cell.config.json> [--listen <host:port>] [--no-watch]   the HTTP API, /mcp over Streamable HTTP, /healthz, the watchers
+foga node mcp --config <cell.config.json>                                 MCP over stdio (= foga mcp; the operator with FOGA_OPERATOR_KEY[_FILE] or --wallet, reads and builds without)
+foga node serve --config <cell.config.json> [--listen <host:port>] [--no-watch]   host mode: the HTTP API, /mcp, /a2a, the documents, /healthz, the watchers; no model
 foga node key new --config <cell.config.json> --id <id> [--level read|build|act] [--visibility public|caller|operator] [--note <text>]
 foga node run --config <cell.config.json> [--model stub|anthropic] [--listen <host:port> | --no-http] [--interval <s>] [--once | --ticks <n>] [--transcripts <dir>]
                                                                           the embedded node: server, watchers and the runner (operator key alone)
 foga demo --loop-d [--model stub|anthropic|external] [--model-name <name>] [--seed <n>] [--no-recovery]   anvil, the world, then Loop D judged by the doctor
 foga loop-d run --world <world.json> --rpc <url> [--dir <dir>] [--out <evidence.json>] [--model] [--model-name] [--seed] [--no-recovery] [--listen] [--wait <s>] [--idle <s>]
 foga doctor [--world <world.json>] --loop-d <evidence.json> [--compare <evidence2.json>] [--out <report.json>]
-foga quickstart [--dir <dir>] [--port <n>] [--listen <host:port> | --no-serve] [--name <cell>] [--no-tenders] [--exit]   one command to a live cell and its client configuration
+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 first) and its client configuration
 ```
 
 During development the CLI runs from source with `npm run foga -- <args>`; `npm run build` compiles it to `dist/` for the `foga` binary.

package/dist/a2a/card.js

@@ -0,0 +1,54 @@
+import { SIGNED_SCHEME } from "../http/signed.js";
+import { A2A_PROTOCOL_VERSION } from "./types.js";
+/** The public endpoints of a cell: the configuration's, or derived from runtime.http.publicUrl. */
+export function endpointsOf(node) {
+    const cfg = node.config;
+    const base = cfg.runtime.http.publicUrl?.replace(/\/+$/, "") ?? null;
+    return {
+        a2a: cfg.presence.endpoints.a2a ?? (base ? `${base}/a2a` : null),
+        mcp: cfg.presence.endpoints.mcp ?? (base ? `${base}/mcp` : null),
+        web: cfg.presence.endpoints.web ?? cfg.presence.homepage ?? base,
+    };
+}
+export async function buildAgentCard(node, o) {
+    const cfg = node.config;
+    const endpoints = endpointsOf(node);
+    const held = node.cell ? await node.heldSkills() : [];
+    const skills = held
+        .filter((h) => cfg.skills.offered.includes(h.name))
+        .map((h) => {
+        const m = h.pkg.manifest;
+        const version = m.skillVersion ?? String(h.pkg.version);
+        return {
+            id: `${h.name}@${version}`,
+            name: h.name,
+            description: m.summary ?? `The ERC-8338 skill ${h.name} (package ${h.packageHash})`,
+            tags: ["erc8338", "foga", h.name, ...(m.skillType ? [m.skillType] : [])],
+            examples: [
+                `{"foga":{"mode":"quote","skill":"${h.name}","input":{}}}`,
+                `{"foga":{"mode":"tender","tokenId":"<an ERC-8414 tender for ${h.name}, funded, with the hashlock committed>"}}`,
+            ],
+            inputModes: ["application/json", "text/plain"],
+            outputModes: ["application/json"],
+        };
+    });
+    const card = {
+        name: cfg.presence.name,
+        description: cfg.presence.description || `FOGA cell ${cfg.name}`,
+        supportedInterfaces: endpoints.a2a ? [{ url: endpoints.a2a, protocolBinding: "JSONRPC", protocolVersion: A2A_PROTOCOL_VERSION }] : [],
+        ...(cfg.presence.provider ? { provider: { organization: cfg.presence.provider.organization, url: cfg.presence.provider.url } } : {}),
+        version: o.version,
+        documentationUrl: "https://github.com/garyyang-finchip/foga#readme",
+        capabilities: { streaming: false, pushNotifications: false, extendedAgentCard: false },
+        securitySchemes: {
+            "api-key": { httpAuthSecurityScheme: { scheme: "Bearer", description: "An API key the cell's operator issued (foga node key new)." } },
+            "wallet-signature": { httpAuthSecurityScheme: { scheme: SIGNED_SCHEME, description: "An EIP-712 envelope signed by the caller's own wallet for this cell (docs/mcp.md, signed calls)." } },
+        },
+        securityRequirements: [],
+        defaultInputModes: ["text/plain", "application/json"],
+        defaultOutputModes: ["application/json", "text/plain"],
+        skills,
+        ...(cfg.presence.image ? { iconUrl: cfg.presence.image } : {}),
+    };
+    return card;
+}

package/dist/a2a/server.js

@@ -0,0 +1,276 @@
+import { randomUUID } from "node:crypto";
+import { ACTION_RANK } from "../tools/index.js";
+import { A2A_ERRORS, A2A_PROTOCOL_VERSION, TERMINAL_STATES } from "./types.js";
+const TASK_PREFIX = "a2a.task.";
+const MSG_PREFIX = "a2a.msg.";
+const QUOTE_SKILL_LIMIT = 50;
+const now = () => new Date().toISOString();
+function errorInfo(reason, metadata = {}) {
+    return { "@type": "type.googleapis.com/google.rpc.ErrorInfo", reason, domain: "a2a-protocol.org", metadata: { ...metadata, timestamp: now() } };
+}
+export class A2AError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+    }
+}
+function agentMessage(text, data, taskId, contextId) {
+    const parts = [{ text }];
+    if (data !== undefined)
+        parts.push({ data, mediaType: "application/json" });
+    return { messageId: randomUUID(), role: "ROLE_AGENT", parts, ...(taskId ? { taskId } : {}), ...(contextId ? { contextId } : {}) };
+}
+/** The `foga` request in a message: from a data part with a `foga` object, or a text part (a question in words → quote). */
+export function fogaRequestOf(message) {
+    for (const p of message.parts) {
+        const d = p.data;
+        if (d && typeof d === "object" && d.foga && typeof d.foga === "object") {
+            const f = d.foga;
+            const mode = f.mode === "tender" ? "tender" : "quote";
+            return { mode, skill: typeof f.skill === "string" ? f.skill : undefined, input: f.input, tokenId: f.tokenId !== undefined ? String(f.tokenId) : undefined };
+        }
+    }
+    const text = message.parts.map((p) => p.text).filter((t) => typeof t === "string").join("\n").trim();
+    return { mode: "quote", text: text || undefined };
+}
+export class A2AServer {
+    node;
+    catalog;
+    log;
+    constructor(node, catalog, log = () => { }) {
+        this.node = node;
+        this.catalog = catalog;
+        this.log = log;
+    }
+    get store() {
+        return this.node.store;
+    }
+    load(id) {
+        return this.store.getFact(TASK_PREFIX + id);
+    }
+    save(t) {
+        this.store.setFact(TASK_PREFIX + t.task.id, t);
+    }
+    visible(t, caller) {
+        return caller.visibility === "operator" || t.caller === caller.id;
+    }
+    setState(t, state, message) {
+        t.task.status = { state, timestamp: now(), ...(message ? { message } : {}) };
+        if (message)
+            t.task.history = [...(t.task.history ?? []), message];
+        this.save(t);
+    }
+    /** The JSON-RPC dispatcher: one request in, one response out; the HTTP layer checks the version header and the media type. */
+    async handle(request, caller, version) {
+        const id = request?.id ?? null;
+        try {
+            if (!request || typeof request !== "object" || request.jsonrpc !== "2.0" || typeof request.method !== "string")
+                throw new A2AError(A2A_ERRORS.InvalidRequestError, "Request payload validation error");
+            const v = (version ?? "").trim() || "0.3";
+            if (v !== A2A_PROTOCOL_VERSION)
+                throw new A2AError(A2A_ERRORS.VersionNotSupportedError, `A2A version ${v} is not supported; this agent speaks ${A2A_PROTOCOL_VERSION} (send A2A-Version: ${A2A_PROTOCOL_VERSION})`, [errorInfo("VERSION_NOT_SUPPORTED", { requested: v, supported: [A2A_PROTOCOL_VERSION] })]);
+            const { method, params } = request;
+            let result;
+            switch (method) {
+                case "SendMessage":
+                    result = await this.sendMessage(params, caller);
+                    break;
+                case "GetTask":
+                    result = this.getTask(params, caller);
+                    break;
+                case "ListTasks":
+                    result = this.listTasks((params ?? {}), caller);
+                    break;
+                case "CancelTask":
+                    result = await this.cancelTask(params, caller);
+                    break;
+                case "SendStreamingMessage":
+                case "SubscribeToTask":
+                    throw new A2AError(A2A_ERRORS.UnsupportedOperationError, "streaming is not supported by this agent (capabilities.streaming is false)");
+                case "GetExtendedAgentCard":
+                    throw new A2AError(A2A_ERRORS.UnsupportedOperationError, "no extended agent card (capabilities.extendedAgentCard is false)");
+                case "CreateTaskPushNotificationConfig":
+                case "GetTaskPushNotificationConfig":
+                case "ListTaskPushNotificationConfigs":
+                case "DeleteTaskPushNotificationConfig":
+                    throw new A2AError(A2A_ERRORS.PushNotificationNotSupportedError, "push notifications are not supported by this agent (capabilities.pushNotifications is false)");
+                default:
+                    throw new A2AError(A2A_ERRORS.MethodNotFoundError, "Method not found");
+            }
+            return { jsonrpc: "2.0", id, result };
+        }
+        catch (e) {
+            if (e instanceof A2AError)
+                return { jsonrpc: "2.0", id, error: { code: e.code, message: e.message, ...(e.data ? { data: e.data } : {}) } };
+            this.log(`a2a: ${e.message}`);
+            return { jsonrpc: "2.0", id, error: { code: A2A_ERRORS.InternalError, message: "Internal error" } };
+        }
+    }
+    // ---------------------------------------------------------------------------- SendMessage
+    async sendMessage(params, caller) {
+        const m = params?.message;
+        if (!m || typeof m !== "object" || typeof m.messageId !== "string" || !Array.isArray(m.parts) || m.parts.length === 0)
+            throw new A2AError(A2A_ERRORS.InvalidParamsError, "Invalid parameters", [{ "@type": "type.googleapis.com/google.rpc.BadRequest", fieldViolations: [{ field: "message", description: "messageId and at least one part are required" }] }]);
+        for (const p of m.parts) {
+            if (p.raw !== undefined || p.url !== undefined)
+                throw new A2AError(A2A_ERRORS.ContentTypeNotSupportedError, "file parts are not accepted; send text/plain or an application/json data part");
+            if (p.mediaType && !/^(text\/plain|application\/json)\b/.test(p.mediaType))
+                throw new A2AError(A2A_ERRORS.ContentTypeNotSupportedError, `media type ${p.mediaType} is not accepted; text/plain or application/json`);
+        }
+        // the same message from the same caller is the same task (3.3.1: messageId detects duplicates)
+        const dedupeKey = `${MSG_PREFIX}${caller.id}:${m.messageId}`;
+        const known = this.store.getFact(dedupeKey);
+        if (known) {
+            const t = this.load(known);
+            if (t)
+                return { task: this.publicTask(t, params.configuration?.historyLength) };
+        }
+        // a message to an existing task: input for one that asked, nothing for a terminal one
+        if (m.taskId) {
+            const t = this.load(m.taskId);
+            if (!t || !this.visible(t, caller))
+                throw new A2AError(A2A_ERRORS.TaskNotFoundError, "Task not found", [errorInfo("TASK_NOT_FOUND", { taskId: m.taskId })]);
+            if (TERMINAL_STATES.includes(t.task.status.state))
+                throw new A2AError(A2A_ERRORS.UnsupportedOperationError, `task ${m.taskId} is ${t.task.status.state} and accepts no further message`);
+            t.messageIds.push(m.messageId);
+            t.task.history = [...(t.task.history ?? []), m];
+            this.store.setFact(dedupeKey, t.task.id);
+            await this.work(t, m, caller);
+            return { task: this.publicTask(t, params.configuration?.historyLength) };
+        }
+        const task = { task: { id: randomUUID(), contextId: m.contextId ?? randomUUID(), status: { state: "TASK_STATE_SUBMITTED", timestamp: now() }, history: [m], artifacts: [], metadata: { caller: caller.id, cell: this.node.config.name } }, caller: caller.id, messageIds: [m.messageId], createdAt: now(), jobs: {} };
+        this.save(task);
+        this.store.setFact(dedupeKey, task.task.id);
+        await this.work(task, m, caller);
+        return { task: this.publicTask(task, params.configuration?.historyLength) };
+    }
+    /** Decide what a message asks for and do it: a quote at once, a tender's work started. */
+    async work(t, m, caller) {
+        const req = fogaRequestOf(m);
+        if (req.mode === "quote") {
+            await this.quote(t, req);
+            return;
+        }
+        const tokenId = req.tokenId ?? t.tokenId;
+        if (!tokenId) {
+            this.setState(t, "TASK_STATE_INPUT_REQUIRED", agentMessage("Which tender? Send a data part {\"foga\":{\"mode\":\"tender\",\"tokenId\":\"<id>\"}} naming an ERC-8414 tender that exists, is funded, and has its answer committed to the hashlock verifier.", { foga: { need: ["tokenId"] } }, t.task.id, t.task.contextId));
+            return;
+        }
+        if (ACTION_RANK[caller.level] < ACTION_RANK.act) {
+            this.setState(t, "TASK_STATE_REJECTED", agentMessage("This caller may not ask the cell to act: the tender mode needs an act-level credential (an API key the operator issued, or a wallet signature the cell's policy grants). A quote is open to everyone.", { foga: { gate: "permission", callerLevel: caller.level } }, t.task.id, t.task.contextId));
+            return;
+        }
+        t.tokenId = tokenId;
+        this.setState(t, "TASK_STATE_WORKING", agentMessage(`Working tender ${tokenId}: pre-check, run, submit. Settlement is the node's own duty afterwards.`, undefined, t.task.id, t.task.contextId));
+        // the work continues after the response (3.3.3); GetTask reads the result
+        void this.takeTender(t, tokenId, caller).catch((e) => {
+            this.log(`a2a: task ${t.task.id}: ${e.message}`);
+            const fresh = this.load(t.task.id) ?? t;
+            this.setState(fresh, "TASK_STATE_FAILED", agentMessage(`The work failed: ${e.message}`, undefined, t.task.id, t.task.contextId));
+        });
+    }
+    async quote(t, req) {
+        const cfg = this.node.config;
+        const held = this.node.cell ? await this.node.heldSkills() : [];
+        const offered = held.filter((h) => cfg.skills.offered.includes(h.name)).slice(0, QUOTE_SKILL_LIMIT);
+        const terms = { acceptance: "hashlock", verifier: this.node.acceptance.hashlock, asset: "native", minRewardWei: cfg.policy.tenders.minRewardWei, minSubmitWindowSeconds: cfg.policy.tenders.minSubmitWindowSeconds, minSettleWindowSeconds: cfg.policy.tenders.minSettleWindowSeconds, counterpartyMinLevel: cfg.policy.tenders.counterpartyMinLevel };
+        const how = "Mint an ERC-8414 tender for the skill with these terms (tender_mint_build gives the calls for your own account), fund it, commit the answer hash to the hashlock verifier, then send {\"foga\":{\"mode\":\"tender\",\"tokenId\":\"<id>\"}} with an act-level credential.";
+        if (req.skill && !offered.some((h) => h.name === req.skill)) {
+            this.setState(t, "TASK_STATE_REJECTED", agentMessage(`The cell does not offer a skill named ${req.skill}. Offered: ${offered.map((h) => h.name).join(", ") || "none"}.`, { foga: { quote: { skill: req.skill, offered: false, available: offered.map((h) => h.name) } } }, t.task.id, t.task.contextId));
+            return;
+        }
+        const chosen = req.skill ? offered.filter((h) => h.name === req.skill) : offered;
+        const quote = { cell: cfg.name, account: this.node.cell?.address ?? null, skills: chosen.map((h) => ({ name: h.name, version: String(h.pkg.manifest.skillVersion ?? h.pkg.version), packageHash: h.packageHash, tokenId: h.tokenId.toString(), summary: h.pkg.manifest.summary ?? null })), terms, ...(req.input !== undefined ? { inputEchoed: req.input } : {}), how };
+        const artifact = { artifactId: randomUUID(), name: "quote", description: "What the cell can do and on what terms", parts: [{ data: { foga: { quote } }, mediaType: "application/json" }] };
+        t.task.artifacts = [artifact];
+        const text = req.text ? `You asked: ${req.text.slice(0, 200)}. ` : "";
+        this.setState(t, "TASK_STATE_COMPLETED", agentMessage(`${text}The cell offers ${chosen.length} skill(s)${chosen.length ? `: ${chosen.map((h) => h.name).join(", ")}` : ""}; the terms are in the quote artifact. Nothing ran and nothing touched the chain.`, undefined, t.task.id, t.task.contextId));
+    }
+    /** The tender road: the catalog decides every step as the caller; the task records the decisions. */
+    async takeTender(t, tokenId, caller) {
+        const reject = (text, data) => this.setState(this.load(t.task.id) ?? t, "TASK_STATE_REJECTED", agentMessage(text, data, t.task.id, t.task.contextId));
+        const cancelled = () => Boolean(this.load(t.task.id)?.cancelRequested);
+        const pre = await this.catalog.invoke(this.node, "tender_precheck", { tokenId }, caller, { mode: "act" });
+        if (!pre.ok)
+            return reject(`Tender ${tokenId} refused at ${pre.gate}: ${pre.reason}`, { foga: { gate: pre.gate, reason: pre.reason, decisionId: pre.decisionId ?? null } });
+        const view = pre.output.tender;
+        if (!view.task)
+            return reject(`Tender ${tokenId} has no readable task document`, { foga: { gate: "input" } });
+        if (cancelled())
+            return this.setState(this.load(t.task.id), "TASK_STATE_CANCELED", agentMessage("Cancelled before the run.", undefined, t.task.id, t.task.contextId));
+        const run = await this.catalog.invoke(this.node, "skill_run", { skill: view.task.skill, input: view.task.input, tokenId }, caller, { mode: "act" });
+        if (!run.ok)
+            return reject(`The run for tender ${tokenId} was refused at ${run.gate}: ${run.reason}`, { foga: { gate: run.gate, reason: run.reason, decisionId: run.decisionId ?? null } });
+        const stored = this.load(t.task.id) ?? t;
+        stored.jobs.run = run.jobId;
+        this.save(stored);
+        if (cancelled())
+            return this.setState(this.load(t.task.id), "TASK_STATE_CANCELED", agentMessage("Cancelled before the submission.", undefined, t.task.id, t.task.contextId));
+        const out = run.output;
+        const sub = await this.catalog.invoke(this.node, "tender_submit", { tokenId, resultHash: out.resultHash, runReceipt: out.runReceipt }, caller, { mode: "act" });
+        const latest = this.load(t.task.id) ?? t;
+        if (!sub.ok) {
+            latest.jobs.submit = sub.jobId;
+            this.save(latest);
+            return reject(`The submission for tender ${tokenId} was refused at ${sub.gate}: ${sub.reason}`, { foga: { gate: sub.gate, reason: sub.reason, decisionId: sub.decisionId ?? null, jobId: sub.jobId ?? null } });
+        }
+        latest.jobs.submit = sub.jobId;
+        const result = sub.output;
+        latest.task.artifacts = [{ artifactId: randomUUID(), name: "submission", description: "The cell's submission on the tender", parts: [{ data: { foga: { tokenId, resultHash: out.resultHash, answerHash: out.answerHash, submissionId: result.submissionId ?? null, txHash: result.txHash ?? null, jobId: sub.jobId, decisionId: sub.decisionId ?? null, operations: sub.operations ?? [] } }, mediaType: "application/json" }] }];
+        this.setState(latest, "TASK_STATE_COMPLETED", agentMessage(`Tender ${tokenId} submitted (job ${sub.jobId}); the node settles it once the chain allows.`, undefined, t.task.id, t.task.contextId));
+    }
+    // ---------------------------------------------------------------------------- GetTask, ListTasks, CancelTask
+    getTask(params, caller) {
+        if (!params || typeof params.id !== "string")
+            throw new A2AError(A2A_ERRORS.InvalidParamsError, "Invalid parameters", [{ "@type": "type.googleapis.com/google.rpc.BadRequest", fieldViolations: [{ field: "id", description: "the task id is required" }] }]);
+        const t = this.load(params.id);
+        if (!t || !this.visible(t, caller))
+            throw new A2AError(A2A_ERRORS.TaskNotFoundError, "Task not found", [errorInfo("TASK_NOT_FOUND", { taskId: params.id })]);
+        return this.publicTask(t, params.historyLength);
+    }
+    listTasks(params, caller) {
+        const all = Object.values(this.store.facts(TASK_PREFIX));
+        let tasks = all.filter((t) => this.visible(t, caller));
+        if (params.contextId)
+            tasks = tasks.filter((t) => t.task.contextId === params.contextId);
+        if (params.status)
+            tasks = tasks.filter((t) => t.task.status.state === params.status);
+        if (params.statusTimestampAfter)
+            tasks = tasks.filter((t) => (t.task.status.timestamp ?? "") > params.statusTimestampAfter);
+        tasks.sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
+        const pageSize = Math.min(100, Math.max(1, params.pageSize ?? 50));
+        const offset = params.pageToken ? Number(params.pageToken) || 0 : 0;
+        const page = tasks.slice(offset, offset + pageSize);
+        return { tasks: page.map((t) => this.publicTask(t, params.historyLength, params.includeArtifacts ?? false)), nextPageToken: offset + pageSize < tasks.length ? String(offset + pageSize) : "", pageSize, totalSize: tasks.length };
+    }
+    async cancelTask(params, caller) {
+        if (!params || typeof params.id !== "string")
+            throw new A2AError(A2A_ERRORS.InvalidParamsError, "Invalid parameters");
+        const t = this.load(params.id);
+        if (!t || !this.visible(t, caller))
+            throw new A2AError(A2A_ERRORS.TaskNotFoundError, "Task not found", [errorInfo("TASK_NOT_FOUND", { taskId: params.id })]);
+        if (TERMINAL_STATES.includes(t.task.status.state))
+            throw new A2AError(A2A_ERRORS.TaskNotCancelableError, `task ${params.id} is ${t.task.status.state}`, [errorInfo("TASK_NOT_CANCELABLE", { taskId: params.id, state: t.task.status.state })]);
+        // a submission on its way to the chain is not undone by a cancellation: what was broadcast stays
+        if (t.jobs.submit)
+            throw new A2AError(A2A_ERRORS.TaskNotCancelableError, `task ${params.id} has submitted on chain (job ${t.jobs.submit}); a broadcast is not undone`, [errorInfo("TASK_NOT_CANCELABLE", { taskId: params.id, jobId: t.jobs.submit })]);
+        if (t.task.status.state === "TASK_STATE_WORKING") {
+            t.cancelRequested = true;
+            this.save(t);
+            return this.publicTask(t);
+        }
+        this.setState(t, "TASK_STATE_CANCELED", agentMessage("Cancelled.", undefined, t.task.id, t.task.contextId));
+        return this.publicTask(t);
+    }
+    publicTask(t, historyLength, artifacts = true) {
+        const task = { ...t.task };
+        if (historyLength !== undefined && task.history)
+            task.history = historyLength <= 0 ? [] : task.history.slice(-historyLength);
+        if (!artifacts)
+            delete task.artifacts;
+        return task;
+    }
+}

package/dist/a2a/types.js

@@ -0,0 +1,20 @@
+export const TERMINAL_STATES = ["TASK_STATE_COMPLETED", "TASK_STATE_FAILED", "TASK_STATE_CANCELED", "TASK_STATE_REJECTED"];
+/** JSON-RPC error codes of the binding (specification section 5.4 and 9.5). */
+export const A2A_ERRORS = {
+    JSONParseError: -32700,
+    InvalidRequestError: -32600,
+    MethodNotFoundError: -32601,
+    InvalidParamsError: -32602,
+    InternalError: -32603,
+    TaskNotFoundError: -32001,
+    TaskNotCancelableError: -32002,
+    PushNotificationNotSupportedError: -32003,
+    UnsupportedOperationError: -32004,
+    ContentTypeNotSupportedError: -32005,
+    InvalidAgentResponseError: -32006,
+    ExtendedAgentCardNotConfiguredError: -32007,
+    ExtensionSupportRequiredError: -32008,
+    VersionNotSupportedError: -32009,
+};
+export const A2A_PROTOCOL_VERSION = "1.0";
+export const A2A_WELL_KNOWN = "/.well-known/agent-card.json";

package/dist/build/bundle.js

@@ -35,7 +35,8 @@ function solcBinary(profiles, version, solcDir) {
 function forgeBuild(projectDir, outDir, skip, solcPath, extraArgs = []) {
     rmrf(outDir);
     ensureDir(outDir);
-    const args = ["build", "--ast", "--no-cache", "--out", outDir, ...extraArgs];
+    // the build-info files (the standard JSON input and output of each compiler run) stay beside the artifacts: `foga world verify --sourcify` submits them
+    const args = ["build", "--ast", "--no-cache", "--out", outDir, "--build-info", "--build-info-path", join(outDir, "build-info"), ...extraArgs];
     for (const s of skip)
         args.push("--skip", s);
     if (solcPath)