@fangorn-network/westmarch 2026.10.27 → 2026.10.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fangorn-network/westmarch",
-  "version": "2026.10.27",
+  "version": "2026.10.28",
   "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.26-dev",
+    "@fangorn-network/sdk": "^2026.10.27-dev",
     "@huggingface/transformers": "^4.2.0",
     "@noble/curves": "^1.9.1",
     "viem": "^2.55.1"
@@ -56,7 +56,7 @@
     }
   },
   "devDependencies": {
-    "@fangorn-network/sdk": "^2026.10.26-dev",
+    "@fangorn-network/sdk": "^2026.10.27-dev",
     "@huggingface/transformers": "^4.2.0",
     "@noble/curves": "^1.9.1",
     "@privy-io/react-auth": "^3.47.0",
@@ -68,14 +68,14 @@
     "viem": "^2.56.3"
   },
   "bin": {
-    "westmarch": "./src/publish/init.js",
-    "westmarch-publish": "./src/publish/cli.js",
-    "westmarch-view": "./src/publish/view-cli.js",
-    "westmarch-ship": "./src/publish/ship.js",
-    "westmarch-eval": "./dist/ts/eval.js",
-    "westmarch-lint": "./src/publish/lint.js",
-    "fangorn-mcp": "./src/agent/mcp.js",
-    "fangorn-fx": "./plugin/scripts/fx.mjs"
+    "westmarch": "src/publish/init.js",
+    "westmarch-publish": "src/publish/cli.js",
+    "westmarch-view": "src/publish/view-cli.js",
+    "westmarch-ship": "src/publish/ship.js",
+    "westmarch-eval": "dist/ts/eval.js",
+    "westmarch-lint": "src/publish/lint.js",
+    "fangorn-mcp": "src/agent/mcp.js",
+    "fangorn-fx": "plugin/scripts/fx.mjs"
   },
   "files": [
     "src",

package/site/worker.js

@@ -35,7 +35,7 @@ import { createPublicClient, http } from "viem";
 import { generatePrivateKey } from "viem/accounts";
 import { EMBED_MODEL, DOCUMENT, QUERY, matryoshka } from "../src/core/embed.js";
 import { configure, resetShard } from "../src/core/shard.js";
-import { publishView, r2Store } from "../src/publish/view.js";
+import { ORIGIN, publishView, r2Store } from "../src/publish/view.js";
 import { viewTools } from "../src/agent/view-tools.js";
 
 let CONFIG = { paid: null };
@@ -57,8 +57,18 @@ const encode = (env, prompt) => async (texts) =>
 // ── the indexer ───────────────────────────────────────────────────────────────
 
 const STATE = "state.json", LOCK = "index.lock";
-// A run past this is presumed dead and its lock taken over. Cron runs get 15 minutes.
-const LOCK_MS = 14 * 60_000;
+// A live run beats its lock every BEAT_MS; one silent past LOCK_MS is presumed dead (killed for CPU
+// or wall time, which skips `finally`) and its lock taken over. Lock: "<last beat ms> <run id>".
+// ponytail: get-then-put, so two runs starting in the same instant can both take it; R2's onlyIf etag when that shows.
+const LOCK_MS = 2 * 60_000, BEAT_MS = 30_000;
+export async function takeLock(bucket, now = Date.now()) {
+    const held = await (await bucket.get(LOCK))?.text();
+    if (held && now - Number(held.split(" ")[0]) < LOCK_MS) return null;
+    const id = crypto.randomUUID();
+    const beat = () => bucket.put(LOCK, `${Date.now()} ${id}`);
+    await beat();
+    return { id, beat, release: async () => { if ((await (await bucket.get(LOCK))?.text())?.endsWith(id)) await bucket.delete(LOCK); } };
+}
 
 // CONFIG.network: the SDK's network name ("baseSepolia"); absent, its default.
 const network = () => SupportedNetworks[CONFIG.network] ?? FangornConfig;
@@ -96,9 +106,9 @@ export async function presented({ fangorn, chain }, state) {
 }
 
 export async function index(env, { log = console.log } = {}) {
-    const lock = await env.VIEW.get(LOCK);
-    if (lock && Date.now() - Number(await lock.text()) < LOCK_MS) return log("index: a run is in progress; skipped");
-    await env.VIEW.put(LOCK, String(Date.now()));
+    const lock = await takeLock(env.VIEW);
+    if (!lock) return log("index: a run is in progress; skipped");
+    const beating = setInterval(() => lock.beat().catch(() => {}), BEAT_MS);
     try {
         const state = (await (await env.VIEW.get(STATE))?.json()) ?? { block: null, repos: {} };
         const r = reader(env);
@@ -113,7 +123,8 @@ export async function index(env, { log = console.log } = {}) {
         log(`index: through block ${state.block}, ${Object.keys(report).length} domain(s) changed`);
         return report;
     } finally {
-        await env.VIEW.delete(LOCK);
+        clearInterval(beating);
+        await lock.release();
     }
 }
 
@@ -455,7 +466,6 @@ async function paidCall(origin, tool, payment, run) {
     return { ...result, _meta: { ...result._meta, "x402/payment-response": settled } };
 }
 
-export const ORIGIN = "https://origin.westmarch.invalid";
 const BY_ORIGIN = new Set(["/.well-known/agent-card.json", "/openapi.json", "/.well-known/x402"]);
 
 const worker = {
@@ -517,6 +527,15 @@ if (typeof process !== "undefined" && import.meta.url === `file://${process.argv
                      delimitedPrefixes: [...new Set(ks.filter((k) => rest(k).includes("/")).map((k) => `${prefix + rest(k).split("/")[0]}/`))] };
         },
     };
+    const a = await takeLock(VIEW);
+    eq([!!a, await takeLock(VIEW)], [true, null], "a held lock skips the next run");
+    objs.set(LOCK, { bytes: new TextEncoder().encode(`${Date.now() - LOCK_MS - 1} dead`), at: new Date() });
+    const b = await takeLock(VIEW);
+    await a.release();
+    eq([!!b, objs.has(LOCK)], [true, true], "a silent lock is taken over, and its dead owner can't release the new one");
+    await b.release();
+    eq(objs.has(LOCK), false, "the owner releases its own lock");
+
     // Words → a 768-d vector, so a query shares dimensions with the rows that share its words.
     const calls = [];
     const AI = { run: async (model, { text }) => { calls.push({ model, text });

package/src/agent/agent-card.js

@@ -17,6 +17,7 @@
 // point back at it, so writing someone else's appId here gets you nothing.
 
 import { FANGORN_APP_EXTENSION, BaseSepoliaConfig, appId as hashAppId } 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. */
@@ -79,7 +80,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, skill, config = BaseSepoliaConfig }) {
+export function fangornExtension({ app, fromBlock, repos = [], views = [], mcp, paid, access, skill, plugin, config = BaseSepoliaConfig }) {
     if (!app) throw new Error("fangorn.app is required");
     const id = HEX32.test(app) ? app : hashAppId(app);
     const from = String(fromBlock ?? "");
@@ -102,6 +103,8 @@ export function fangornExtension({ app, fromBlock, repos = [], views = [], mcp,
     // `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 (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)}`);
     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 {
@@ -117,6 +120,7 @@ export function fangornExtension({ app, fromBlock, repos = [], views = [], mcp,
                                  symbol: paid.symbol ?? "USDC", decimals: paid.decimals ?? 6, description: paid.description ?? "" } } : {}),
             ...(access ? { access } : {}),
             ...(skill ? { skill: { url: skill.url, sha256: skill.sha256 } } : {}),
+            ...(plugin ? { plugin: { marketplace: plugin.marketplace, name: plugin.name } } : {}),
         },
     };
 }
@@ -159,6 +163,8 @@ if (typeof process !== "undefined" && import.meta.url === `file://${process.argv
     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");
+    eq(fangornExtension({ app: "a", 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", 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");
 }

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, skillOf, toApp } from "../discover/apps.js";
+import { APP_EXTENSION, listApps, pluginOf, 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.
@@ -216,7 +216,7 @@ export function handlers(deps) {
         while (open.has(s)) s += "-";
         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 }) };
+        const o = { slug: s, name: card.name, card: cardUrl, appId, skill: skillOf(ext), plugin: pluginOf(ext), ...await deps.remoteTools(mcp, { access }) };
         trace(`open ${app}: ready`);
         open.set(o.slug, o);
         deps.notify?.("notifications/tools/list_changed");
@@ -253,7 +253,10 @@ export function handlers(deps) {
                           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." } } : {}) });
+                          ...(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." } } : {}),
+                          // Its Claude Code plugin: hooks run code on every matching event, so the same rule, louder.
+                          ...(o.plugin ? { plugin: { ...o.plugin, install: `claude plugin install ${o.plugin.name} --marketplace ${o.plugin.marketplace}`,
+                              adopt: "The app ships a Claude Code plugin, whose hooks run code on this machine without being called. Offer it to the user once, saying what its hooks trigger on; install only on their yes. It takes effect next session." } } : {}) });
         },
         "call-app-tool": async ({ app, tool, arguments: args }) => call(app, tool, args),
     };
@@ -303,7 +306,7 @@ if (process.argv[2] === "--selfcheck") {
                                         { 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", 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" }),
+            params: { skill: { url: "https://k.test/skill/kings-foil/SKILL.md", sha256: "b".repeat(64) }, plugin: { marketplace: "k/kf", name: "kings-foil" } } }] } }, mcp: "https://k.test/mcp" }),
         remoteTools: async () => (opened++, remote),
     };
     deps.notify = serve(handlers(deps), { input, output });
@@ -327,6 +330,7 @@ if (process.argv[2] === "--selfcheck") {
     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(body(5).plugin?.marketplace === "k/kf" && /user/.test(body(5).plugin.adopt), "open-app offers the app's plugin, for the user to install");
     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

@@ -39,6 +39,14 @@ export const skillOf = (ext) => {
     return k && safeView(k.url) && /^[0-9a-f]{64}$/.test(k.sha256 ?? "") ? { url: k.url, sha256: k.sha256 } : null;
 };
 
+// The app's Claude Code plugin, for what a skill can't do (hooks). Both fields reach a shell command
+// in the reader's agent, so they are held to a GitHub owner/repo (or https URL) and a plain name.
+export const PLUGIN_MARKETPLACE = /^([\w.-]+\/[\w.-]+|https:\/\/[\w.\/-]+)$/, PLUGIN_NAME = /^[a-z0-9][a-z0-9-]*$/;
+export const pluginOf = (ext) => {
+    const p = ext?.params?.plugin;
+    return p && PLUGIN_MARKETPLACE.test(p.marketplace ?? "") && PLUGIN_NAME.test(p.name ?? "") ? { marketplace: p.marketplace, name: p.name } : 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);
@@ -46,7 +54,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, skill: skillOf(ext),
+        appId, card: cardUrl, fromBlock, repos, views, paid, skill: skillOf(ext), plugin: pluginOf(ext),
         mcp: safeView(ext?.params?.mcp),
         name: card.name ?? appId,
         desc: card.description ?? "",

package/src/publish/ship.js

@@ -83,6 +83,7 @@ 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)
+//             "plugin": {"marketplace": "owner/repo", "name": "…"},   // optional: its Claude Code plugin (hooks), offered by open-app
 //             "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
@@ -165,10 +166,13 @@ export function presentedRepos(cfg) {
 
 /** The Worker's wrangler config: the stock worker, the site as its assets, its bucket, the AI
  *  binding, the cron and CONFIG. `worker` is site/worker.js unless a test points elsewhere. */
-export function wranglerConfig({ name, site, account, cron = "*/5 * * * *", config, url, ipfsGateway, worker = join(HERE, "../../site/worker.js") }) {
+export function wranglerConfig({ name, site, account, cron = "*/5 * * * *", cpuMs, config, url, ipfsGateway, worker = join(HERE, "../../site/worker.js") }) {
     return {
         name, main: worker, compatibility_date: "2025-09-15", compatibility_flags: ["nodejs_compat"],
         ...(account ? { account_id: account } : {}),
+        // site.cpu_ms: the indexer's CPU per run. Reading one big commit (50k records) outlasts the
+        // 30 s Workers Paid default; up to 300000. The Free plan refuses the deploy with it set.
+        ...(cpuMs ? { limits: { cpu_ms: cpuMs } } : {}),
         assets: { directory: site, binding: "ASSETS" },
         r2_buckets: [{ binding: "VIEW", bucket_name: `${name}-view` }],
         ai: { binding: "AI" },
@@ -272,7 +276,7 @@ export async function buildForDeploy(configPath, wranglerPath = join(dirname(res
         log(`the R2 bucket ${w.r2_buckets?.[0]?.bucket_name} doesn't name the Worker; two apps sharing one overwrite each other's view`);
 
     process.env.FANGORN_NETWORK = process.env.CHAIN_NAME = cfg.network;
-    const [{ createPublicClient, http }, view, { ORIGIN }] = await Promise.all([import("viem"), import("./view.js"), import("../../site/worker.js")]);
+    const [{ createPublicClient, http }, view] = await Promise.all([import("viem"), import("./view.js")]);
     const FangornConfig = await view.network(cfg.network);
     const fangorn = await view.readOnlyFangorn();
     fangorn.setAppId(cfg.app);
@@ -283,7 +287,7 @@ export async function buildForDeploy(configPath, wranglerPath = join(dirname(res
 
     const base = dirname(resolve(configPath));
     const { site, writeCard } = await buildSite(cfg, base);
-    writeCard(ORIGIN, { fromBlock, repos: [] });
+    writeCard(view.ORIGIN, { fromBlock, repos: [] });
     const gateway = process.env.FANGORN_IPFS_GATEWAY;
     w.assets = { ...w.assets, directory: relative(dirname(resolve(wranglerPath)), site) };
     w.vars = { ...w.vars, CONFIG: { app: cfg.app, name: cfg.name, description: cfg.description, fromBlock, network: cfg.network,
@@ -400,7 +404,7 @@ export async function ship(configPath, { crawl = true, deploy = true, dry = fals
     const workerConfig = (u) => {
         const path = join(dir, "wrangler.json");
         writeFileSync(path, JSON.stringify(wranglerConfig({
-            name: cfg.site.project, site, account: cfg.site.account, cron: cfg.site.cron, url: cfg.site.url, ipfsGateway: view.ipfsGateway(),
+            name: cfg.site.project, site, account: cfg.site.account, cron: cfg.site.cron, cpuMs: cfg.site.cpu_ms, url: cfg.site.url, ipfsGateway: view.ipfsGateway(),
             config: { app: cfg.app, name: cfg.name, description: cfg.description, fromBlock: state.fromBlock, network: cfg.network,
                       schema: { types: cfg.types, relations: cfg.relations }, repos: register ? [] : repos, paid: sale(u).sale, private: access(u).config },
         }), null, 1));
@@ -576,7 +580,8 @@ export async function buildSite(cfg, base) {
                     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 } : {}),
-                       ...(skill ? { skill: { url: `${u}/${skill.path}`, sha256: skill.sha256 } } : {}) },
+                       ...(skill ? { skill: { url: `${u}/${skill.path}`, sha256: skill.sha256 } } : {}),
+                       ...(cfg.site.plugin ? { plugin: cfg.site.plugin } : {}) },
         });
         mkdirSync(join(site, ".well-known"), { recursive: true });
         writeFileSync(join(site, ".well-known/agent-card.json"), JSON.stringify(agentCard, null, 1));
@@ -715,8 +720,11 @@ export async function indexHere(configPath, { port = 8791 } = {}) {
     if (secret) writeFileSync(vars, `PAID_SECRET=${secret}\n`, { mode: 0o600 });
     const url = `http://127.0.0.1:${port}`, start = Math.floor(Date.now() / 1000);
     const wrangler = spawn("npx", ["wrangler", "dev", "--config", wpath, "--port", String(port), "--ip", "127.0.0.1", "--test-scheduled"],
-        { cwd: join(HERE, "../.."), stdio: ["ignore", "inherit", "inherit"],
+        { cwd: join(HERE, "../.."), stdio: ["ignore", "pipe", "inherit"],
           env: { ...process.env, ...(cfg.site.account ? { CLOUDFLARE_ACCOUNT_ID: cfg.site.account } : {}) } });
+    // A run already holds the lock (the deployed cron's): this one skips, and the catalog would never move.
+    let skipped = false;
+    wrangler.stdout.on("data", (b) => { process.stdout.write(b); if (String(b).includes("index: a run is in progress; skipped")) skipped = true; });
     try {
         for (;;) {
             if (wrangler.exitCode !== null) throw new Error("wrangler dev exited");
@@ -728,6 +736,7 @@ export async function indexHere(configPath, { port = 8791 } = {}) {
         let catalog = null;
         while (!(catalog?.generated_at >= start)) {
             if (wrangler.exitCode !== null) throw new Error("wrangler dev exited");
+            if (skipped) throw new Error("another indexer run holds the lock (the deployed cron's, most likely); it frees within 2 minutes of that run dying. Try again then.");
             await new Promise((ok) => setTimeout(ok, 5000));
             catalog = await fetch(`${url}/view/cdn/catalog`).then((r) => (r.ok ? r.json() : null), () => null);
         }