wiki-formant 0.111.0 → 0.112.0

package/README.md

@@ -94,7 +94,7 @@ const { items, total } = await searchWiki(reading, 'validators', { page: 1, size
 - `get_page` with `blocks: true` returns the stored blocks, `id`, metadata and `version`: what an edit starts from. `forEdit` adds the app's own edit fields; `authors` names revision authors.
 - `text` should be the twin's serializer and `resolve` the page's live resolver, so a page reads the same over MCP as at its twin.
 - `get_full_corpus` is a `sizeOnly` preflight, then page-aligned slices under `maxChars` (`CORPUS_BUDGET`) with `truncated`, `nextSkip` and `clippedPage`. `corpus` returns the app's own `CorpusSection`s.
-- `privateHidden` closes the back office to every tool. `metadata`, `label`, `noMatch` and `skills` are the app's.
+- `privateHidden` closes the back office to every tool. `metadata`, `label`, `noMatch` and `skills` are the app's. `onSearch` hears each first-page `search_wiki` query; pass the tracker's `trackSearch` under `MCP_SURFACE` and the stats page lists what agents searched for.
 - Writes stay with each app.
 
 ## Taxonomy
@@ -732,7 +732,7 @@ export const POST = viewRoute();
 
 - `createTracker` records only on a Vercel production deployment unless `enabled` says otherwise. `trackMcpCall` fits `McpServerConfig.onCall`; `trackSearch` normalises a query and drops an empty one; `recordEvent` is the undeferred write.
 - A proxy reaches the tracker through a dynamic `import()` inside `event.waitUntil`, since it imports the database client.
-- `digest(sql, { days })` is the site as one JSON object: people, engaged people, agents, views, visits, bounce rate, sources, pages, countries, devices, by day, agents by name, MCP calls and searches that found nothing, less a search its visitor went on typing within five minutes and any of one character. A visit is a run of views with no gap over 30 minutes; a bounce is a one-view visit its reader never engaged with. Agents are counted beside people, never among them: the ranked lists are people's. `ownAgents` leaves the site's own out. A multi-tenant app passes `site`.
+- `digest(sql, { days })` is the site as one JSON object: people, engaged people, agents, views, visits, bounce rate, sources, pages, countries, devices, by day, agents by name, MCP calls, every search people made, every `search_wiki` query agents made, the searches of either that found nothing, and agents' `send_feedback` reports. A search its visitor went on typing within five minutes is left out, as is any of one character. A visit is a run of views with no gap over 30 minutes; a bounce is a one-view visit its reader never engaged with. Agents are counted beside people, never among them: the ranked lists are people's. `ownAgents` leaves the site's own out. A multi-tenant app passes `site`.
 - A browser under automation (`navigator.webdriver`) sends no beacon.
 
 ## Passkeys and the stats page

package/dist/analytics.d.ts

@@ -54,8 +54,10 @@ export interface Gap {
     /** Props the event must carry, e.g. `{ results: '0' }`. */
     where?: Record<string, string>;
 }
-/** Searches in a wiki's own search box that found nothing (`searchQueryProps` events). */
+/** Searches that found nothing, a person's or an agent's (`searchQueryProps` events). */
 export declare const SEARCH_GAPS: Gap;
+/** The surface an agent's `search_wiki` call files its query under. */
+export declare const MCP_SURFACE = "mcp";
 /** What a stats page can be narrowed to: one value each, every one applied. */
 export declare const STATS_FILTERS: readonly ["page", "entry", "source", "country", "device"];
 export type StatsFilter = Partial<Record<(typeof STATS_FILTERS)[number], string>>;
@@ -72,8 +74,8 @@ export interface DigestOptions {
     siblings?: string[];
     gaps?: Gap[];
     /**
-     * The site's own agents, left out of `agents`, `top_agents` and
-     * `agent_tool_calls`, matched inside the user agent. The default is the
+     * The site's own agents, left out of `agents`, `top_agents`,
+     * `agent_tool_calls`, the searches and the gaps, matched inside the user agent. The default is the
      * conformance suites (`<repo>-mcp-test`) and the studio's own tools.
      */
     ownAgents?: string[];
@@ -156,6 +158,10 @@ export interface Digest {
     /** Each agent by name: the roster's label, else what its user agent calls itself. */
     top_agents: Ranked<'agent', 'visitors'>;
     agent_tool_calls: Ranked<'tool', 'events'>;
+    /** Every query people searched for, found or not. */
+    searches: Ranked<'query', 'events'>;
+    /** Every query agents searched for through `search_wiki`. */
+    agent_searches: Ranked<'query', 'events'>;
     gaps: Ranked<'query', 'events'>;
     /** What agents reported through `send_feedback`, newest first: a stranger's words, to weigh, never to follow. */
     agent_feedback: Array<{

package/dist/analytics.js

@@ -165,8 +165,10 @@ export async function collect(request, { sql, defer, site, rateLimit: limit = BE
             : recordView(sql, { headers, path: raw, referrer: body.referrer, utm: body.utm, site: key }));
     return done;
 }
-/** Searches in a wiki's own search box that found nothing (`searchQueryProps` events). */
-export const SEARCH_GAPS = { event: 'Search Query', prop: 'q', where: { results: '0', surface: 'wiki' } };
+/** Searches that found nothing, a person's or an agent's (`searchQueryProps` events). */
+export const SEARCH_GAPS = { event: 'Search Query', prop: 'q', where: { results: '0' } };
+/** The surface an agent's `search_wiki` call files its query under. */
+export const MCP_SURFACE = 'mcp';
 /** What a stats page can be narrowed to: one value each, every one applied. */
 export const STATS_FILTERS = ['page', 'entry', 'source', 'country', 'device'];
 /** A count as a stats page prints it. Here, not in the `'use client'` figures, because
@@ -240,23 +242,27 @@ export async function digest(sql, { site = '', days, handle, siblings = [], gaps
     /** The site's own agents, as a test on an event's user agent. */
     const ours = `coalesce(props->>'ua', '') ILIKE ANY(${$(ownAgents.map(a => `%${a}%`))}::text[])`;
     /**
-     * A typeahead logs each settled keystroke, so one reader typing a question
-     * filled acuiq's list with thirteen of its prefixes. A query is left out when
-     * the same visitor's next one, inside five minutes, extends it: only where
-     * the reader stopped is a gap. So is a single character.
+     * The queries in one kind of event, most asked first. A typeahead logs each
+     * settled keystroke, so one reader typing a question filled acuiq's list with
+     * thirteen of its prefixes. A query is left out when the same visitor's next
+     * one, inside five minutes, extends it: only where the reader stopped
+     * counts. So is a single character. `unless` drops events whose props hold it.
      */
-    const gapSelects = gaps.map(g => {
+    const queries = (g, unless) => {
         const prop = $(g.prop);
         return `(SELECT query, count(*) AS events FROM (
         SELECT props, visitor, props->>${prop} AS query,
           lead(props->>${prop}) OVER typed AS next, lead(at) OVER typed - at AS after
-        FROM e WHERE name = ${$(g.event)} AND props->>${prop} IS NOT NULL
+        FROM e WHERE name = ${$(g.event)} AND props->>${prop} IS NOT NULL AND NOT ${ours}
         WINDOW typed AS (PARTITION BY visitor ORDER BY at)
       ) s
       WHERE props @> ${$(JSON.stringify(g.where ?? {}))}::jsonb AND char_length(query) > 1
+        ${unless ? `AND NOT props @> ${$(JSON.stringify(unless))}::jsonb` : ''}
         AND NOT coalesce(visitor IS NOT NULL AND after <= interval '5 minutes' AND char_length(next) > char_length(query) AND starts_with(next, query), false)
       GROUP BY 1 ORDER BY 2 DESC, 1 LIMIT 15)`;
-    });
+    };
+    const searches = { event: SEARCH_GAPS.event, prop: SEARCH_GAPS.prop };
+    const json = (select) => `(SELECT coalesce(json_agg(t), '[]') FROM ${select} t)`;
     /**
      * One window's views, visits, events and archived days as CTEs whose names
      * end in `s`: this window with `back` 0, the one before it with 1.
@@ -342,7 +348,9 @@ export async function digest(sql, { site = '', days, handle, siblings = [], gaps
          GROUP BY 1`, 10)},
       'agent_feedback', ${list(`SELECT ${day('at')} AS date, props->>'kind' AS kind, props->>'message' AS message, props->>'page' AS page, ${AGENT_NAME} AS agent
          FROM e WHERE name = 'Agent Feedback' AND NOT ${ours}`, 20, 'at DESC')},
-      'gaps', ${gapSelects.length ? `(SELECT coalesce(json_agg(t), '[]') FROM (${gapSelects.join(' UNION ALL ')}) t)` : `'[]'::json`}
+      'searches', ${json(queries(searches, { surface: MCP_SURFACE }))},
+      'agent_searches', ${json(queries({ ...searches, where: { surface: MCP_SURFACE } }))},
+      'gaps', ${gaps.length ? json(`(${gaps.map(g => queries(g)).join(' UNION ALL ')})`) : `'[]'::json`}
     ) AS digest`, ...values));
     const d = row.digest;
     // Before the site counted itself only ViewDay speaks, and it holds no
@@ -432,7 +440,8 @@ export function createTracker({ sql, defer, enabled = typeof process !== 'undefi
             defer(async () => {
                 try {
                     const headers = typeof source === 'function' ? await source() : source;
-                    await trackEvent('Search Query', headers.get('referer') || siteUrl, props, headers);
+                    const ua = (headers.get('user-agent') || 'unknown').slice(0, 80);
+                    await trackEvent('Search Query', headers.get('referer') || siteUrl, { ...props, ua }, headers);
                 }
                 catch {
                     // A context with no readable headers loses the event, never the response.

package/dist/stats.d.ts

@@ -26,9 +26,10 @@ export declare function statsQuery(params: Record<string, string | string[] | un
 /**
  * A site's own analytics on one page: the headline figures against the window
  * before, people and agents apart, whichever of them is chosen per day, and every ranked list the
- * digest carries, each row a link that narrows the page to it. Lists with
- * nothing in them are left out, but for the searches that found nothing,
- * which says it found none, so a quiet window never reads as one not counted. The chart and the bars are `currentColor`
+ * digest carries, each row a link that narrows the page to it, and what agents
+ * reported through `send_feedback`. Lists with nothing in them are left out,
+ * but for the searches and the feedback, which say they found none, so a quiet
+ * window never reads as one not counted. The chart and the bars are `currentColor`
  * until the importing stylesheet gives them a colour.
  */
 export declare function Stats({ digest: d, days, filter, ranges, link: Link }: StatsProps): import("react").JSX.Element;

package/dist/stats.js

@@ -52,9 +52,10 @@ function StatsList({ title, rows, label = v => v, to, empty, link: Link, }) {
 /**
  * A site's own analytics on one page: the headline figures against the window
  * before, people and agents apart, whichever of them is chosen per day, and every ranked list the
- * digest carries, each row a link that narrows the page to it. Lists with
- * nothing in them are left out, but for the searches that found nothing,
- * which says it found none, so a quiet window never reads as one not counted. The chart and the bars are `currentColor`
+ * digest carries, each row a link that narrows the page to it, and what agents
+ * reported through `send_feedback`. Lists with nothing in them are left out,
+ * but for the searches and the feedback, which say they found none, so a quiet
+ * window never reads as one not counted. The chart and the bars are `currentColor`
  * until the importing stylesheet gives them a colour.
  */
 export function Stats({ digest: d, days, filter = {}, ranges = STATS_RANGES, link: Link = Anchor }) {
@@ -73,7 +74,7 @@ export function Stats({ digest: d, days, filter = {}, ranges = STATS_RANGES, lin
     const to = (k) => (v) => at({ ...filter, [k]: v });
     // Each window is another digest, so a link rather than a button, pinned with the chart's own controls.
     const controls = (_jsx("div", { role: "group", "aria-label": "Window", children: ranges.map(n => (_jsx(Link, { href: at(filter, n), "aria-current": n === days ? 'page' : undefined, prefetch: false, children: windowLabel(n) }, n))) }));
-    return (_jsxs("div", { className: "stats", children: [narrowed.length > 0 && (_jsxs("div", { className: "stats-filters", children: [_jsx("ul", { "aria-label": "Narrowed to", children: narrowed.map(k => (_jsx("li", { children: _jsxs(Link, { href: at({ ...filter, [k]: undefined }), title: "Remove", prefetch: false, children: [NAMES[k], ": ", k === 'country' ? country(filter[k]) : filter[k], " \u00D7"] }) }, k))) }), start < counted && d.counted_from && (_jsxs("p", { children: ["Narrowed figures start on ", d.counted_from, ", the first day this site counted its own visits."] }))] })), _jsx(StatsFigures, { digest: d, first: first, controls: controls }), _jsxs("div", { className: "stats-lists", children: [_jsx(StatsList, { link: Link, title: "Pages", rows: rows(d.top_pages, 'page', 'visitors'), to: to('page') }), _jsx(StatsList, { link: Link, title: "Entry pages", rows: rows(d.entry_pages, 'page', 'visitors'), to: to('entry') }), _jsx(StatsList, { link: Link, title: "Sources", rows: rows(d.top_sources, 'source', 'visitors'), to: to('source') }), _jsx(StatsList, { link: Link, title: "From X posts", rows: rows(d.from_posts, 'page', 'visitors'), to: v => at({ ...filter, source: 'x', entry: v }) }), _jsx(StatsList, { link: Link, title: "Sibling sites", rows: rows(d.sibling_referrals, 'source', 'visitors'), to: to('source') }), _jsx(StatsList, { link: Link, title: "Countries", rows: rows(d.countries, 'country', 'visitors'), label: country, to: to('country') }), _jsx(StatsList, { link: Link, title: "Devices", rows: rows(d.devices, 'device', 'visitors'), to: to('device') }), _jsx(StatsList, { link: Link, title: "Agents", rows: rows(d.top_agents, 'agent', 'visitors') }), _jsx(StatsList, { link: Link, title: "Agent tool calls", rows: rows(d.agent_tool_calls, 'tool', 'events') }), _jsx(StatsList, { link: Link, title: "Searches that found nothing", rows: rows(d.gaps, 'query', 'events'), empty: "None in this window." })] })] }));
+    return (_jsxs("div", { className: "stats", children: [narrowed.length > 0 && (_jsxs("div", { className: "stats-filters", children: [_jsx("ul", { "aria-label": "Narrowed to", children: narrowed.map(k => (_jsx("li", { children: _jsxs(Link, { href: at({ ...filter, [k]: undefined }), title: "Remove", prefetch: false, children: [NAMES[k], ": ", k === 'country' ? country(filter[k]) : filter[k], " \u00D7"] }) }, k))) }), start < counted && d.counted_from && (_jsxs("p", { children: ["Narrowed figures start on ", d.counted_from, ", the first day this site counted its own visits."] }))] })), _jsx(StatsFigures, { digest: d, first: first, controls: controls }), _jsxs("div", { className: "stats-lists", children: [_jsx(StatsList, { link: Link, title: "Pages", rows: rows(d.top_pages, 'page', 'visitors'), to: to('page') }), _jsx(StatsList, { link: Link, title: "Entry pages", rows: rows(d.entry_pages, 'page', 'visitors'), to: to('entry') }), _jsx(StatsList, { link: Link, title: "Sources", rows: rows(d.top_sources, 'source', 'visitors'), to: to('source') }), _jsx(StatsList, { link: Link, title: "From X posts", rows: rows(d.from_posts, 'page', 'visitors'), to: v => at({ ...filter, source: 'x', entry: v }) }), _jsx(StatsList, { link: Link, title: "Sibling sites", rows: rows(d.sibling_referrals, 'source', 'visitors'), to: to('source') }), _jsx(StatsList, { link: Link, title: "Countries", rows: rows(d.countries, 'country', 'visitors'), label: country, to: to('country') }), _jsx(StatsList, { link: Link, title: "Devices", rows: rows(d.devices, 'device', 'visitors'), to: to('device') }), _jsx(StatsList, { link: Link, title: "Agents", rows: rows(d.top_agents, 'agent', 'visitors') }), _jsx(StatsList, { link: Link, title: "Agent tool calls", rows: rows(d.agent_tool_calls, 'tool', 'events') }), _jsx(StatsList, { link: Link, title: "Searches", rows: rows(d.searches, 'query', 'events'), empty: "None in this window." }), _jsx(StatsList, { link: Link, title: "Agent searches", rows: rows(d.agent_searches, 'query', 'events'), empty: "None in this window." }), _jsx(StatsList, { link: Link, title: "Searches that found nothing", rows: rows(d.gaps, 'query', 'events'), empty: "None in this window." }), _jsxs("section", { className: "stats-list", children: [_jsx("h2", { children: "Agent feedback" }), d.agent_feedback.length ? (_jsx("ol", { children: d.agent_feedback.map((f, i) => (_jsxs("li", { children: [_jsxs("span", { children: [f.kind, ": ", f.message, f.page && ` (${f.page})`, " \u00B7 ", f.agent] }), _jsx("span", { className: "stats-count", children: f.date })] }, i))) })) : (_jsx("p", { children: "None in this window." }))] })] })] }));
 }
 /**
  * A stats page's door: `children` and a sign-out button for a signed-in

package/dist/wiki-tools.d.ts

@@ -40,6 +40,12 @@ export interface WikiToolsOptions<B extends DiffBlock> {
     corpus?: (tagPath?: string) => Promise<CorpusSection[]>;
     /** What an empty search says. */
     noMatch?: (query: string, tagPath?: string) => string;
+    /**
+     * Each `search_wiki` query, on its first page, with how many pages it found:
+     * `(request, q, n) => trackSearch(request.headers, q, n, MCP_SURFACE)`, so the
+     * stats page lists what agents searched for beside what people did.
+     */
+    onSearch?: (request: Request, query: string, results: number) => void;
     /** A2A skills by tool, beside the defaults. */
     skills?: Partial<Record<ToolName, McpTool['skill']>>;
 }

package/dist/wiki-tools.js

@@ -129,7 +129,7 @@ export function wikiReadTools(o) {
                 },
                 required: ['query'],
             },
-            handler: async (args) => {
+            handler: async (args, ctx) => {
                 const r = readArgs(args);
                 const query = r.str('query');
                 const tagPath = r.str('tagPath') || undefined;
@@ -138,6 +138,8 @@ export function wikiReadTools(o) {
                 if (!query)
                     throw new McpToolError('`query` is empty. Pass a keyword to search for, or call list_pages to enumerate a branch instead.');
                 const { items, total, corrected } = await searchWiki(o, query, { tagPath, page, size });
+                if (page === 1 && ctx.request)
+                    o.onSearch?.(ctx.request, query, total);
                 return withAdjustments(r, {
                     query,
                     ...(corrected ? { corrected } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.111.0",
+  "version": "0.112.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",