wiki-formant 0.69.0 → 0.71.0

package/README.md

@@ -91,6 +91,7 @@ const { items, total } = await searchWiki(reading, 'validators', { page: 1, size
 
 - Every row carries `path`, which every read tool takes back, and `chars` where the page's text was read. A pasted URL resolves, with `pathPrefix` stripped; a category's path reads its hub article; a miss names the nearest pages.
 - Every row carries the page `id` too, which a `pageList` block takes. `get_page` with `blocks: true` returns the stored blocks, the page `id`, its whole metadata and `version`: what an edit starts from. `forEdit` adds what the app's write tool takes beside them, and `authors` names each revision's author in `get_page_history`.
+- `text` should be the serializer the page's markdown twin uses, and `resolve` the resolver its page uses to fill what is read live (a page list's pages): `get_page`, `get_pages` and the default corpus read text through both, so a page reads the same over MCP as at its twin, which `twinParity` checks.
 - `privateHidden` closes the back office to every tool; without it a hidden page is unlisted but readable by path, as its URL is.
 - `metadata`, `label`, `corpus`, `noMatch` and `skills` are the app's: what a row adds, how a category is named, the sections its llms-full.txt is made of, what an empty search says, and the A2A skills.
 - Writes stay with each app, because who may write is the one thing no two of them agree on.
@@ -206,6 +207,7 @@ What it gets right:
 - **The preflight allow-list includes `Accept` and `Mcp-Protocol-Version`.** One missing entry fails the preflight rather than the POST, which presents as "the server is down".
 - **Batches are capped** (default 20) with a teaching error, because the rate limiter charges one token per HTTP request before the body is parsed. From 2025-06-18 on they are refused outright, because that revision removed them.
 - **Both protocol eras, one endpoint.** A request carrying `io.modelcontextprotocol/protocolVersion` in `params._meta` is served as `2026-07-28`: `server/discover`, per-request version and header validation (`-32022` naming every version spoken, `-32020` on a routing header that disagrees with the body), `resultType` and cache hints on results, and 404 for the methods that revision removed. Everything else is the legacy era, where `initialize` echoes the client's version when it is one of `2025-11-25`, `2025-06-18`, `2025-03-26` or `2024-11-05` and offers the newest otherwise. The spec permits a dual-era server, and it is the only way to adopt the new revision without failing the handshake of every client already in the field.
+- **The A2A call an agent card invites is answered.** Every card names this endpoint as its JSON-RPC `url`, so `message/send` (v0.3) and `SendMessage` (v1.0) get a message back: the result of the tool `answer` names (`{ tool: 'search_wiki', argument: 'query' }`), or `instructions` and the tool names without one. The task methods are `-32001`, since no task is ever created; streaming and push are `-32004`.
 - **The version is negotiated, not asserted.** Every response carries it back in `MCP-Protocol-Version`. Answering a constant is legal and still costs the caller structured output, tool titles and `_meta` without ever saying so.
 - **`Access-Control-Expose-Headers` is set.** Allow-Headers governs what a browser may send, Expose-Headers what it may read — without the second a browser client cannot see `Retry-After` on a 429, and a rate limit presents as a hang.
 - **The rate limit is declared, not wired.** Put `rateLimit: {capacity, refillPerSec}` on the config and `mcpResponse` enforces it before parsing the body, refuses with a JSON-RPC envelope, and states `RateLimit-Limit`/`-Remaining`/`-Reset` on every answer. Four routes had each transcribed that by hand through three differently-named local helpers, which is how a headroom header gets added to one surface and forgotten on the next.

package/dist/a2a.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/a2a.js

@@ -0,0 +1,95 @@
+// a2a.ts — the A2A calls an agent card invites, answered on the MCP endpoint.
+//
+// Every card here names the MCP endpoint as its `url` with `preferredTransport:
+// JSONRPC`, which to an A2A client means "send `message/send` here". The
+// endpoint answered -32601, so the card promised an interface the server then
+// refused: A2A clients and the registries that probe for them sent about 140
+// such calls per origin in a fortnight (October 2026) and got nothing back.
+// Now a message is answered with the site's own search, and the task methods
+// say plainly that no task exists, since every answer is a direct message.
+//
+// Both revisions in the field are spoken: v0.3 (`message/send`, a Message with
+// `kind`) and v1.0 (`SendMessage`, a `{ message }` with proto-JSON enums).
+import { McpToolError } from './mcp.js';
+const SEND = { 'message/send': '0.3', SendMessage: '1.0' };
+/** Task methods: none can succeed, because no task is ever created. */
+const TASK = new Set(['tasks/get', 'tasks/cancel', 'tasks/resubscribe', 'GetTask', 'CancelTask', 'SubscribeToTask']);
+/** Everything else either revision defines, which this server declines. */
+const UNSUPPORTED = new Set([
+    'message/stream',
+    'tasks/pushNotificationConfig/set',
+    'tasks/pushNotificationConfig/get',
+    'tasks/pushNotificationConfig/list',
+    'tasks/pushNotificationConfig/delete',
+    'agent/getAuthenticatedExtendedCard',
+    'SendStreamingMessage',
+    'ListTasks',
+    'CreateTaskPushNotificationConfig',
+    'GetTaskPushNotificationConfig',
+    'ListTaskPushNotificationConfigs',
+    'DeleteTaskPushNotificationConfig',
+    'GetExtendedAgentCard',
+]);
+/** @internal */
+export const isA2aMethod = (method) => method in SEND || TASK.has(method) || UNSUPPORTED.has(method);
+const error = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+/** The text of a message's text parts, whichever revision shaped them. */
+function textOf(message) {
+    const parts = message?.parts;
+    if (!Array.isArray(parts))
+        return '';
+    return parts
+        .map(p => (p && typeof p.text === 'string' ? p.text : ''))
+        .join(' ')
+        .trim();
+}
+/** What a message gets when there is no search to run: what this server is and how to use it. */
+const orientation = (config) => `${config.instructions}\n\nThis endpoint also speaks MCP (JSON-RPC over POST): send "initialize", then "tools/list". Tools: ${config.tools.map(t => t.name).join(', ')}.`;
+async function reply(text, config) {
+    const tool = config.answer && config.tools.find(t => t.name === config.answer.tool);
+    if (!text || !tool)
+        return { text: orientation(config) };
+    try {
+        const out = await tool.handler({ [config.answer.argument]: text }, {
+            meta: {},
+            setMeta: () => { },
+            protocolVersion: '2025-11-25',
+        });
+        const lead = `${config.serverInfo.name} ${tool.name} for ${JSON.stringify(text)}. For more, call this endpoint over MCP: "initialize", then "tools/list".`;
+        if (typeof out === 'string')
+            return { text: `${lead}\n\n${out}` };
+        // The text twin stays beside the data, as it does on an MCP tool result:
+        // a client that reads only text parts still has to be able to read the answer.
+        return { text: `${lead}\n\n${JSON.stringify(out, null, 2)}`, ...(out && typeof out === 'object' && !Array.isArray(out) ? { data: out } : {}) };
+    }
+    catch (err) {
+        if (err instanceof McpToolError)
+            return { text: `${err.message}\n\n${orientation(config)}` };
+        throw err;
+    }
+}
+/** Answer one A2A call. Only reached for a method `isA2aMethod` accepts. @internal */
+export async function handleA2a(req, config) {
+    const { id, method } = req;
+    if (TASK.has(method)) {
+        return error(id, -32001, 'Task not found: this agent keeps no tasks. Every message it is sent is answered directly with a message.');
+    }
+    const revision = SEND[method];
+    if (!revision) {
+        const send = method.includes('/') ? 'message/send' : 'SendMessage';
+        return error(id, -32004, `Unsupported operation: "${method}". This agent answers ${send} only, without streaming or push notifications.`);
+    }
+    const message = req.params?.message;
+    if (!message || typeof message !== 'object') {
+        return error(id, -32602, 'Missing params.message: send a message with at least one text part.');
+    }
+    const { text, data } = await reply(textOf(message), config);
+    const contextId = typeof message.contextId === 'string' ? message.contextId : crypto.randomUUID();
+    const messageId = crypto.randomUUID();
+    if (revision === '1.0') {
+        const parts = [{ text }, ...(data ? [{ data }] : [])];
+        return { jsonrpc: '2.0', id, result: { message: { messageId, contextId, role: 'ROLE_AGENT', parts } } };
+    }
+    const parts = [{ kind: 'text', text }, ...(data ? [{ kind: 'data', data }] : [])];
+    return { jsonrpc: '2.0', id, result: { kind: 'message', messageId, contextId, role: 'agent', parts } };
+}

package/dist/conformance.js

@@ -294,6 +294,13 @@ export async function agentCardParity(t) {
     const probe = await rawPost(endpoint, { jsonrpc: '2.0', id: 1, method: 'ping' });
     t.recordCall();
     t.check('agent card url is callable', (probe.headers.get('content-type') ?? '').includes('json'), `POST ${endpoint} -> ${probe.status} ${probe.headers.get('content-type')}`);
+    // Callable is not the same as answering. A `JSONRPC` url invites A2A's own
+    // first call, and a -32601 to it refuses the interface the card names.
+    const send = await t.rpcAt(endpoint, 'message/send', {
+        message: { kind: 'message', role: 'user', messageId: 'conformance', parts: [{ kind: 'text', text: String(a.name ?? 'help') }] },
+    });
+    const reply = send.result;
+    t.check('agent card url answers A2A', reply?.kind === 'message' && typeof reply.parts?.[0]?.text === 'string', reply ? `message/send -> ${reply.parts?.length} part(s)` : `message/send -> ${JSON.stringify(send.error)}`);
 }
 /**
  * Any surface an agent recrawls should answer a conditional GET with a 304.

package/dist/mcp.d.ts

@@ -179,6 +179,16 @@ export interface McpServerConfig {
      * clicks when they do not have one yet.
      */
     prompts?: McpPrompt[];
+    /**
+     * The tool an A2A `message/send` is answered with, and the argument its text
+     * fills: usually the search tool and its query. Without it a message is
+     * answered with `instructions` and the tool names, which is still an answer
+     * where -32601 was a refusal of the interface the agent card names.
+     */
+    answer?: {
+        tool: string;
+        argument: string;
+    };
     /** Appended to the GET refusal so a browser that lands here learns where to go. */
     docsUrl?: string;
     /**

package/dist/mcp.js

@@ -66,6 +66,7 @@ function requestProtocol(request) {
 }
 /** JSON-RPC batching was removed in 2025-06-18 and stays removed; it is legal only below that. */
 const allowsBatch = (v) => v === '2025-03-26' || v === '2024-11-05';
+import { handleA2a, isA2aMethod } from './a2a.js';
 import { clientKey, rateLimit, rateLimitHeaders, withRateLimit } from './rate-limit.js';
 /**
  * A tool as every surface advertises it — `tools/list`, the agent card and
@@ -418,6 +419,8 @@ async function handleRpc(req, config, dispatch) {
                 }
             }
             default:
+                if (isA2aMethod(method))
+                    return await handleA2a(req, config);
                 return methodNotFound(id, method, config, dispatch.era);
         }
     }
@@ -452,7 +455,7 @@ export async function handleMcp(body, config, dispatch = { protocolVersion: ASSU
 export const MCP_CORS = {
     'Access-Control-Allow-Origin': '*',
     'Access-Control-Allow-Methods': 'POST, OPTIONS',
-    'Access-Control-Allow-Headers': 'Content-Type, Accept, Authorization, Mcp-Session-Id, Mcp-Protocol-Version, Mcp-Method, Mcp-Name, Last-Event-ID',
+    'Access-Control-Allow-Headers': 'Content-Type, Accept, Authorization, Mcp-Session-Id, Mcp-Protocol-Version, Mcp-Method, Mcp-Name, Last-Event-ID, A2A-Version',
     // Allow-Headers governs what a browser may send; without Expose-Headers it
     // may read none of what comes back. A browser client could not see the
     // negotiated version, and could not see `Retry-After` on the 429 telling it

package/dist/store.d.ts

@@ -147,8 +147,8 @@ export declare function wikiStore<B extends DiffBlock = DiffBlock>(o: WikiStoreO
         items: {
             content: B[];
             title: string;
-            metadata: PageMetadata;
             id: string;
+            metadata: PageMetadata;
             tagPath: string;
             slug: string;
             siteId: string;

package/dist/well-known.js

@@ -84,10 +84,20 @@ export function agentCard(config) {
         // The endpoint, not the homepage. A card's `url` is where a client sends
         // its first call, and every card here pointed at an HTML page — so a client
         // that believed the card got markup back, or a 405. MCP is JSON-RPC over
-        // HTTP POST, so an A2A caller arriving at it is answered in a shape it can
-        // parse: a -32601 naming every method the server does implement.
+        // HTTP POST, and the endpoint answers A2A's `message/send` (v0.3) and
+        // `SendMessage` (v1.0) from the site's own search (`McpServerConfig.answer`).
         url: endpoint,
         preferredTransport: 'JSONRPC',
+        // v1.0 reads the interfaces from here and ignores `url`; v0.3 the reverse.
+        ...(mcpEndpoint === null
+            ? {}
+            : {
+                supportedInterfaces: ['1.0', '0.3'].map(protocolVersion => ({
+                    url: endpoint,
+                    protocolBinding: 'JSONRPC',
+                    protocolVersion,
+                })),
+            }),
         version,
         capabilities: { streaming: false, pushNotifications: false },
         skills,

package/dist/wiki-tools.d.ts

@@ -11,6 +11,13 @@ export interface WikiToolsOptions<B extends DiffBlock> {
     url: (tagPath: string, slug: string) => string;
     /** A page's blocks as plain prose: what `get_page` returns and `chars` counts. */
     text: (blocks: B[]) => string;
+    /**
+     * A page's blocks with what is read live filled in, such as a page list's
+     * pages: the resolver the app's page and markdown twin use. `get_page`,
+     * `get_pages` and the default corpus read their text through it, so a list
+     * reads there as it does on the twin rather than as its stored placeholder.
+     */
+    resolve?: (blocks: B[]) => Promise<B[]>;
     /** The wiki as the descriptions name it: "the Radix Wiki", "this DAO's wiki". */
     noun: string;
     /** The corpus document's heading. */

package/dist/wiki-tools.js

@@ -90,21 +90,23 @@ export function wikiReadTools(o) {
             hint: 'Paths are exact. Use search_wiki for a keyword, or list_pages with the tagPath to enumerate the branch.',
         });
     };
-    const full = (page) => ({
+    /** Blocks as the page shows them. */
+    const shown = (blocks) => (o.resolve ? o.resolve(blocks) : Promise.resolve(blocks));
+    const head = (page) => ({
         ...summary({ ...page, snippet: describe(openingText(page.content)) }),
         version: page.version,
-        content: o.text(page.content),
     });
+    const full = async (page) => ({ ...head(page), content: o.text(await shown(page.content)) });
     const sections = async (tagPath) => {
         if (o.corpus)
             return o.corpus(tagPath);
         const pages = (await store.corpus())
             .filter(p => !(p.tagPath === '' && p.slug === '') && (!tagPath || p.tagPath === tagPath || p.tagPath.startsWith(`${tagPath}/`)))
             .sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
-        return pages.map(p => {
+        return Promise.all(pages.map(async (p) => {
             const path = pathOf(p.tagPath, p.slug);
-            return { path, tagPath: p.tagPath, section: `## ${p.title}\n\nPath: ${path}\nURL: ${o.url(p.tagPath, p.slug)}\nUpdated: ${isoDate(p.updatedAt)}\n\n${o.text(p.content)}` };
-        });
+            return { path, tagPath: p.tagPath, section: `## ${p.title}\n\nPath: ${path}\nURL: ${o.url(p.tagPath, p.slug)}\nUpdated: ${isoDate(p.updatedAt)}\n\n${o.text(await shown(p.content))}` };
+        }));
     };
     const tools = [
         {
@@ -165,8 +167,9 @@ export function wikiReadTools(o) {
                 const r = readArgs(args);
                 const page = await named(r);
                 if (!r.bool('blocks'))
-                    return withAdjustments(r, full(page));
-                return withAdjustments(r, { ...full(page), id: page.id, content: page.content, metadata: page.metadata, ...o.forEdit?.(page) });
+                    return withAdjustments(r, await full(page));
+                // Stored, not resolved: what an edit sends back is what was stored.
+                return withAdjustments(r, { ...head(page), id: page.id, content: page.content, metadata: page.metadata, ...o.forEdit?.(page) });
             },
         },
         {
@@ -207,7 +210,7 @@ export function wikiReadTools(o) {
                         missing.push(input);
                         continue;
                     }
-                    const row = full(page);
+                    const row = await full(page);
                     // At least one page always comes back, so one oversized page can still be read.
                     if (pages.length && used + row.content.length > maxChars) {
                         omitted.push({ path: row.path, chars: row.content.length });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.69.0",
+  "version": "0.71.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, conditional-GET plumbing, and the headers and CSP every origin sends.",
   "type": "module",
   "license": "MIT",