@fangorn-network/westmarch 0.0.19-dev → 0.1.0

package/src/agent/agent-card.js

@@ -10,13 +10,13 @@
 // generated from the same declarations the browser sees. Add a tool and it
 // appears on the next build; there is no second list to drift.
 //
-// The Fangorn extension is what makes the card an APP rather than a web page.
-// It names the app, where its data starts on chain, and which namespaces and
-// views hold it. It only counts once the app owner binds the card's URL on
-// chain (`setAppAgentUri`). `discoverApp` refuses a card whose app does not
-// point back at it, so writing someone else's appId here gets you nothing.
+// The Fangorn extension is what makes the card an APP rather than a web page. An app is a
+// publisher's repo (`owner : app`); the extension names it, where its data starts on chain,
+// which repos and views hold the data, and the MCP endpoint that serves them. It only counts
+// once the repo's `@card` record points back at the card (`setCard`): `discoverCard` checks.
 
-import { FANGORN_APP_EXTENSION, FangornConfig, appId as hashAppId } from "@fangorn-network/sdk";
+import { FANGORN_REPO_EXTENSION, BaseSepoliaConfig } from "@fangorn-network/sdk";
+import { PLUGIN_MARKETPLACE, PLUGIN_NAME } from "../discover/apps.js";
 
 /** Run `register` against a recording `document.modelContext`; return what it
  *  registered. `register` is whatever the page calls at load. */
@@ -31,21 +31,26 @@ export async function captureTools(register) {
     return tools;
 }
 
-const HEX32 = /^0x[0-9a-fA-F]{64}$/;
-
 /**
  * The card.
  *
  * `fangorn` is optional: without it this is a plain A2A card for a page with
- * tools. With it, `{app, fromBlock, namespaces, views, config}`:
- *   app        the app's name or its bytes32 id
+ * tools. With it, `{app, owner, fromBlock, repos, views, mcp, config}`:
+ *   app        the app's repo name
+ *   owner      the address that publishes it
  *   fromBlock  a block at or before the app's registration. The reader's log
  *              scan starts here; leave it at 0 and a reader makes one RPC call
  *              per 1000 blocks of chain history.
- *   views      view bases (quickbeam) holding the baked data. Read by
+ *   views      view bases (view.js's layout) holding the baked data. Read by
  *              westmarch's directory; the SDK ignores it.
+ *   mcp        a remote MCP endpoint (streamable HTTP) serving the views as
+ *              tools, as the free tier's Worker does at /mcp.
  *   config     the deployment; defaults to the SDK's, so the addresses in the
- *              card cannot drift from the ones `discoverApp` checks.
+ *              card cannot drift from the ones `discoverCard` checks.
+ *   skill      `{url, sha256}`: the app's own agent skill (a SKILL.md), for agents
+ *              that adopt it, so its behaviour travels with the app and not with a
+ *              marketplace. The hash pins what the reader saw: an agent adopts it
+ *              only on its user's yes, and asks again when the hash changes.
  */
 export function agentCard({ name, description, url, version = "0.0.0", tools = [], tags = [], skills = [], fangorn, ...rest }) {
     if (!name || !url) throw new Error("agentCard: name and url are required");
@@ -71,48 +76,49 @@ export function agentCard({ name, description, url, version = "0.0.0", tools = [
     return card;
 }
 
-/** The params `discoverApp` reads, validated the same way it validates them.
- *  A malformed card should fail the build, not the first reader. */
-export function fangornExtension({ app, fromBlock, namespaces = [], views = [], paid, config = FangornConfig }) {
+/** The params `discoverCard` reads, plus westmarch's. A malformed card fails the build, not the first reader. */
+export function fangornExtension({ app, owner, fromBlock, repos = [], views = [], mcp, paid, skill, plugin, config = BaseSepoliaConfig }) {
     if (!app) throw new Error("fangorn.app is required");
-    const id = HEX32.test(app) ? app : hashAppId(app);
+    if (!/^0x[0-9a-fA-F]{40}$/.test(owner ?? "")) throw new Error(`fangorn.owner must be an address, got ${owner}`);
     const from = String(fromBlock ?? "");
     if (!/^\d+$/.test(from)) throw new Error(`fangorn.fromBlock must be a non-negative integer, got ${fromBlock}`);
-    if (!namespaces.every((n) => typeof n === "string")) throw new Error("fangorn.namespaces must be strings");
-    for (const v of views) {
+    if (!repos.every((n) => typeof n === "string")) throw new Error("fangorn.repos must be strings");
+    for (const v of [...views, ...(mcp ? [mcp] : [])]) {
         const u = new URL(v);   // throws on garbage
         if (u.protocol !== "https:" && u.protocol !== "http:") throw new Error(`fangorn.views: not http(s): ${v}`);
     }
-    // `paid`: records sold over x402. `url` has an `{id}` for the record's id; `price` is in
-    // the token's base units. Readers only offer to buy; the 402 itself is the quote.
+    // `paid`: the app sells records (field-v1). `url` has an `{id}`: GET it for the record's x402 quote.
     if (paid) {
         const u = new URL(paid.url.replace("{id}", "x"));
         if (!/^https?:$/.test(u.protocol) || !paid.url.includes("{id}")) throw new Error(`fangorn.paid.url must be http(s) with {id}: ${paid.url}`);
-        if (!/^\d+$/.test(String(paid.price))) throw new Error(`fangorn.paid.price must be base units, got ${paid.price}`);
-        if (!/^0x[0-9a-fA-F]{40}$/.test(paid.asset ?? "")) throw new Error(`fangorn.paid.asset must be a token address`);
     }
+    if (skill && !(/^https?:\/\//.test(skill.url ?? "") && /^[0-9a-f]{64}$/.test(skill.sha256 ?? "")))
+        throw new Error(`fangorn.skill needs an http(s) url and the sha256 of the file, in hex: ${JSON.stringify(skill)}`);
+    if (plugin && !(PLUGIN_MARKETPLACE.test(plugin.marketplace ?? "") && PLUGIN_NAME.test(plugin.name ?? "")))
+        throw new Error(`fangorn.plugin needs a marketplace (GitHub owner/repo or https URL) and a plugin name: ${JSON.stringify(plugin)}`);
     return {
-        uri: FANGORN_APP_EXTENSION,
+        uri: FANGORN_REPO_EXTENSION,
         description: "The Fangorn app this agent fronts.",
         required: false,
         params: {
             chainId: config.caip2,
-            appRegistry: config.appRegistryContractAddress,
             dataRegistry: config.dataRegistryContractAddress,
-            appId: id, fromBlock: from, namespaces, views,
-            ...(paid ? { paid: { url: paid.url, price: String(paid.price), asset: paid.asset, network: paid.network,
-                                 symbol: paid.symbol ?? "USDC", decimals: paid.decimals ?? 6, description: paid.description ?? "" } } : {}),
+            publisher: owner, repo: app,
+            fromBlock: from, repos, views, ...(mcp ? { mcp } : {}),
+            ...(paid ? { paid: { url: paid.url } } : {}),
+            ...(skill ? { skill: { url: skill.url, sha256: skill.sha256 } } : {}),
+            ...(plugin ? { plugin: { marketplace: plugin.marketplace, name: plugin.name } } : {}),
         },
     };
 }
 
 // ── self-check: `node src/agent/agent-card.js` ────────────────────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/agent-card.js")) {
+if (import.meta.url === `file://${globalThis.process?.argv?.[1]}` && process.argv[1].endsWith("/agent-card.js")) {
     const eq = (a, b, m) => { if (JSON.stringify(a) !== JSON.stringify(b)) throw new Error(`${m}: ${JSON.stringify(a)} != ${JSON.stringify(b)}`); };
     const throws = (f, re, m) => { try { f(); } catch (e) { if (re.test(e.message)) return; throw e; } throw new Error(`must throw: ${m}`); };
 
     const { APP_EXTENSION } = await import("../discover/apps.js");
-    eq(APP_EXTENSION, FANGORN_APP_EXTENSION, "src/discover/apps.js's copy of the extension uri");
+    eq(APP_EXTENSION, FANGORN_REPO_EXTENSION, "src/discover/apps.js's copy of the extension uri");
 
     let fired = 0;
     const tools = await captureTools(() => {
@@ -128,17 +134,25 @@ if (typeof process !== "undefined" && import.meta.url === `file://${process.argv
     eq(plain.skills.map((s) => [s.id, s.name, s.tags]), [["search-rows", "Search rows", ["x", "webmcp"]], ["get-row", "Get row", ["x", "webmcp"]]], "skills");
     if (plain.capabilities.extensions) throw new Error("no fangorn → no extension");
 
-    const card = agentCard({ name: "X", url: "https://x.test", tools, fangorn: { app: "kingsfoil", fromBlock: 5n, namespaces: ["kingsfoil"], views: ["https://x.test/v1"] } });
+    const O = "0x" + "11".repeat(20);
+    const card = agentCard({ name: "X", url: "https://x.test", tools, fangorn: { app: "kingsfoil", owner: O, fromBlock: 5n, repos: ["kingsfoil"], views: ["https://x.test/v1"], mcp: "https://x.test/mcp" } });
     const [ext] = card.capabilities.extensions;
-    eq(ext.uri, FANGORN_APP_EXTENSION, "extension uri");
-    eq(ext.params.appId, hashAppId("kingsfoil"), "app name hashes to the id the registry uses");
-    eq([ext.params.chainId, ext.params.appRegistry, ext.params.fromBlock], [FangornConfig.caip2, FangornConfig.appRegistryContractAddress, "5"], "deployment + fromBlock as a decimal string");
-    eq(fangornExtension({ app: ext.params.appId, fromBlock: 0 }).params.appId, ext.params.appId, "a bytes32 id passes through");
+    eq(ext.uri, FANGORN_REPO_EXTENSION, "extension uri");
+    eq([ext.params.publisher, ext.params.repo], [O, "kingsfoil"], "the card names the repo it speaks for, as discoverCard reads it");
+    eq([ext.params.chainId, ext.params.dataRegistry, ext.params.fromBlock], [BaseSepoliaConfig.caip2, BaseSepoliaConfig.dataRegistryContractAddress, "5"], "deployment + fromBlock as a decimal string");
+    eq([ext.params.repos, ext.params.mcp], [["kingsfoil"], "https://x.test/mcp"], "repos and the MCP endpoint");
+    throws(() => fangornExtension({ app: "a", fromBlock: 0 }), /owner/, "missing owner");
 
-    throws(() => fangornExtension({ app: "a", fromBlock: -1 }), /fromBlock/, "negative fromBlock");
-    throws(() => fangornExtension({ app: "a" }), /fromBlock/, "missing fromBlock");
-    throws(() => fangornExtension({ app: "a", fromBlock: 0, views: ["javascript:alert(1)"] }), /views/, "non-http view");
+    throws(() => fangornExtension({ app: "a", owner: O, fromBlock: -1 }), /fromBlock/, "negative fromBlock");
+    throws(() => fangornExtension({ app: "a", owner: O }), /fromBlock/, "missing fromBlock");
+    throws(() => fangornExtension({ app: "a", owner: O, fromBlock: 0, views: ["javascript:alert(1)"] }), /views/, "non-http view");
     throws(() => agentCard({ name: "X" }), /url/, "missing url");
+    const sha = "a".repeat(64);
+    eq(fangornExtension({ app: "a", owner: O, fromBlock: 0, skill: { url: "https://x.test/skill/a/SKILL.md", sha256: sha } }).params.skill, { url: "https://x.test/skill/a/SKILL.md", sha256: sha }, "a skill rides in the extension");
+    throws(() => fangornExtension({ app: "a", owner: O, fromBlock: 0, skill: { url: "https://x.test/s.md" } }), /skill/, "a skill without its hash");
+    throws(() => fangornExtension({ app: "a", owner: O, fromBlock: 0, skill: { url: "file:///etc/passwd", sha256: sha } }), /skill/, "a non-http skill");
+    eq(fangornExtension({ app: "a", owner: O, fromBlock: 0, plugin: { marketplace: "o/r", name: "a" } }).params.plugin, { marketplace: "o/r", name: "a" }, "a plugin rides in the extension");
+    throws(() => fangornExtension({ app: "a", owner: O, fromBlock: 0, plugin: { marketplace: "o/r; rm -rf ~", name: "a" } }), /plugin/, "a plugin that would inject into a shell");
 
     console.log("agent-card.js self-check ok — tools captured without executing, extension matches the SDK's, bad params fail the build");
 }