wtf-p 0.6.0 → 0.7.1

package/README.md

@@ -19,9 +19,16 @@ the scientific judgment. The agent keeps the bookkeeping and does bounded jobs.
 
 It ships as one canonical [Agent Plugins 1.0.0](https://agent-plugins.org)
 bundle that a deterministic compiler projects into a native package for seven
-coding-agent hosts. Version `0.6.0` is the first stable release of that
-design and is what npm `latest` resolves to; v0.5 remains installable by
-explicit version.
+coding-agent hosts. Version `0.7.1` is the current stable release and is
+what npm `latest` resolves to; v0.5 remains installable by explicit version.
+
+**Optional CiteNexus research backend (since 0.7.0):** `citation-search --backend=cite-nexus`
+queries Crossref, DataCite and Europe PMC by default, plus explicitly selected academic
+APIs, through the [CiteNexus](docs/CITE_NEXUS.md) MCP server. Results keep their source
+evidence and stay candidates. CiteNexus is a separate Python package
+(`pip install cite-nexus-mcp==0.2.0`) that WTF-P never installs for you. Research
+actions reach it on Clio Coder and Claude Code; the other hosts keep their existing
+capability blockers.
 
 ## Install on your agent
 
@@ -49,13 +56,13 @@ registers it with the host's native plugin lifecycle where one exists.
 
 | Host | Install | Native registration the installer performs | Verified with |
 | --- | --- | --- | --- |
-| Clio Coder (0.4.7 or newer) | `npx --yes --package=wtf-p@0.6.0 -- wtf-p install clio` | `clio-coder library install <staged-bundle> --user`, then `clio-coder library inspect wtfp --user --json` | 0.4.8 |
-| Claude Code | `npx --yes --package=wtf-p@0.6.0 -- wtf-p install claude` | `claude plugin marketplace add <root>/marketplaces/wtfp --scope user`, then `claude plugin install wtfp@wtfp --scope user -y` | 2.1.271 |
-| Codex | `npx --yes --package=wtf-p@0.6.0 -- wtf-p install codex` | `codex plugin marketplace add <root>/marketplaces/wtfp`, then `codex plugin add wtfp@wtfp --json`; agents copied to `$CODEX_HOME/agents/` | 0.153.3 |
-| GitHub Copilot CLI | `npx --yes --package=wtf-p@0.6.0 -- wtf-p install copilot` | `copilot plugin marketplace add <root>/marketplaces/wtfp`, then `copilot plugin install wtfp@wtfp` | 1.0.83 |
-| OpenCode | `npx --yes --package=wtf-p@0.6.0 -- wtf-p install opencode` | Files under the OpenCode config root; OpenCode discovers them by directory | 1.18.31 |
-| Antigravity CLI | `npx --yes --package=wtf-p@0.6.0 -- wtf-p install antigravity` | `agy plugin install <root>/sources/wtfp` | 1.2.2 |
-| Gemini CLI | `npx --yes --package=wtf-p@0.6.0 -- wtf-p install gemini` | Files under `<root>/extensions/wtfp`; Gemini discovers the extension by directory | 0.59.0 |
+| Clio Coder (0.4.7 or newer) | `npx --yes --package=wtf-p@0.7.1 -- wtf-p install clio` | `clio-coder library install <staged-bundle> --user`, then `clio-coder library inspect wtfp --user --json` | 0.4.9 (local build) |
+| Claude Code | `npx --yes --package=wtf-p@0.7.1 -- wtf-p install claude` | `claude plugin marketplace add <root>/marketplaces/wtfp --scope user`, then `claude plugin install wtfp@wtfp --scope user -y` | 2.1.274 |
+| Codex | `npx --yes --package=wtf-p@0.7.1 -- wtf-p install codex` | `codex plugin marketplace add <root>/marketplaces/wtfp`, then `codex plugin add wtfp@wtfp --json`; agents copied to `$CODEX_HOME/agents/` | 0.153.3 |
+| GitHub Copilot CLI | `npx --yes --package=wtf-p@0.7.1 -- wtf-p install copilot` | `copilot plugin marketplace add <root>/marketplaces/wtfp`, then `copilot plugin install wtfp@wtfp` | 1.0.85 |
+| OpenCode | `npx --yes --package=wtf-p@0.7.1 -- wtf-p install opencode` | Files under the OpenCode config root; OpenCode discovers them by directory | 1.18.31 |
+| Antigravity CLI | `npx --yes --package=wtf-p@0.7.1 -- wtf-p install antigravity` | `agy plugin install <root>/sources/wtfp` | 1.2.5 |
+| Gemini CLI | `npx --yes --package=wtf-p@0.7.1 -- wtf-p install gemini` | Files under `<root>/extensions/wtfp`; Gemini discovers the extension by directory | 0.60.0 |
 
 "Verified" means native discovery in a disposable profile on this exact
 envelope, with the commands recorded in
@@ -69,7 +76,7 @@ the old executable instead.
 ## Sixty-second start
 
 ```bash
-npx --yes --package=wtf-p@0.6.0 -- wtf-p install clio
+npx --yes --package=wtf-p@0.7.1 -- wtf-p install clio
 cd /path/to/your-paper-or-proposal
 clio-coder --autonomy suggest
 ```

package/bin/lib/adapter-compiler.js

@@ -1410,13 +1410,13 @@ function toolOutputPath(tool) {
 
 // The one command a host is ever asked to run. It resolves a logical tool id
 // through the packaged module map, bounds every argument, and prints JSON on
-// stdout. Nothing here shells out, writes a file, or reads a path the caller
-// did not name.
+// stdout. The explicit CiteNexus backend launches only its installed companion
+// without a shell. No tool writes a file or reads a path the caller did not name.
 const TOOL_COMMANDS = Object.freeze([
   { command: 'bib-index', tool: 'bibliography.index', usage: 'bib-index <bib-file> [--key=<citation-key>] [--query=<text>]' },
   { command: 'bib-format', tool: 'bibliography.format', usage: 'bib-format <bib-file> --key=<citation-key> [--style=<bibtex|al-folio>]' },
   { command: 'bib-impact', tool: 'bibliography.analyze-impact', usage: 'bib-impact <bib-file> [--timeout=<seconds>]' },
-  { command: 'citation-search', tool: 'citation.fetch', usage: 'citation-search --query=<text> [--limit=<1-25>] [--intent=<seminal|recent|balanced>] [--year=<yyyy>] [--timeout=<seconds>]' },
+  { command: 'citation-search', tool: 'citation.fetch', usage: 'citation-search --query=<text> [--backend=<legacy|cite-nexus>] [--providers=<comma-separated-IDs>] [--limit=<1-25>] [--intent=<seminal|recent|balanced>] [--year=<yyyy>] [--timeout=<seconds>]' },
   { command: 'scholar-search', tool: 'citation.scholar-lookup', usage: 'scholar-search --query=<text> [--limit=<1-25>] [--timeout=<seconds>]' },
   { command: 's2-search', tool: 'citation.semantic-scholar', usage: 's2-search --query=<text> [--limit=<1-25>] [--year=<yyyy>] [--timeout=<seconds>]' },
   { command: 'rank', tool: 'citation.rank', usage: 'rank <papers.json> [--intent=<seminal|recent|balanced>]' }
@@ -1463,9 +1463,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) {
@@ -1520,7 +1520,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}\`);
   }
@@ -1551,7 +1551,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;
 }
@@ -1588,6 +1588,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]);
 
@@ -1622,7 +1629,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}\`);
@@ -1649,7 +1660,7 @@ 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));
 }
 `;
 }
@@ -1657,6 +1668,10 @@ if (require.main === module) {
 function addToolBundle(plan) {
   const registry = readJson(path.join(PROTOCOL_ROOT, 'tools.json'));
   const byLegacyName = new Map(registry.tools.map((tool) => [tool.legacyName, toolOutputPath(tool)]));
+  // One private companion dependency, owned and hashed with every envelope.
+  // It is not a logical tool and receives no independent execution grant.
+  byLegacyName.set('cite-nexus-client', 'tools/support/cite-nexus-client.js');
+  addFile(plan, 'tools/support/cite-nexus-client.js', fs.readFileSync(path.join(ROOT, 'bin', 'lib', 'cite-nexus-client.js'), 'utf8'));
   const byToolId = new Map(registry.tools.map((tool) => [tool.id, toolOutputPath(tool)]));
   const effectsByToolId = new Map(registry.tools.map((tool) => [tool.id, [...tool.effects]]));
   for (const entry of TOOL_COMMANDS) {
@@ -1689,9 +1704,10 @@ function addToolBundle(plan) {
     '',
     generatedBanner('protocol', 'tools.json'),
     '',
-    '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.',
     '',
     ...rows,
+    '- Private dependency: `tools/support/cite-nexus-client.js`; reached only through `citation.fetch`, never executed directly.',
     '',
     '## Executing a bundled tool',
     '',
@@ -1705,6 +1721,8 @@ function addToolBundle(plan) {
     '',
     ...TOOL_COMMANDS.map((entry) => `- \`${entry.usage}\` → \`${entry.tool}\` (${effectsByToolId.get(entry.tool).length > 0 ? effectsByToolId.get(entry.tool).join(', ') : '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.',
     ''
   ].join('\n'));

package/bin/lib/citation-fetcher.js

@@ -160,6 +160,9 @@ function deduplicatePapers(papers) {
 // --- Main Search Logic ---
 
 async function search(query, options = {}) {
+  if (options.backend === 'cite-nexus') return require('./cite-nexus-client').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/bin/lib/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wtf-p",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Portable, evidence-grounded academic writing workflows (papers, proposals, posters, presentations) for Clio Coder, Claude Code, Codex, GitHub Copilot CLI, OpenCode, Antigravity CLI, and Gemini CLI.",
   "bin": {
     "wtfp": "bin/install.js",
@@ -11,7 +11,7 @@
     "build:adapters": "node scripts/build-adapters.js",
     "check:adapters": "node scripts/build-adapters.js --check",
     "test:evaluation": "node evaluation/tools/lint.js && node test/compiler-v4-evidence.test.js && node test/dynamo-lifecycle-evidence.test.js && node test/evaluation-comparison.test.js && node test/evaluation.test.js && node test/evaluation-routing-runner.test.js && node test/evaluation-lifecycle.test.js && node test/evaluation-fleets.test.js && node test/nsf25-531-proposal-uat.test.js",
-    "test:tools": "node test/lib/bib-index.test.js && node test/lib/bib-format.test.js && node test/lib/citation-ranker.test.js && node test/lib/analyze-impact.test.js && node test/lib/scholar-lookup.test.js && node test/lib/semantic-scholar.test.js && node test/lib/citation-fetcher.test.js",
+    "test:tools": "node test/lib/bib-index.test.js && node test/lib/bib-format.test.js && node test/lib/citation-ranker.test.js && node test/lib/analyze-impact.test.js && node test/lib/scholar-lookup.test.js && node test/lib/semantic-scholar.test.js && node test/lib/citation-fetcher.test.js && node test/lib/cite-nexus-client.test.js",
     "test:protocol": "node test/protocol-catalog.test.js && node test/canonical-workflows.test.js && node test/portable-roles.test.js && node test/project-protocol.test.js && node test/test-skills.test.js && npm run test:tools && npm run test:evaluation && node test/adapter-compiler.test.js && node test/tool-dispatcher.test.js",
     "test:installer": "node test/import-safety.test.js && node test/ownership.test.js && node test/ownership-races.test.js && node test/status-partial.test.js && node test/paths.js && node test/modern-targets.test.js && node test/clio-installer.test.js && node test/installer.test.js",
     "test:compatibility": "node test/sanity.js && node test/linter.js && node test/dry-run.js && node test/feature-tests.js",

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

@@ -2,7 +2,7 @@
   "schema": "wtfp.generated-adapter/v1",
   "generatorVersion": 5,
   "target": "antigravity",
-  "sourceHash": "a189e7094e5c62db7ff8da9c4c6146c6c131ea5cbd9345ff3c4031d3a9e9a371",
+  "sourceHash": "fd300ebe88a80d19a91efd0d8e22700782eceec0728584e5d1004a54794804a7",
   "files": [
     {
       "path": "actions/add-todo.json",
@@ -362,7 +362,7 @@
     },
     {
       "path": "plugin.json",
-      "sha256": "c025a56dccbfb22881924e0b776161423b030944bea4ada3b3cf473e25a97035"
+      "sha256": "1017fe85464c00f4d1f2ad8ac23c1aace4f2edfccccd264b7ba6580568dc42bf"
     },
     {
       "path": "project/README.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/antigravity/plugin.json

@@ -1,5 +1,5 @@
 {
   "$schema": "https://antigravity.google/schemas/v1/plugin.json",
   "name": "wtfp",
-  "description": "Portable academic research and writing workflows (WTF-P 0.6.0)."
+  "description": "Portable academic research and writing workflows (WTF-P 0.7.1)."
 }

package/vendors/antigravity/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/antigravity/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/antigravity/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/antigravity/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));
 }