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

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 3c done — Loop D, the unscripted run (3c); 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 3d in progress — 3d-2 done (the wallet, signed callers, the documents on chain, preflight, A2A, Sourcify), 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
+
+**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 — owner, operator, guardian in 0600 files under `~/.foga/wallet`, 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.
 
 **3c (0.6.0-alpha.4, 2026-11-02).** A model in the loop, and the acceptance that looks at records rather than words. `src/node/runner.ts` is the node's loop with a model: each tick perceives through the read capabilities, hands the situation and the catalog as tools to the model, carries out what it proposes — reads at once, acts through `Catalog.invoke` where the three checks decide and a refusal goes back so the model can revise once — and records the tick by hash (the decision records carry the model and the hashes of its request and answer; the journal the hash of the whole transcript; the text never). Limits bound a tick (12 tool calls, 2 acts) and a day (the model's calls, counted in the store). Two adapters on one interface: `anthropic` (the Messages API over `fetch`, the key in the environment, the model name in the configuration) and `stub` (a deterministic decision table that also proposes, once, a tender above the budget so the evidence shows the gate closing). `foga node run` is the embedded node — server, watchers, runner — on the operator key alone. `foga demo --loop-d` (`src/demo/loop-d.ts`) is the unscripted run: a new cell with fresh keys, an independent demander process minting cases a–f in a seeded order (two tenders to take, four to refuse at `skill`, `policy`, `verifier`, and one met during the guardian's suspension), the node killed after its first submission and restarted, the HTTP entrance used beside the runner (the same request answered once, the same job under another request a conflict, three mints at once of which the third is refused at `budget` before anything is sent), and an evidence file with every record, the cases' outcomes and a scan of every transaction the operator key signed. `foga doctor --loop-d` judges it beside layer 5: every operation under an allowed decision, refusals that broadcast nothing, the four budget books, the operator's transactions all at the account and allow-listed, the cases as expected, the recovery, the entrances, and — given two runs — the same outcomes from the stub and a real model. The slice also closed a race the run exposed: the catalog's decision section now runs one act at a time per node and a job reserves the value it will move from its decision. `test/loop-d.test.ts` (anvil, under a minute) and `test/model.test.ts` are the gate; CI runs Loop D on the world the genesis ran on. docs/loop-d.md.
 
@@ -70,11 +74,27 @@ 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: 3d closes Phase 3 — A2A, the documents, `foga quickstart`, the npm and registry publication, the OG instance's move to a revision-2 account with public endpoints and a real model'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
 
-Three ways in, from most to least demanding:
+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: owner, operator, guardian keys; prints the addresses to fund
+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
 # 1. Full reproduction (needs git, Node >= 22 and Foundry):
@@ -156,18 +176,18 @@ 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)
+docs/                design memo, compatibility matrix, version lock, build, world, doctor, cell account, kernel, genesis, zk, node, mcp, loop-d, quickstart, wallet, documents, a2a; 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)
 ```
@@ -180,26 +200,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>] [--single] | show [--rpc <url>] | sign --config <cell.config.json> [--role] [--ttl <s>] [--agent-id <id>] [--method --path [--body]]
+                                                                          an agent's own keys (the first step), 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] [--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]
+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>] [--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)