wtf-p 0.6.0 → 0.7.0

package/vendors/codex/plugins/wtfp/tools/wtfp-tool.js

@@ -54,7 +54,7 @@ const COMMANDS = [
   {
     "command": "citation-search",
     "tool": "citation.fetch",
-    "usage": "citation-search --query=<text> [--limit=<1-25>] [--intent=<seminal|recent|balanced>] [--year=<yyyy>] [--timeout=<seconds>]",
+    "usage": "citation-search --query=<text> [--backend=<legacy|cite-nexus>] [--providers=<comma-separated-IDs>] [--limit=<1-25>] [--intent=<seminal|recent|balanced>] [--year=<yyyy>] [--timeout=<seconds>]",
     "effects": [
       "network.search"
     ]
@@ -96,9 +96,9 @@ function offlineRequested(argv) {
   return argv.includes('--offline') || flag === '1' || flag === 'true';
 }
 
-function fail(message) {
+function fail(message, status = 1) {
   process.stderr.write(`${JSON.stringify({ error: message })}\n`);
-  process.exit(1);
+  process.exit(status);
 }
 
 function emit(value) {
@@ -153,7 +153,7 @@ function requirePath(candidate) {
 
 function timeoutOf(flags) {
   if (!flags.has('timeout')) return DEFAULT_TIMEOUT_SECONDS;
-  const seconds = Number.parseInt(flags.get('timeout'), 10);
+  const seconds = /^\d+$/.test(flags.get('timeout')) ? Number(flags.get('timeout')) : NaN;
   if (!Number.isInteger(seconds) || seconds < 1 || seconds > MAX_TIMEOUT_SECONDS) {
     fail(`--timeout must be an integer number of seconds between 1 and ${MAX_TIMEOUT_SECONDS}`);
   }
@@ -184,7 +184,7 @@ function uniqueEntry(bib, content, key) {
 
 function limitOf(flags) {
   if (!flags.has('limit')) return 10;
-  const limit = Number.parseInt(flags.get('limit'), 10);
+  const limit = /^\d+$/.test(flags.get('limit')) ? Number(flags.get('limit')) : NaN;
   if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) fail(`--limit must be an integer between 1 and ${MAX_LIMIT}`);
   return limit;
 }
@@ -221,6 +221,13 @@ async function main(rawArgv) {
     fail(`${command} is refused in offline mode: it declares ${networkEffects.join(', ')}`);
   }
   const { flags, positional } = parseArguments(argv.slice(1));
+  const allowedFlags = {
+    'bib-index': ['key', 'query'], 'bib-format': ['key', 'style'],
+    'bib-impact': ['timeout'], 'citation-search': ['query', 'backend', 'providers', 'limit', 'intent', 'year', 'timeout'],
+    'scholar-search': ['query', 'limit', 'timeout'], 's2-search': ['query', 'limit', 'year', 'timeout'],
+    'rank': ['intent']
+  };
+  for (const key of flags.keys()) if (!allowedFlags[command].includes(key)) fail(`unknown --${key} for ${command}`);
   if (positional.length > 1) fail(`${command} accepts at most one positional argument: ${declared.usage}`);
   const load = () => require(MODULES[declared.tool]);
 
@@ -255,7 +262,11 @@ async function main(rawArgv) {
     const query = requireText(flags.get('query'), '--query');
     const year = yearOf(flags);
     const seconds = timeoutOf(flags);
-    return emit(await withTimeout(load().search(query, { limit: limitOf(flags), intent: intentOf(flags), ...(year ? { year } : {}) }), seconds, command));
+    const backend = flags.get('backend') || 'legacy';
+    if (!['legacy', 'cite-nexus'].includes(backend)) fail('--backend must be legacy or cite-nexus');
+    const providers = flags.has('providers') ? flags.get('providers').split(',').map((p) => p.trim()) : undefined;
+    if (providers && backend !== 'cite-nexus') fail('--providers requires --backend=cite-nexus');
+    return emit(await withTimeout(load().search(query, { backend, providers, timeoutSeconds: seconds, limit: limitOf(flags), intent: intentOf(flags), ...(year ? { year } : {}) }), seconds, command));
   }
   if (command === 'scholar-search') {
     if (positional.length > 0) fail(`${command} takes its query through --query: ${declared.usage}`);
@@ -282,5 +293,5 @@ async function main(rawArgv) {
 // config root as a custom-tool module; an unconditional main() printed a
 // dispatcher error and exited the host process at session start.
 if (require.main === module) {
-  main(process.argv.slice(2)).catch((error) => fail(error && error.message ? error.message : String(error)));
+  main(process.argv.slice(2)).catch((error) => fail(error && error.message ? error.message : String(error), error && error.code === 'WTFP_TIMEOUT' ? EXIT_TIMEOUT : 1));
 }

package/vendors/copilot/.wtfp-generated.json

@@ -2,11 +2,11 @@
   "schema": "wtfp.generated-adapter/v1",
   "generatorVersion": 5,
   "target": "copilot-marketplace",
-  "sourceHash": "416cee6696b3df0dbfc259233e4b9178d36b3498d23bdff4c7c81387047891c9",
+  "sourceHash": "b933037f9c8f8db38fa419255a7fb8b1a53752a9563cc4af3e2b0fcd04d0f68e",
   "files": [
     {
       "path": "marketplace.json",
-      "sha256": "79bd329e763f4ec0c2dd47d83a43bb982d94fbcb4a86382ed55b2fe818d7442c"
+      "sha256": "6fadbcf000495f705f889160e9af5fa917bcff26b0acd9a6e1803ba2b1255c81"
     },
     {
       "path": "project/.github/agents/wtfp-argument-verifier.agent.md",

package/vendors/copilot/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "WTF-P research workflow plugins",
-    "version": "0.6.0"
+    "version": "0.7.0"
   },
   "plugins": [
     {
       "name": "wtfp",
       "source": "./plugins/wtfp",
       "description": "Portable academic research and writing workflows.",
-      "version": "0.6.0",
+      "version": "0.7.0",
       "author": {
         "name": "akougkas"
       },

package/vendors/copilot/plugins/wtfp/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "wtfp",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Portable academic research and writing workflows with stable wtfp actions.",
   "author": {
     "name": "akougkas",

package/vendors/copilot/plugins/wtfp/.wtfp-generated.json

@@ -2,11 +2,11 @@
   "schema": "wtfp.generated-adapter/v1",
   "generatorVersion": 5,
   "target": "copilot",
-  "sourceHash": "05284b75607dc84c0c4bda35376047dd9bfa1acaf5d18a476947ed47431daca3",
+  "sourceHash": "592f78b5aa750de99e239898a484c196422501fe6628fb6deeae1f7c1fbf6912",
   "files": [
     {
       "path": ".claude-plugin/plugin.json",
-      "sha256": "1420ac38f0a3b75555b8922deef339df2b242e854ad0763c6d7af2e53ba9e0a4"
+      "sha256": "94c8c984c5fd89bdb9e9ce2e3569d3661e207b80491ab9d9be76afebf726883b"
     },
     {
       "path": "actions/add-todo.json",
@@ -646,7 +646,7 @@
     },
     {
       "path": "tools/citation/fetch.js",
-      "sha256": "56c92d67709d7fc21b8b6e00492ba7e22e60b402c36b4f1d0780a9cf45c56d7b"
+      "sha256": "fa24cc676bdad1699c1ef3ca56ac358268ec516a1aa1305ffe0760941ec8d756"
     },
     {
       "path": "tools/citation/rank.js",
@@ -662,11 +662,15 @@
     },
     {
       "path": "tools/README.md",
-      "sha256": "92e77815dd04a1b1df4606daefd76de5dba88a6351a3c8cd7810a94d70db8e2b"
+      "sha256": "997889703a61599a3d6267b1ddbd571ac354b55e7fe3a9dc2ebbf00b6c6d2106"
+    },
+    {
+      "path": "tools/support/cite-nexus-client.js",
+      "sha256": "9a7a9a548477b14cadda2be40ed95e579d809956e63ccf19092edde8de46d2dc"
     },
     {
       "path": "tools/wtfp-tool.js",
-      "sha256": "4eb713f525eb0b2c13ccc5b1126611039654927fdecfd76c5aa62dc232fcb8c6"
+      "sha256": "d7fe8278161d5a18f33be87a41c374e2a9c90657ac2315c24a1697793f750e19"
     },
     {
       "path": "workflows/add-todo.md",

package/vendors/copilot/plugins/wtfp/tools/README.md

@@ -2,7 +2,7 @@
 
 <!-- Generated by WTF-P adapter compiler v5 from protocol/tools.json; do not edit. -->
 
-Only implementations declared by `tools.json` are packaged here. Resolve each logical implementation URI through this exact mapping; do not search for or execute undeclared installer/compiler modules.
+Only implementations declared by `tools.json`, the dispatcher, and its private CiteNexus companion dependency are packaged here. Resolve each logical implementation URI through this exact mapping; do not search for or execute undeclared installer/compiler modules.
 
 - `wtfp://tools/bibliography/analyze-impact` → `tools/bibliography/analyze-impact.js` (legacy module `analyze-impact.js`)
 - `wtfp://tools/bibliography/format` → `tools/bibliography/format.js` (legacy module `bib-format.js`)
@@ -11,6 +11,7 @@ Only implementations declared by `tools.json` are packaged here. Resolve each lo
 - `wtfp://tools/citation/rank` → `tools/citation/rank.js` (legacy module `citation-ranker.js`)
 - `wtfp://tools/citation/scholar-lookup` → `tools/citation/scholar-lookup.js` (legacy module `scholar-lookup.js`)
 - `wtfp://tools/citation/semantic-scholar` → `tools/citation/semantic-scholar.js` (legacy module `semantic-scholar.js`)
+- Private dependency: `tools/support/cite-nexus-client.js`; reached only through `citation.fetch`, never executed directly.
 
 ## Executing a bundled tool
 
@@ -25,9 +26,11 @@ Run it with no argument, or with `list`, to print the declared command set as JS
 - `bib-index <bib-file> [--key=<citation-key>] [--query=<text>]` → `bibliography.index` (filesystem.read)
 - `bib-format <bib-file> --key=<citation-key> [--style=<bibtex|al-folio>]` → `bibliography.format` (filesystem.read)
 - `bib-impact <bib-file> [--timeout=<seconds>]` → `bibliography.analyze-impact` (filesystem.read, network.search)
-- `citation-search --query=<text> [--limit=<1-25>] [--intent=<seminal|recent|balanced>] [--year=<yyyy>] [--timeout=<seconds>]` → `citation.fetch` (network.search)
+- `citation-search --query=<text> [--backend=<legacy|cite-nexus>] [--providers=<comma-separated-IDs>] [--limit=<1-25>] [--intent=<seminal|recent|balanced>] [--year=<yyyy>] [--timeout=<seconds>]` → `citation.fetch` (network.search)
 - `scholar-search --query=<text> [--limit=<1-25>] [--timeout=<seconds>]` → `citation.scholar-lookup` (network.search)
 - `s2-search --query=<text> [--limit=<1-25>] [--year=<yyyy>] [--timeout=<seconds>]` → `citation.semantic-scholar` (network.fetch, network.search)
 - `rank <papers.json> [--intent=<seminal|recent|balanced>]` → `citation.rank` (no declared effects)
 
+For approved scholarly discovery, `citation-search --backend=cite-nexus --query="<topic>"` uses the separately installed `cite-nexus-wtfp` companion and its real MCP stdio server. Defaults are Crossref, DataCite and Europe PMC. Select optional vendors explicitly with `--providers`; include selected providers and query scope in the action approval. CiteNexus supports only balanced provider ordering, so omit `--intent` or use `--intent=balanced`. Results remain candidates: retain `citeNexus.sources`, field attribution, metrics, warnings and `metadata.errors`; do not infer verification or combine citation counts. The result limit is a displayed total; `metadata.total` counts the fetched deduplicated page, not the full corpus. Unavailable enrichment fails explicitly without falling back to another vendor. `WTFP_CITE_NEXUS_COMMAND` may name an absolute installed companion executable; it is operator configuration, never source content. No package is installed, server registered, or user profile changed by a tool call. Offline mode refuses this backend before process launch. Host capability blockers still apply.
+
 Every command prints one JSON document on stdout and reports failures as `{"error": "..."}` on stderr with exit status 1. Queries are capped at 512 characters, file paths at 4096, and result limits at 25. A symlinked file is accepted and read through its resolved target, which must be a regular file. Commands whose effects include `network.*` perform outbound requests to the declared scholarly indexes; pass `--offline` or set `WTFP_TOOL_OFFLINE=1` to refuse them, which is the mechanical form of "do not invoke a network-capable bibliography tool through a filesystem-only permission path". Each network command has a hard wall clock, `--timeout=<seconds>` (default 20, maximum 600); on expiry it reports `{"error": "<command> timed out after N s"}` on stderr and exits 124. `bib-impact` reports batch progress on stderr. `bib-index` flags repeated keys with `duplicate: true` and lists them under `duplicates`; `--key` refuses an ambiguous key. `bib-format` emits a standard BibTeX entry (`@article`, `@inproceedings`, ...) by default; `--style=al-folio` selects the Jekyll al-folio projection, which is not valid BibTeX. Do not execute any other module in this package directly, and do not pass a logical `project://` or `wtfp://` URI as a shell argument.

package/vendors/copilot/plugins/wtfp/tools/citation/fetch.js

@@ -160,6 +160,9 @@ function deduplicatePapers(papers) {
 // --- Main Search Logic ---
 
 async function search(query, options = {}) {
+  if (options.backend === 'cite-nexus') return require('../support/cite-nexus-client.js').search(query, options);
+  if (options.backend && options.backend !== 'legacy') throw new Error('Unknown citation backend');
+  if (options.providers) throw new Error('Provider selection requires --backend=cite-nexus');
   const limit = options.limit || 10;
   const intent = options.intent || 'balanced';
 
@@ -299,4 +302,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { search };
+module.exports = { search };

package/vendors/copilot/plugins/wtfp/tools/support/cite-nexus-client.js

@@ -0,0 +1,120 @@
+'use strict';
+
+// Optional companion to citation.fetch, never a separately executable tool.
+const { spawn } = require('child_process');
+const path = require('path');
+const SCHEMA = 'cite-nexus.wtfp/v1';
+const MAX_BYTES = 2 * 1024 * 1024;
+const PROVIDERS = Object.freeze({
+  crossref: ['CITE_NEXUS_CONTACT_EMAIL'], datacite: [], europe_pmc: [], arxiv: [],
+  semantic_scholar: ['SEMANTIC_SCHOLAR_API_KEY'], openalex: ['OPENALEX_API_KEY'],
+  serpapi: ['SERPAPI_API_KEY'], scopus: ['SCOPUS_API_KEY', 'SCOPUS_INSTTOKEN'], wos: ['WOS_API_KEY']
+});
+const RUNTIME_ENV = ['PATH', 'PATHEXT', 'SYSTEMROOT', 'WINDIR', 'LANG', 'LC_ALL', 'TMPDIR', 'TEMP', 'TMP'];
+
+function timedOut() {
+  return Object.assign(new Error('CiteNexus request timed out'), { code: 'WTFP_TIMEOUT' });
+}
+
+function requestFor(query, options) {
+  if (process.env.WTFP_TOOL_OFFLINE === '1' || process.env.WTFP_TOOL_OFFLINE === 'true') {
+    throw new Error('CiteNexus is unavailable in offline mode');
+  }
+  if (typeof query !== 'string' || !query.trim() || query.length > 512) throw new Error('CiteNexus query must contain 1-512 characters');
+  const limit = options.limit === undefined ? 10 : options.limit;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 25) throw new Error('CiteNexus limit must be an integer between 1 and 25');
+  const providers = options.providers || ['crossref', 'datacite', 'europe_pmc'];
+  if (!Array.isArray(providers) || providers.length < 1 || providers.length > 9 ||
+      providers.some((p) => typeof p !== 'string' || !Object.hasOwn(PROVIDERS, p))) {
+    throw new Error('CiteNexus providers must be a nonempty list of supported provider IDs');
+  }
+  const timeout = options.timeoutSeconds === undefined ? 20 : options.timeoutSeconds;
+  if (!Number.isInteger(timeout) || timeout < 1 || timeout > 600) throw new Error('CiteNexus timeout must be an integer between 1 and 600 seconds');
+  const request = { schema_version: SCHEMA, operation: 'search', query, limit, providers: [...new Set(providers)], timeout_seconds: timeout };
+  if (options.year != null) {
+    if (!/^\d{4}$/.test(String(options.year)) || Number(options.year) < 1000 || Number(options.year) > 2200) throw new Error('CiteNexus year must be between 1000 and 2200');
+    request.year = Number(options.year);
+  }
+  if (options.intent && options.intent !== 'balanced') throw new Error('CiteNexus preserves provider ordering; use --intent=balanced');
+  return request;
+}
+
+function validateResponse(text, limit) {
+  let data;
+  try { data = JSON.parse(text); } catch { throw new Error('CiteNexus returned malformed JSON'); }
+  const stack = [[data, 0]];
+  while (stack.length) {
+    const [value, depth] = stack.pop();
+    if (depth > 32) throw new Error('CiteNexus response nesting exceeds 32 levels');
+    if (value && typeof value === 'object') for (const child of Object.values(value)) stack.push([child, depth + 1]);
+  }
+  if (!data || data.schema_version !== SCHEMA || !Array.isArray(data.results) || data.results.length > limit ||
+      !data.metadata || data.metadata.backend !== 'cite-nexus' || !Array.isArray(data.metadata.errors) ||
+      data.metadata.returned !== data.results.length ||
+      data.results.some((p) => !p || p.verification !== 'candidate' || typeof p.title !== 'string' ||
+        typeof p.bibtex !== 'string' || !p.citeNexus || !Array.isArray(p.citeNexus.sources) || !Array.isArray(p.citeNexus.metrics))) {
+    throw new Error('CiteNexus returned an incompatible response; update both companions');
+  }
+  return data;
+}
+
+async function search(query, options = {}) {
+  const request = requestFor(query, options);
+  if (options.signal && options.signal.aborted) throw new Error('CiteNexus request cancelled');
+  const command = process.env.WTFP_CITE_NEXUS_COMMAND || 'cite-nexus-wtfp';
+  if (command !== 'cite-nexus-wtfp' && !path.isAbsolute(command)) {
+    throw new Error('WTFP_CITE_NEXUS_COMMAND must name an absolute installed executable');
+  }
+  const allowed = [...RUNTIME_ENV, ...request.providers.flatMap((p) => PROVIDERS[p])];
+  const env = Object.fromEntries(allowed.filter((key) => process.env[key] !== undefined).map((key) => [key, process.env[key]]));
+  return new Promise((resolve, reject) => {
+    // No shell, command arguments, URL or executable can arrive from source data.
+    const child = spawn(command, [], { env, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+    let settled = false, bytes = 0;
+    const chunks = [];
+    const stop = () => { if (child.exitCode === null) child.kill('SIGTERM'); };
+    const onExit = () => stop();
+    const onSignal = () => { stop(); process.exit(130); };
+    const finish = (error, data) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      process.removeListener('exit', onExit);
+      process.removeListener('SIGTERM', onSignal);
+      process.removeListener('SIGINT', onSignal);
+      if (options.signal) options.signal.removeEventListener('abort', cancel);
+      if (error) {
+        stop();
+        // The Python bridge cancels MCP and closes the SDK-owned server group.
+        const kill = setTimeout(() => child.kill('SIGKILL'), 7000);
+        kill.unref();
+        child.once('close', () => clearTimeout(kill));
+        reject(error);
+      } else resolve(data);
+    };
+    const cancel = () => finish(new Error('CiteNexus request cancelled'));
+    const timer = setTimeout(() => finish(timedOut()), request.timeout_seconds * 1000);
+    process.once('exit', onExit);
+    process.once('SIGTERM', onSignal);
+    process.once('SIGINT', onSignal);
+    if (options.signal) options.signal.addEventListener('abort', cancel, { once: true });
+    child.on('error', () => finish(new Error('CiteNexus companion unavailable; install cite-nexus-mcp 0.2.0 separately and run cite-nexus-wtfp --check')));
+    child.stdin.on('error', () => finish(new Error('CiteNexus companion closed its input')));
+    child.stdout.on('data', (chunk) => {
+      bytes += chunk.length;
+      if (bytes > MAX_BYTES) return finish(new Error('CiteNexus response exceeds 2 MiB'));
+      if (!settled) chunks.push(chunk);
+    });
+    // Drain, but never relay child stderr (it may contain sensitive diagnostics).
+    child.stderr.on('data', () => {});
+    child.on('close', (code) => {
+      if (settled) return;
+      if (code !== 0) return finish(code === 124 ? timedOut() : new Error('CiteNexus companion failed; run cite-nexus-wtfp --check'));
+      try { finish(null, validateResponse(Buffer.concat(chunks).toString('utf8'), request.limit)); }
+      catch (error) { finish(error); }
+    });
+    child.stdin.end(JSON.stringify(request));
+  });
+}
+
+module.exports = { search, requestFor, validateResponse };

package/vendors/copilot/plugins/wtfp/tools/wtfp-tool.js

@@ -54,7 +54,7 @@ const COMMANDS = [
   {
     "command": "citation-search",
     "tool": "citation.fetch",
-    "usage": "citation-search --query=<text> [--limit=<1-25>] [--intent=<seminal|recent|balanced>] [--year=<yyyy>] [--timeout=<seconds>]",
+    "usage": "citation-search --query=<text> [--backend=<legacy|cite-nexus>] [--providers=<comma-separated-IDs>] [--limit=<1-25>] [--intent=<seminal|recent|balanced>] [--year=<yyyy>] [--timeout=<seconds>]",
     "effects": [
       "network.search"
     ]
@@ -96,9 +96,9 @@ function offlineRequested(argv) {
   return argv.includes('--offline') || flag === '1' || flag === 'true';
 }
 
-function fail(message) {
+function fail(message, status = 1) {
   process.stderr.write(`${JSON.stringify({ error: message })}\n`);
-  process.exit(1);
+  process.exit(status);
 }
 
 function emit(value) {
@@ -153,7 +153,7 @@ function requirePath(candidate) {
 
 function timeoutOf(flags) {
   if (!flags.has('timeout')) return DEFAULT_TIMEOUT_SECONDS;
-  const seconds = Number.parseInt(flags.get('timeout'), 10);
+  const seconds = /^\d+$/.test(flags.get('timeout')) ? Number(flags.get('timeout')) : NaN;
   if (!Number.isInteger(seconds) || seconds < 1 || seconds > MAX_TIMEOUT_SECONDS) {
     fail(`--timeout must be an integer number of seconds between 1 and ${MAX_TIMEOUT_SECONDS}`);
   }
@@ -184,7 +184,7 @@ function uniqueEntry(bib, content, key) {
 
 function limitOf(flags) {
   if (!flags.has('limit')) return 10;
-  const limit = Number.parseInt(flags.get('limit'), 10);
+  const limit = /^\d+$/.test(flags.get('limit')) ? Number(flags.get('limit')) : NaN;
   if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) fail(`--limit must be an integer between 1 and ${MAX_LIMIT}`);
   return limit;
 }
@@ -221,6 +221,13 @@ async function main(rawArgv) {
     fail(`${command} is refused in offline mode: it declares ${networkEffects.join(', ')}`);
   }
   const { flags, positional } = parseArguments(argv.slice(1));
+  const allowedFlags = {
+    'bib-index': ['key', 'query'], 'bib-format': ['key', 'style'],
+    'bib-impact': ['timeout'], 'citation-search': ['query', 'backend', 'providers', 'limit', 'intent', 'year', 'timeout'],
+    'scholar-search': ['query', 'limit', 'timeout'], 's2-search': ['query', 'limit', 'year', 'timeout'],
+    'rank': ['intent']
+  };
+  for (const key of flags.keys()) if (!allowedFlags[command].includes(key)) fail(`unknown --${key} for ${command}`);
   if (positional.length > 1) fail(`${command} accepts at most one positional argument: ${declared.usage}`);
   const load = () => require(MODULES[declared.tool]);
 
@@ -255,7 +262,11 @@ async function main(rawArgv) {
     const query = requireText(flags.get('query'), '--query');
     const year = yearOf(flags);
     const seconds = timeoutOf(flags);
-    return emit(await withTimeout(load().search(query, { limit: limitOf(flags), intent: intentOf(flags), ...(year ? { year } : {}) }), seconds, command));
+    const backend = flags.get('backend') || 'legacy';
+    if (!['legacy', 'cite-nexus'].includes(backend)) fail('--backend must be legacy or cite-nexus');
+    const providers = flags.has('providers') ? flags.get('providers').split(',').map((p) => p.trim()) : undefined;
+    if (providers && backend !== 'cite-nexus') fail('--providers requires --backend=cite-nexus');
+    return emit(await withTimeout(load().search(query, { backend, providers, timeoutSeconds: seconds, limit: limitOf(flags), intent: intentOf(flags), ...(year ? { year } : {}) }), seconds, command));
   }
   if (command === 'scholar-search') {
     if (positional.length > 0) fail(`${command} takes its query through --query: ${declared.usage}`);
@@ -282,5 +293,5 @@ async function main(rawArgv) {
 // config root as a custom-tool module; an unconditional main() printed a
 // dispatcher error and exited the host process at session start.
 if (require.main === module) {
-  main(process.argv.slice(2)).catch((error) => fail(error && error.message ? error.message : String(error)));
+  main(process.argv.slice(2)).catch((error) => fail(error && error.message ? error.message : String(error), error && error.code === 'WTFP_TIMEOUT' ? EXIT_TIMEOUT : 1));
 }

package/vendors/gemini/.wtfp-generated.json

@@ -2,7 +2,7 @@
   "schema": "wtfp.generated-adapter/v1",
   "generatorVersion": 5,
   "target": "gemini",
-  "sourceHash": "de13c4e935dbcd02650338f2897395374f624300d84cfde3920061064e9748d1",
+  "sourceHash": "e2780b9dd2fdbad4667ec5248135caed0664bd3ec4122d0bac98ce1fdd762045",
   "files": [
     {
       "path": "actions/add-todo.json",
@@ -362,7 +362,7 @@
     },
     {
       "path": "gemini-extension.json",
-      "sha256": "c90755abe6ebf7656ee771d2f8726e25ebeaf0f160dccf60f082532a033297d9"
+      "sha256": "7d9e45fe44be4a5c910f491fa75ea479d8faf23ea27df916cad3884efd5eb64e"
     },
     {
       "path": "GEMINI.md",
@@ -650,7 +650,7 @@
     },
     {
       "path": "tools/citation/fetch.js",
-      "sha256": "56c92d67709d7fc21b8b6e00492ba7e22e60b402c36b4f1d0780a9cf45c56d7b"
+      "sha256": "fa24cc676bdad1699c1ef3ca56ac358268ec516a1aa1305ffe0760941ec8d756"
     },
     {
       "path": "tools/citation/rank.js",
@@ -666,11 +666,15 @@
     },
     {
       "path": "tools/README.md",
-      "sha256": "92e77815dd04a1b1df4606daefd76de5dba88a6351a3c8cd7810a94d70db8e2b"
+      "sha256": "997889703a61599a3d6267b1ddbd571ac354b55e7fe3a9dc2ebbf00b6c6d2106"
+    },
+    {
+      "path": "tools/support/cite-nexus-client.js",
+      "sha256": "9a7a9a548477b14cadda2be40ed95e579d809956e63ccf19092edde8de46d2dc"
     },
     {
       "path": "tools/wtfp-tool.js",
-      "sha256": "4eb713f525eb0b2c13ccc5b1126611039654927fdecfd76c5aa62dc232fcb8c6"
+      "sha256": "d7fe8278161d5a18f33be87a41c374e2a9c90657ac2315c24a1697793f750e19"
     },
     {
       "path": "workflows/add-todo.md",

package/vendors/gemini/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "wtfp",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Portable academic research and writing workflows for Gemini CLI.",
   "contextFileName": "GEMINI.md"
 }

package/vendors/gemini/tools/README.md

@@ -2,7 +2,7 @@
 
 <!-- Generated by WTF-P adapter compiler v5 from protocol/tools.json; do not edit. -->
 
-Only implementations declared by `tools.json` are packaged here. Resolve each logical implementation URI through this exact mapping; do not search for or execute undeclared installer/compiler modules.
+Only implementations declared by `tools.json`, the dispatcher, and its private CiteNexus companion dependency are packaged here. Resolve each logical implementation URI through this exact mapping; do not search for or execute undeclared installer/compiler modules.
 
 - `wtfp://tools/bibliography/analyze-impact` → `tools/bibliography/analyze-impact.js` (legacy module `analyze-impact.js`)
 - `wtfp://tools/bibliography/format` → `tools/bibliography/format.js` (legacy module `bib-format.js`)
@@ -11,6 +11,7 @@ Only implementations declared by `tools.json` are packaged here. Resolve each lo
 - `wtfp://tools/citation/rank` → `tools/citation/rank.js` (legacy module `citation-ranker.js`)
 - `wtfp://tools/citation/scholar-lookup` → `tools/citation/scholar-lookup.js` (legacy module `scholar-lookup.js`)
 - `wtfp://tools/citation/semantic-scholar` → `tools/citation/semantic-scholar.js` (legacy module `semantic-scholar.js`)
+- Private dependency: `tools/support/cite-nexus-client.js`; reached only through `citation.fetch`, never executed directly.
 
 ## Executing a bundled tool
 
@@ -25,9 +26,11 @@ Run it with no argument, or with `list`, to print the declared command set as JS
 - `bib-index <bib-file> [--key=<citation-key>] [--query=<text>]` → `bibliography.index` (filesystem.read)
 - `bib-format <bib-file> --key=<citation-key> [--style=<bibtex|al-folio>]` → `bibliography.format` (filesystem.read)
 - `bib-impact <bib-file> [--timeout=<seconds>]` → `bibliography.analyze-impact` (filesystem.read, network.search)
-- `citation-search --query=<text> [--limit=<1-25>] [--intent=<seminal|recent|balanced>] [--year=<yyyy>] [--timeout=<seconds>]` → `citation.fetch` (network.search)
+- `citation-search --query=<text> [--backend=<legacy|cite-nexus>] [--providers=<comma-separated-IDs>] [--limit=<1-25>] [--intent=<seminal|recent|balanced>] [--year=<yyyy>] [--timeout=<seconds>]` → `citation.fetch` (network.search)
 - `scholar-search --query=<text> [--limit=<1-25>] [--timeout=<seconds>]` → `citation.scholar-lookup` (network.search)
 - `s2-search --query=<text> [--limit=<1-25>] [--year=<yyyy>] [--timeout=<seconds>]` → `citation.semantic-scholar` (network.fetch, network.search)
 - `rank <papers.json> [--intent=<seminal|recent|balanced>]` → `citation.rank` (no declared effects)
 
+For approved scholarly discovery, `citation-search --backend=cite-nexus --query="<topic>"` uses the separately installed `cite-nexus-wtfp` companion and its real MCP stdio server. Defaults are Crossref, DataCite and Europe PMC. Select optional vendors explicitly with `--providers`; include selected providers and query scope in the action approval. CiteNexus supports only balanced provider ordering, so omit `--intent` or use `--intent=balanced`. Results remain candidates: retain `citeNexus.sources`, field attribution, metrics, warnings and `metadata.errors`; do not infer verification or combine citation counts. The result limit is a displayed total; `metadata.total` counts the fetched deduplicated page, not the full corpus. Unavailable enrichment fails explicitly without falling back to another vendor. `WTFP_CITE_NEXUS_COMMAND` may name an absolute installed companion executable; it is operator configuration, never source content. No package is installed, server registered, or user profile changed by a tool call. Offline mode refuses this backend before process launch. Host capability blockers still apply.
+
 Every command prints one JSON document on stdout and reports failures as `{"error": "..."}` on stderr with exit status 1. Queries are capped at 512 characters, file paths at 4096, and result limits at 25. A symlinked file is accepted and read through its resolved target, which must be a regular file. Commands whose effects include `network.*` perform outbound requests to the declared scholarly indexes; pass `--offline` or set `WTFP_TOOL_OFFLINE=1` to refuse them, which is the mechanical form of "do not invoke a network-capable bibliography tool through a filesystem-only permission path". Each network command has a hard wall clock, `--timeout=<seconds>` (default 20, maximum 600); on expiry it reports `{"error": "<command> timed out after N s"}` on stderr and exits 124. `bib-impact` reports batch progress on stderr. `bib-index` flags repeated keys with `duplicate: true` and lists them under `duplicates`; `--key` refuses an ambiguous key. `bib-format` emits a standard BibTeX entry (`@article`, `@inproceedings`, ...) by default; `--style=al-folio` selects the Jekyll al-folio projection, which is not valid BibTeX. Do not execute any other module in this package directly, and do not pass a logical `project://` or `wtfp://` URI as a shell argument.

package/vendors/gemini/tools/citation/fetch.js

@@ -160,6 +160,9 @@ function deduplicatePapers(papers) {
 // --- Main Search Logic ---
 
 async function search(query, options = {}) {
+  if (options.backend === 'cite-nexus') return require('../support/cite-nexus-client.js').search(query, options);
+  if (options.backend && options.backend !== 'legacy') throw new Error('Unknown citation backend');
+  if (options.providers) throw new Error('Provider selection requires --backend=cite-nexus');
   const limit = options.limit || 10;
   const intent = options.intent || 'balanced';
 
@@ -299,4 +302,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { search };
+module.exports = { search };

package/vendors/gemini/tools/support/cite-nexus-client.js

@@ -0,0 +1,120 @@
+'use strict';
+
+// Optional companion to citation.fetch, never a separately executable tool.
+const { spawn } = require('child_process');
+const path = require('path');
+const SCHEMA = 'cite-nexus.wtfp/v1';
+const MAX_BYTES = 2 * 1024 * 1024;
+const PROVIDERS = Object.freeze({
+  crossref: ['CITE_NEXUS_CONTACT_EMAIL'], datacite: [], europe_pmc: [], arxiv: [],
+  semantic_scholar: ['SEMANTIC_SCHOLAR_API_KEY'], openalex: ['OPENALEX_API_KEY'],
+  serpapi: ['SERPAPI_API_KEY'], scopus: ['SCOPUS_API_KEY', 'SCOPUS_INSTTOKEN'], wos: ['WOS_API_KEY']
+});
+const RUNTIME_ENV = ['PATH', 'PATHEXT', 'SYSTEMROOT', 'WINDIR', 'LANG', 'LC_ALL', 'TMPDIR', 'TEMP', 'TMP'];
+
+function timedOut() {
+  return Object.assign(new Error('CiteNexus request timed out'), { code: 'WTFP_TIMEOUT' });
+}
+
+function requestFor(query, options) {
+  if (process.env.WTFP_TOOL_OFFLINE === '1' || process.env.WTFP_TOOL_OFFLINE === 'true') {
+    throw new Error('CiteNexus is unavailable in offline mode');
+  }
+  if (typeof query !== 'string' || !query.trim() || query.length > 512) throw new Error('CiteNexus query must contain 1-512 characters');
+  const limit = options.limit === undefined ? 10 : options.limit;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 25) throw new Error('CiteNexus limit must be an integer between 1 and 25');
+  const providers = options.providers || ['crossref', 'datacite', 'europe_pmc'];
+  if (!Array.isArray(providers) || providers.length < 1 || providers.length > 9 ||
+      providers.some((p) => typeof p !== 'string' || !Object.hasOwn(PROVIDERS, p))) {
+    throw new Error('CiteNexus providers must be a nonempty list of supported provider IDs');
+  }
+  const timeout = options.timeoutSeconds === undefined ? 20 : options.timeoutSeconds;
+  if (!Number.isInteger(timeout) || timeout < 1 || timeout > 600) throw new Error('CiteNexus timeout must be an integer between 1 and 600 seconds');
+  const request = { schema_version: SCHEMA, operation: 'search', query, limit, providers: [...new Set(providers)], timeout_seconds: timeout };
+  if (options.year != null) {
+    if (!/^\d{4}$/.test(String(options.year)) || Number(options.year) < 1000 || Number(options.year) > 2200) throw new Error('CiteNexus year must be between 1000 and 2200');
+    request.year = Number(options.year);
+  }
+  if (options.intent && options.intent !== 'balanced') throw new Error('CiteNexus preserves provider ordering; use --intent=balanced');
+  return request;
+}
+
+function validateResponse(text, limit) {
+  let data;
+  try { data = JSON.parse(text); } catch { throw new Error('CiteNexus returned malformed JSON'); }
+  const stack = [[data, 0]];
+  while (stack.length) {
+    const [value, depth] = stack.pop();
+    if (depth > 32) throw new Error('CiteNexus response nesting exceeds 32 levels');
+    if (value && typeof value === 'object') for (const child of Object.values(value)) stack.push([child, depth + 1]);
+  }
+  if (!data || data.schema_version !== SCHEMA || !Array.isArray(data.results) || data.results.length > limit ||
+      !data.metadata || data.metadata.backend !== 'cite-nexus' || !Array.isArray(data.metadata.errors) ||
+      data.metadata.returned !== data.results.length ||
+      data.results.some((p) => !p || p.verification !== 'candidate' || typeof p.title !== 'string' ||
+        typeof p.bibtex !== 'string' || !p.citeNexus || !Array.isArray(p.citeNexus.sources) || !Array.isArray(p.citeNexus.metrics))) {
+    throw new Error('CiteNexus returned an incompatible response; update both companions');
+  }
+  return data;
+}
+
+async function search(query, options = {}) {
+  const request = requestFor(query, options);
+  if (options.signal && options.signal.aborted) throw new Error('CiteNexus request cancelled');
+  const command = process.env.WTFP_CITE_NEXUS_COMMAND || 'cite-nexus-wtfp';
+  if (command !== 'cite-nexus-wtfp' && !path.isAbsolute(command)) {
+    throw new Error('WTFP_CITE_NEXUS_COMMAND must name an absolute installed executable');
+  }
+  const allowed = [...RUNTIME_ENV, ...request.providers.flatMap((p) => PROVIDERS[p])];
+  const env = Object.fromEntries(allowed.filter((key) => process.env[key] !== undefined).map((key) => [key, process.env[key]]));
+  return new Promise((resolve, reject) => {
+    // No shell, command arguments, URL or executable can arrive from source data.
+    const child = spawn(command, [], { env, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+    let settled = false, bytes = 0;
+    const chunks = [];
+    const stop = () => { if (child.exitCode === null) child.kill('SIGTERM'); };
+    const onExit = () => stop();
+    const onSignal = () => { stop(); process.exit(130); };
+    const finish = (error, data) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      process.removeListener('exit', onExit);
+      process.removeListener('SIGTERM', onSignal);
+      process.removeListener('SIGINT', onSignal);
+      if (options.signal) options.signal.removeEventListener('abort', cancel);
+      if (error) {
+        stop();
+        // The Python bridge cancels MCP and closes the SDK-owned server group.
+        const kill = setTimeout(() => child.kill('SIGKILL'), 7000);
+        kill.unref();
+        child.once('close', () => clearTimeout(kill));
+        reject(error);
+      } else resolve(data);
+    };
+    const cancel = () => finish(new Error('CiteNexus request cancelled'));
+    const timer = setTimeout(() => finish(timedOut()), request.timeout_seconds * 1000);
+    process.once('exit', onExit);
+    process.once('SIGTERM', onSignal);
+    process.once('SIGINT', onSignal);
+    if (options.signal) options.signal.addEventListener('abort', cancel, { once: true });
+    child.on('error', () => finish(new Error('CiteNexus companion unavailable; install cite-nexus-mcp 0.2.0 separately and run cite-nexus-wtfp --check')));
+    child.stdin.on('error', () => finish(new Error('CiteNexus companion closed its input')));
+    child.stdout.on('data', (chunk) => {
+      bytes += chunk.length;
+      if (bytes > MAX_BYTES) return finish(new Error('CiteNexus response exceeds 2 MiB'));
+      if (!settled) chunks.push(chunk);
+    });
+    // Drain, but never relay child stderr (it may contain sensitive diagnostics).
+    child.stderr.on('data', () => {});
+    child.on('close', (code) => {
+      if (settled) return;
+      if (code !== 0) return finish(code === 124 ? timedOut() : new Error('CiteNexus companion failed; run cite-nexus-wtfp --check'));
+      try { finish(null, validateResponse(Buffer.concat(chunks).toString('utf8'), request.limit)); }
+      catch (error) { finish(error); }
+    });
+    child.stdin.end(JSON.stringify(request));
+  });
+}
+
+module.exports = { search, requestFor, validateResponse };