@fangorn-network/westmarch 2026.10.26-dev → 2026.10.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fangorn-network/westmarch",
-  "version": "2026.10.26-dev",
+  "version": "2026.10.27",
   "description": "all-in-one builder for fangorn apps",
   "license": "MIT",
   "type": "module",
@@ -45,7 +45,7 @@
     "@fangorn-network/markov": "^0.1.0"
   },
   "peerDependencies": {
-    "@fangorn-network/sdk": "^2026.10.21-dev",
+    "@fangorn-network/sdk": "^2026.10.26-dev",
     "@huggingface/transformers": "^4.2.0",
     "@noble/curves": "^1.9.1",
     "viem": "^2.55.1"

package/src/agent/agent-card.js

@@ -48,6 +48,10 @@ const HEX32 = /^0x[0-9a-fA-F]{64}$/;
  *              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.
+ *   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");
@@ -75,7 +79,7 @@ export function agentCard({ name, description, url, version = "0.0.0", tools = [
 
 /** 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, repos = [], views = [], mcp, paid, access, config = BaseSepoliaConfig }) {
+export function fangornExtension({ app, fromBlock, repos = [], views = [], mcp, paid, access, skill, config = BaseSepoliaConfig }) {
     if (!app) throw new Error("fangorn.app is required");
     const id = HEX32.test(app) ? app : hashAppId(app);
     const from = String(fromBlock ?? "");
@@ -96,6 +100,8 @@ export function fangornExtension({ app, fromBlock, repos = [], views = [], mcp,
     }
     // `access`: a private app. Its view and tools need a pass (`pass_url`, `pass` in base units, for
     // `days`) or one x402 payment of `call` per tool call; describe and the catalog are free.
+    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 (access && !(/^https?:\/\//.test(access.pass_url ?? "") && /^\d+$/.test(String(access.pass)) && /^\d+$/.test(String(access.call))))
         throw new Error(`fangorn.access needs pass_url, and pass and call in base units: ${JSON.stringify(access)}`);
     return {
@@ -110,6 +116,7 @@ export function fangornExtension({ app, fromBlock, repos = [], views = [], mcp,
             ...(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 ?? "" } } : {}),
             ...(access ? { access } : {}),
+            ...(skill ? { skill: { url: skill.url, sha256: skill.sha256 } } : {}),
         },
     };
 }
@@ -148,6 +155,10 @@ if (typeof process !== "undefined" && import.meta.url === `file://${process.argv
     throws(() => fangornExtension({ app: "a" }), /fromBlock/, "missing fromBlock");
     throws(() => fangornExtension({ app: "a", 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", 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", fromBlock: 0, skill: { url: "https://x.test/s.md" } }), /skill/, "a skill without its hash");
+    throws(() => fangornExtension({ app: "a", fromBlock: 0, skill: { url: "file:///etc/passwd", sha256: sha } }), /skill/, "a non-http skill");
 
     console.log("agent-card.js self-check ok — tools captured without executing, extension matches the SDK's, bad params fail the build");
 }

package/src/agent/mcp.js

@@ -24,7 +24,7 @@ import net from "node:net";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { createInterface } from "node:readline";
-import { APP_EXTENSION, listApps, toApp } from "../discover/apps.js";
+import { APP_EXTENSION, listApps, skillOf, toApp } from "../discover/apps.js";
 
 const log = (...a) => console.error("[fangorn-mcp]", ...a);   // stdout is the protocol
 // FANGORN_MCP_TRACE=1: step timings on stderr, for finding where an answer waits.
@@ -214,8 +214,9 @@ export function handlers(deps) {
         if (!mcp) throw new Error(`${card.name ?? cardUrl} has no MCP server (its card has no \`mcp\`)`);
         let s = slug(card.name ?? app);
         while (open.has(s)) s += "-";
-        const access = card.capabilities?.extensions?.find((e) => e.uri === APP_EXTENSION)?.params?.access ?? null;
-        const o = { slug: s, name: card.name, card: cardUrl, appId, ...await deps.remoteTools(mcp, { access }) };
+        const ext = card.capabilities?.extensions?.find((e) => e.uri === APP_EXTENSION);
+        const access = ext?.params?.access ?? null;
+        const o = { slug: s, name: card.name, card: cardUrl, appId, skill: skillOf(ext), ...await deps.remoteTools(mcp, { access }) };
         trace(`open ${app}: ready`);
         open.set(o.slug, o);
         deps.notify?.("notifications/tools/list_changed");
@@ -249,7 +250,10 @@ export function handlers(deps) {
         "open-app": async ({ app }) => {
             const o = await openApp(app);
             return text({ app: o.slug, name: o.name, card: o.card,
-                          call_as: `${o.slug}__<tool>, or call-app-tool`, tools: o.tools });
+                          call_as: `${o.slug}__<tool>, or call-app-tool`, tools: o.tools,
+                          // An app's own skill: standing instructions for the reader's agent, so never loaded
+                          // silently. The fangorn-index skill offers it to the user and pins the hash on a yes.
+                          ...(o.skill ? { skill: { ...o.skill, adopt: "The app ships an agent skill. Offer it to the user (what it would make you do, from its description); adopt it only on their yes, checking sha256, and ask again if the hash changes." } } : {}) });
         },
         "call-app-tool": async ({ app, tool, arguments: args }) => call(app, tool, args),
     };
@@ -298,7 +302,8 @@ if (process.argv[2] === "--selfcheck") {
         findApps: async () => ({ apps: [{ name: "Kings Foil", desc: "trials", card: "https://k.test/card", appId: "0xk" },
                                         { name: "Bare", desc: "", card: "https://b.test/card", appId: "0xb" }], rejected: [{}] }),
         exploreApps: async (q) => ({ ranked_by: q ? "meaning" : null, apps: [{ app: "kings-foil", name: "Kings Foil", relevant: true }, { app: "b", name: "B", relevant: false }] }),
-        resolveCard: async (url) => (url.includes("b.test") ? { card: { name: "Bare" }, mcp: null } : { card: { name: "Kings Foil" }, mcp: "https://k.test/mcp" }),
+        resolveCard: async (url) => (url.includes("b.test") ? { card: { name: "Bare" }, mcp: null } : { card: { name: "Kings Foil", capabilities: { extensions: [{ uri: APP_EXTENSION,
+            params: { skill: { url: "https://k.test/skill/kings-foil/SKILL.md", sha256: "b".repeat(64) } } }] } }, mcp: "https://k.test/mcp" }),
         remoteTools: async () => (opened++, remote),
     };
     deps.notify = serve(handlers(deps), { input, output });
@@ -321,6 +326,7 @@ if (process.argv[2] === "--selfcheck") {
     call(5, "open-app", { app: "Kings Foil" }); await wait();
     call(6, "open-app", { app: "https://k.test/card" }); await wait();
     assert(body(5).tools[0].name === "search" && opened === 1, "open once, by name or by card URL");
+    assert(body(5).skill?.url === "https://k.test/skill/kings-foil/SKILL.md" && /user/.test(body(5).skill.adopt), "open-app offers the app's skill, for the user to adopt");
     assert(replies.some((r) => r.method === "notifications/tools/list_changed"), "opening notifies");
     rpc(7, "tools/list"); call(8, "kings-foil__search", { query: "x" }); call(9, "call-app-tool", { app: "kings-foil", tool: "search" });
     call(10, "call-app-tool", { app: "kings-foil", tool: "boom" }); call(11, "open-app", { app: "nope" }); call(13, "open-app", { app: "Bare" }); rpc(12, "nope"); await wait();

package/src/discover/apps.js

@@ -33,6 +33,12 @@ function safeView(url) {
  *  src/agent/agent-card.js's self-check fails if the two drift. */
 export const APP_EXTENSION = "https://fangorn.network/a2a/app/v1";
 
+/** The app's agent skill, `{url, sha256}`, when its card names one well-formed; else null. */
+export const skillOf = (ext) => {
+    const k = ext?.params?.skill;
+    return k && safeView(k.url) && /^[0-9a-f]{64}$/.test(k.sha256 ?? "") ? { url: k.url, sha256: k.sha256 } : null;
+};
+
 /** A verified card → an app entry. `views` is westmarch's param; the SDK does not read it. */
 export function toApp({ card, appId, fromBlock, repos }, cardUrl) {
     const ext = card.capabilities.extensions.find((e) => e.uri === APP_EXTENSION);
@@ -40,7 +46,7 @@ export function toApp({ card, appId, fromBlock, repos }, cardUrl) {
     const p = ext?.params?.paid;
     const paid = p && /^https?:\/\//.test(p.url ?? "") && p.url.includes("{id}") && /^\d+$/.test(String(p.price)) ? p : null;
     return {
-        appId, card: cardUrl, fromBlock, repos, views, paid,
+        appId, card: cardUrl, fromBlock, repos, views, paid, skill: skillOf(ext),
         mcp: safeView(ext?.params?.mcp),
         name: card.name ?? appId,
         desc: card.description ?? "",

package/src/publish/ship.js

@@ -83,6 +83,8 @@ const log = (s) => console.error(`[ship] ${s}`);
 //                                 //   (pages/intro.html, a fragment, replaces the description on the front page)
 //             "nav": [{ "href": "coverage.html", "label": "Coverage" }],   // optional: header links to them
 //             "examples": ["…"],  // optional: questions to start from, on the front page (and a private app's gate)
+//             "skill": "skill/SKILL.md",   // optional: the app's agent skill, served at skill/<app>/SKILL.md and named
+//                                          //   in the card with its sha256; fangorn-index offers it to whoever opens the app
 //             "agent": "app/agent.js" },   // optional: the module whose registerAgent the card lists, when
 //                                          // `pages` replaces the stock index.html with a page of its own
 //   "types": { "<tag>": { "description": "…", "role_map": {…}, "presentation": {…} } },
@@ -549,6 +551,15 @@ export async function buildSite(cfg, base) {
     if (cfg.site.pages) cpSync(resolve(base, cfg.site.pages), site, { recursive: true });
     writeFileSync(join(site, "nav.json"), JSON.stringify(cfg.site.nav ?? []));
     writeFileSync(join(site, "examples.json"), JSON.stringify(cfg.site.examples ?? []));
+    // site.skill: the app's agent skill (a SKILL.md), served at skill/<app>/SKILL.md and named in the
+    // card with its hash, so fangorn-index can offer it to whoever opens the app.
+    let skill = null;
+    if (cfg.site.skill) {
+        const bytes = readFileSync(resolve(base, cfg.site.skill));
+        mkdirSync(join(site, "skill", cfg.app), { recursive: true });
+        writeFileSync(join(site, "skill", cfg.app, "SKILL.md"), bytes);
+        skill = { path: `skill/${cfg.app}/SKILL.md`, sha256: createHash("sha256").update(bytes).digest("hex") };
+    }
     // The card lists the tools the page at `url` registers: the stock page's, or the app's own.
     const card = await import("../agent/agent-card.js");
     const { registerAgent } = await import(cfg.site.agent ? pathToFileURL(resolve(base, cfg.site.agent)).href : "../../site/agent.js");
@@ -564,7 +575,8 @@ export async function buildSite(cfg, base) {
                 ...(paid ? [{ id: "keys", name: "Keys", tags: [...(cfg.tags ?? []), "x402"],
                     description: `The keys to sealed records (POST ${u}/paid), per record.` }] : []),
             ],
-            fangorn: { app: cfg.app, fromBlock, repos, views: [`${u}/view`], mcp: `${u}/mcp`, config, ...(paid ? { paid } : {}), ...(access ? { access } : {}) },
+            fangorn: { app: cfg.app, fromBlock, repos, views: [`${u}/view`], mcp: `${u}/mcp`, config, ...(paid ? { paid } : {}), ...(access ? { access } : {}),
+                       ...(skill ? { skill: { url: `${u}/${skill.path}`, sha256: skill.sha256 } } : {}) },
         });
         mkdirSync(join(site, ".well-known"), { recursive: true });
         writeFileSync(join(site, ".well-known/agent-card.json"), JSON.stringify(agentCard, null, 1));

package/template/package.json

@@ -6,7 +6,7 @@
     "deploy": "wrangler deploy"
   },
   "dependencies": {
-    "@fangorn-network/westmarch": "2026.10.2-2.0-dev",
+    "@fangorn-network/westmarch": "2026.10.27",
     "@huggingface/transformers": "^4.3.1",
     "wrangler": "^4.83.0"
   }