@aiwg/cli 2026.10.14 → 2026.10.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/agentic/code/addons/aiwg-utils/rules/anti-laziness.core.md +13 -0
  2. package/agentic/code/addons/aiwg-utils/rules/anti-laziness.md +118 -0
  3. package/dist/src/artifacts/corpus-tools/cli.js +32 -0
  4. package/dist/src/artifacts/corpus-tools/discovery-log.js +1 -1
  5. package/dist/src/artifacts/corpus-tools/expand-cli.js +89 -0
  6. package/dist/src/artifacts/corpus-tools/expand-queue.js +38 -0
  7. package/dist/src/artifacts/corpus-tools/expand-state.js +40 -0
  8. package/dist/src/artifacts/corpus-tools/expand.js +125 -0
  9. package/dist/src/artifacts/corpus-tools/resolve-cli.js +91 -0
  10. package/dist/src/artifacts/corpus-tools/resolve-corpus.js +41 -0
  11. package/dist/src/artifacts/corpus-tools/resolve.js +105 -0
  12. package/dist/src/cli/handlers/doctor-args.js +40 -0
  13. package/dist/src/cli/handlers/doctor-help.js +4 -2
  14. package/dist/src/cli/handlers/utilities.js +5 -31
  15. package/dist/src/config/worker-context.js +33 -4
  16. package/dist/src/decision/heldout/collector.js +1 -1
  17. package/dist/src/features/catalog.js +1 -1
  18. package/dist/src/gates/evaluate.js +2 -2
  19. package/dist/src/gates/heldout.js +42 -0
  20. package/dist/src/gates/index.js +2 -1
  21. package/dist/src/models/worker-installation-store.mjs +228 -0
  22. package/dist/src/models/worker-installation.mjs +7 -162
  23. package/dist/src/providers/provider-definitions.js +10 -10
  24. package/dist/src/research/clients/arxiv.js +10 -4
  25. package/dist/src/research/clients/base.js +5 -4
  26. package/dist/src/research/clients/crossref.js +9 -1
  27. package/dist/src/research/clients/semantic-scholar.js +73 -44
  28. package/dist/src/research/identity.js +85 -0
  29. package/dist/src/research/index.js +1 -0
  30. package/dist/src/research/reference-match.js +89 -0
  31. package/dist/src/rules/core-startup.d.mts +2 -0
  32. package/dist/src/rules/core-startup.mjs +31 -0
  33. package/dist/src/smiths/context-pipeline/agents-md.js +34 -0
  34. package/dist/src/smiths/context-pipeline/aiwg-md.js +3 -0
  35. package/dist/src/smiths/context-pipeline/bridge-ownership.js +50 -0
  36. package/dist/src/smiths/context-pipeline/generator.js +40 -104
  37. package/dist/src/smiths/context-pipeline/managed-hook.js +10 -0
  38. package/package.json +4 -2
  39. package/tools/agents/deploy-agents.mjs +2 -123
  40. package/tools/agents/providers/antigravity.mjs +1 -1
  41. package/tools/agents/providers/context-write.mjs +12 -0
  42. package/tools/agents/providers/grok-build.mjs +8 -5
  43. package/tools/agents/providers/hermes-skill-lifecycle.mjs +144 -0
  44. package/tools/agents/providers/hermes-startup.mjs +209 -0
  45. package/tools/agents/providers/hermes.mjs +9 -359
  46. package/tools/agents/providers/model-wrapper.mjs +5 -1
  47. package/tools/agents/providers/muse.mjs +3 -3
  48. package/tools/agents/providers/pi.mjs +1 -1
  49. package/tools/agents/providers/rule-delivery.mjs +23 -225
  50. package/tools/agents/providers/rule-presentation.mjs +13 -4
  51. package/tools/agents/providers/rule-projection.mjs +119 -0
  52. package/tools/agents/providers/rule-startup.mjs +70 -0
  53. package/tools/agents/providers/stale-artifact-prune.mjs +128 -0
  54. package/tools/agents/providers/warp.mjs +2 -2
  55. package/tools/agents/providers/windsurf.mjs +11 -57
  56. package/tools/plugin/plugin-links.mjs +3 -0
@@ -1,10 +1,10 @@
1
+ import { canonicalFuturePath, inside, readInstalledFile, installationStorePath, assertTrustedStore, readInstallationStore, withWorkerInstallationStore, writeWorkerInstallationStore, retainWorkerApprovals } from './worker-installation-store.mjs';
2
+ export { prepareWorkerInstallationStore } from './worker-installation-store.mjs';
1
3
  /** Shared installed-worker qualification owner, also used by the Ralph compatibility facade. */
2
4
  import { spawn } from 'node:child_process';
3
5
  import { buildInstalledWorkerTransport } from './worker-artifact-binding.mjs';
4
- import { constants } from 'node:fs';
5
- import { open, realpath, lstat, mkdir, rename, writeFile, unlink } from 'node:fs/promises';
6
+ import { open, realpath, lstat } from 'node:fs/promises';
6
7
  import path from 'node:path';
7
- import { homedir } from 'node:os';
8
8
  import { pathToFileURL } from 'node:url';
9
9
  import { createHash } from 'node:crypto';
10
10
  import { parse } from 'acorn';
@@ -225,7 +225,6 @@ const providerRegistry = new Map();
225
225
  const installedModules = new Map();
226
226
  let installedLoad = Promise.resolve();
227
227
  // Same default byte ceiling as workerAdapter.catalogAdapter.maxBytes.
228
- const installedModuleMaxBytes = 5 * 1024 * 1024;
229
228
 
230
229
  async function binaryIdentity(filename, workerWritableRoots) {
231
230
  if (typeof filename !== 'string' || !path.isAbsolute(filename) || filename.includes('\0')) throw new Error('Absolute installed binary required');
@@ -254,20 +253,6 @@ async function binaryIdentity(filename, workerWritableRoots) {
254
253
  } finally { await handle.close(); }
255
254
  }
256
255
 
257
- // Resolve existing ancestors too: a not-yet-created output can traverse a symlink.
258
- async function canonicalFuturePath(filename) {
259
- try { return await realpath(filename); }
260
- catch (error) {
261
- if (error.code !== 'ENOENT') throw error;
262
- // A dangling link is not a new output: following it may leave the scope.
263
- try { if ((await lstat(filename)).isSymbolicLink()) throw new Error('Dangling worker path'); }
264
- catch (statError) { if (statError.code !== 'ENOENT') throw statError; }
265
- const parent = path.dirname(filename);
266
- if (parent === filename) throw error;
267
- return path.join(await canonicalFuturePath(parent), path.basename(filename));
268
- }
269
- }
270
-
271
256
  export async function inspectWorkerInstallation(instance, request) {
272
257
  const { inspectWorkerInvocationProfile, requiredWorkerControls, isOperatorQualifiedWorkerAdapter } = await import('./provider-policy.js');
273
258
  const { qualificationDigest } = await import('./qualification-digest.mjs');
@@ -504,11 +489,6 @@ function runBoundedVersionProbe(executable, argv, environment, cwd, timeoutMs, m
504
489
  });
505
490
  }
506
491
 
507
- function inside(root, target) {
508
- const relative = path.relative(root, target);
509
- return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
510
- }
511
-
512
492
  // Inspect syntax without executing module bodies (including top-level effects).
513
493
  // Only statically declared interfaceVersion and callable register exports qualify.
514
494
  function checkInstalledExports(source) {
@@ -559,27 +539,6 @@ function checkInstalledExports(source) {
559
539
  inspect(ast);
560
540
  }
561
541
 
562
- async function readInstalledFile(filename) {
563
- const file = await open(filename, 'r');
564
- try {
565
- const stat = await file.stat();
566
- if (!stat.isFile()) throw new Error('Installed module inputs must be regular files');
567
- if (stat.size > installedModuleMaxBytes) throw new Error('Installed module input exceeds maxBytes (5 MiB)');
568
- // Bound the actual read too: an fstat size check alone allows concurrent growth.
569
- const bytes = Buffer.alloc(installedModuleMaxBytes + 1);
570
- let length = 0;
571
- while (length < bytes.length) {
572
- const { bytesRead } = await file.read(bytes, length, bytes.length - length, null);
573
- if (!bytesRead) break;
574
- length += bytesRead;
575
- }
576
- if (length > installedModuleMaxBytes) throw new Error('Installed module input exceeds maxBytes (5 MiB)');
577
- return bytes.subarray(0, length);
578
- } finally {
579
- await file.close();
580
- }
581
- }
582
-
583
542
  async function inspectInstalledModule(entry, workerWritableRoots, platform) {
584
543
  if (!entry || !/^installed:[a-z][a-z0-9-]{0,62}$/.test(entry.reference)
585
544
  || typeof entry.packageName !== 'string' || !entry.packageName
@@ -757,74 +716,6 @@ export function hasProvider(name) {
757
716
 
758
717
  // This host-owned record extends the installation owner. It is not project
759
718
  // configuration and never accepts module locations from models.json/aiwg.config.
760
- function installationStorePath() {
761
- const root = process.env.AIWG_CONFIG || path.join(homedir(), '.config/aiwg');
762
- if (!path.isAbsolute(root)) throw new Error('Installation store must be absolute');
763
- return path.join(root, 'worker-installations.json');
764
- }
765
-
766
- // HOME is the operator's trust boundary; custom stores outside it are checked
767
- // back to /. O_NOFOLLOW on the store itself does not protect its ancestors.
768
- async function assertTrustedStoreAncestors(directory) {
769
- const home = path.resolve(homedir());
770
- const boundary = inside(home, directory) ? home : path.parse(directory).root;
771
- // The store directory itself is checked by the caller.
772
- if (directory === boundary) return;
773
- const ancestors = [];
774
- for (let target = path.dirname(directory); ; target = path.dirname(target)) {
775
- ancestors.push(target);
776
- if (target === boundary) break;
777
- }
778
- for (const target of ancestors.reverse()) {
779
- const stat = await lstat(target);
780
- if (!stat.isDirectory() || stat.isSymbolicLink() || stat.mode & 0o022
781
- || process.getuid && stat.uid !== 0 && stat.uid !== process.getuid()) {
782
- throw new Error(`Untrusted installation store ancestor: ${target}`);
783
- }
784
- }
785
- }
786
-
787
- async function assertTrustedStore(filename, writableRoots, repairDirectory = false, apply = false) {
788
- const changes = [];
789
- const canonical = await canonicalFuturePath(filename);
790
- if (canonical !== filename) throw new Error('Symlinked installation store');
791
- for (const root of writableRoots) {
792
- if (inside(await realpath(root), canonical)) throw new Error('Worker-writable installation store');
793
- }
794
- for (const target of [path.dirname(filename), filename]) {
795
- try {
796
- const stat = await lstat(target);
797
- if (process.getuid && stat.uid !== process.getuid()) throw new Error(`Installation store path is owned by another user: ${target}`);
798
- if (stat.isSymbolicLink() || stat.isFile() && stat.nlink !== 1
799
- || target === path.dirname(filename) && !stat.isDirectory()
800
- || target === filename && !stat.isFile()) throw new Error(`Untrusted installation store permissions: ${target}`);
801
- if (stat.mode & 0o022) {
802
- if (!repairDirectory || target !== path.dirname(filename) || !process.getuid) {
803
- throw new Error(`Untrusted installation store permissions: ${target}`);
804
- }
805
- await assertTrustedStoreAncestors(target);
806
- changes.push({ path: target, action: 'chmod go-w' });
807
- if (apply) {
808
- const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_DIRECTORY);
809
- try {
810
- const current = await handle.stat();
811
- if (current.uid !== process.getuid() || current.ino !== stat.ino || current.dev !== stat.dev) {
812
- throw new Error(`Installation store directory changed: ${target}`);
813
- }
814
- await handle.chmod(current.mode & ~0o022);
815
- } finally { await handle.close(); }
816
- }
817
- }
818
- } catch (error) { if (error.code !== 'ENOENT') throw error; }
819
- }
820
- return changes;
821
- }
822
-
823
- /** Qualification's confirmed write may secure its own directory; ordinary readers never repair. */
824
- export async function prepareWorkerInstallationStore({ workerWritableRoots, apply = false }) {
825
- return assertTrustedStore(installationStorePath(), workerWritableRoots, true, apply);
826
- }
827
-
828
719
  // Use the existing delivery ledger's host-selected keyring, never public keys
829
720
  // supplied by a registration. PAE separates this authority from effect records.
830
721
  const qualificationPayloadType = 'application/vnd.aiwg.worker-installation-qualification+json';
@@ -859,22 +750,6 @@ async function qualificationSignatureFailure(record, trust) {
859
750
  return result === 'ok' ? null : result === 'signature-invalid' ? result : `signature-${result}`;
860
751
  }
861
752
 
862
- async function readInstallationStore(filename, expectedDigest) {
863
- try {
864
- const bytes = await readInstalledFile(filename);
865
- const digest = `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
866
- if (expectedDigest !== undefined && digest !== expectedDigest) throw new Error('Installation store binding changed');
867
- const stored = JSON.parse(bytes.toString('utf8'));
868
- if (stored.version !== 1 || !Array.isArray(stored.registrations) || stored.registrations.length > 128) {
869
- throw new Error('Unsupported installation record');
870
- }
871
- return { stored, digest };
872
- } catch (error) {
873
- if (error.code === 'ENOENT' && expectedDigest === undefined) return { stored: { version: 1, registrations: [] }, digest: null };
874
- throw error;
875
- }
876
- }
877
-
878
753
  /** Offline projection of recorded approvals only. Never imports drivers, reads auth, or probes CLIs.
879
754
  * This is historical evidence, not current launch authority; loadRecordedWorkerInstallations
880
755
  * performs binary/version/scope checks when dispatch actually requests a binding.
@@ -935,21 +810,7 @@ export async function recordWorkerInstallation(instance, options) {
935
810
  await assertTrustedStore(filename, installation.workerWritableRoots);
936
811
  // Canonical workspace identity is an exact approval key, never a prefix.
937
812
  installation.cwd = await realpath(installation.cwd);
938
- await mkdir(path.dirname(filename), { recursive: true, mode: 0o700 });
939
- // Serialize read/modify/rename across qualifying CLI processes. A stale lock
940
- // fails closed; qualification never steals another process's lock.
941
- const lockPath = `${filename}.lock`;
942
- let lock;
943
- for (let attempt = 0; attempt < 100; attempt++) {
944
- try { lock = await open(lockPath, 'wx', 0o600); break; }
945
- catch (error) {
946
- if (error.code !== 'EEXIST' || attempt === 99) throw error;
947
- await new Promise(resolve => setTimeout(resolve, 20));
948
- }
949
- }
950
- try {
951
- await assertTrustedStore(filename, installation.workerWritableRoots);
952
- const { stored } = await readInstallationStore(filename);
813
+ return withWorkerInstallationStore(installation.workerWritableRoots, async ({ stored }) => {
953
814
  const environmentNames = Object.keys(installation.environment ?? {});
954
815
  delete installation.environment;
955
816
  delete installation.adapter;
@@ -966,26 +827,10 @@ export async function recordWorkerInstallation(instance, options) {
966
827
  if (checkSignature(keyring, signingKey.keyid, sig, qualificationPayloadType, payload, signedAt) !== 'ok') throw new Error('invalid signature');
967
828
  record.signature = { keyid: signingKey.keyid, sig, signedAt, projectDir: signingProjectDir, scope: keyring.scope };
968
829
  } catch { return { status: 'DISABLED', reason: keyRecoveryMessage }; }
969
- const retained = [];
970
- for (const entry of stored.registrations) {
971
- const workspace = typeof entry.installation?.cwd === 'string'
972
- ? await realpath(entry.installation.cwd).catch(() => entry.installation.cwd) : null;
973
- if (entry.cli !== cli || workspace !== installation.cwd) retained.push(entry);
974
- }
975
- // Bound host authority without silently evicting another workspace approval.
976
- if (retained.length >= 128) throw new Error('Worker installation store is full (128 workspace approvals); remove an obsolete approval before qualifying another workspace');
977
- stored.registrations = retained;
978
- stored.registrations.push(record);
979
- await mkdir(path.dirname(filename), { recursive: true, mode: 0o700 });
980
- await assertTrustedStore(filename, installation.workerWritableRoots);
981
- const temporary = `${filename}.${process.pid}.${createHash('sha256').update(String(Math.random())).digest('hex')}.tmp`;
982
- await writeFile(temporary, `${JSON.stringify(stored, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
983
- await rename(temporary, filename);
830
+ stored.registrations = await retainWorkerApprovals(stored.registrations, record);
831
+ await writeWorkerInstallationStore(filename, stored, installation.workerWritableRoots);
984
832
  return result;
985
- } finally {
986
- await lock.close();
987
- await unlink(lockPath);
988
- }
833
+ });
989
834
  }
990
835
 
991
836
  /** Read recorded host authority, validate installation bytes and the current CLI
@@ -336,7 +336,7 @@ const BUILT_IN_SEEDS = [
336
336
  paths: {
337
337
  deployTarget: 'project',
338
338
  artifacts: {
339
- agents: '.agents/agents', commands: null, skills: '.agents/.aiwg/skills', rules: null, behaviors: null,
339
+ agents: '.agents/agents', commands: null, skills: '.agents/.aiwg/skills', rules: '.antigravity/rules', behaviors: null,
340
340
  },
341
341
  kernelSkills: '.agents/skills',
342
342
  contextDiscovery: { agents: '.agents/agents', skills: '.agents/skills', rules: null, behaviors: null },
@@ -344,7 +344,7 @@ const BUILT_IN_SEEDS = [
344
344
  contextFiles: { aiwgMd: true, agentsMd: true, claudeMdHook: false, hookFile: null, contextFile: 'AGENTS.md' },
345
345
  },
346
346
  smithPaths: {
347
- agents: '.agents/agents', commands: null, skills: '.agents/skills', rules: null,
347
+ agents: '.agents/agents', commands: null, skills: '.agents/skills', rules: '.antigravity/rules',
348
348
  fileExtension: '.md', configFile: 'AGENTS.md', aggregated: false,
349
349
  },
350
350
  skillNamespace: {
@@ -704,7 +704,7 @@ const BUILT_IN_SEEDS = [
704
704
  agents: '.grok/agents',
705
705
  commands: null,
706
706
  skills: '.grok/skills',
707
- rules: null,
707
+ rules: '.grok/rules',
708
708
  behaviors: null,
709
709
  },
710
710
  kernelSkills: '.grok/skills',
@@ -721,7 +721,7 @@ const BUILT_IN_SEEDS = [
721
721
  agents: '.grok/agents',
722
722
  commands: null,
723
723
  skills: '.grok/skills',
724
- rules: null,
724
+ rules: '.grok/rules',
725
725
  fileExtension: '.md',
726
726
  configFile: '.grok/config.toml',
727
727
  aggregated: false,
@@ -768,7 +768,7 @@ const BUILT_IN_SEEDS = [
768
768
  agents: null,
769
769
  commands: null,
770
770
  skills: resolveHermesHomePath('skills'),
771
- rules: null,
771
+ rules: '.hermes/rules',
772
772
  fileExtension: '.md',
773
773
  configFile: 'AGENTS.md',
774
774
  aggregated: false,
@@ -810,12 +810,12 @@ const BUILT_IN_SEEDS = [
810
810
  paths: {
811
811
  deployTarget: 'mixed',
812
812
  artifacts: {
813
- // Skills are written natively; agents, commands, and rules stay
814
- // indexed (aiwg discover/show) behind the AGENTS.md bridge.
813
+ // Skills are native; rule files are reached through the AGENTS.md
814
+ // hook. Agents and commands remain indexed through discover/show.
815
815
  agents: null,
816
816
  commands: null,
817
817
  skills: '.agents/skills',
818
- rules: null,
818
+ rules: '.muse/rules',
819
819
  behaviors: null,
820
820
  },
821
821
  kernelSkills: '.agents/skills',
@@ -832,7 +832,7 @@ const BUILT_IN_SEEDS = [
832
832
  agents: null,
833
833
  commands: null,
834
834
  skills: '.agents/skills',
835
- rules: null,
835
+ rules: '.muse/rules',
836
836
  fileExtension: '.md',
837
837
  configFile: null,
838
838
  aggregated: false,
@@ -1099,7 +1099,7 @@ const BUILT_IN_SEEDS = [
1099
1099
  agents: '.agents/skills',
1100
1100
  commands: '.pi/prompts',
1101
1101
  skills: '.pi/skills',
1102
- rules: null,
1102
+ rules: '.pi/rules',
1103
1103
  fileExtension: '.md',
1104
1104
  configFile: 'AGENTS.md',
1105
1105
  aggregated: false,
@@ -4,6 +4,7 @@
4
4
  * @module research/clients/arxiv
5
5
  */
6
6
  import { BaseClient } from './base.js';
7
+ import { normalizeDoi, parseArxivId } from '../identity.js';
7
8
  import { ResearchError, ResearchErrorCode, } from '../types.js';
8
9
  /**
9
10
  * arXiv API client
@@ -33,7 +34,7 @@ export class ArxivClient extends BaseClient {
33
34
  */
34
35
  async getPaperById(arxivId) {
35
36
  // Normalize arXiv ID (remove version if present)
36
- const normalizedId = arxivId.replace(/v\d+$/, '');
37
+ const normalizedId = parseArxivId(arxivId)?.id ?? arxivId;
37
38
  const url = this.buildUrl('/query', {
38
39
  id_list: normalizedId,
39
40
  max_results: 1,
@@ -125,7 +126,10 @@ export class ArxivClient extends BaseClient {
125
126
  });
126
127
  };
127
128
  const id = extractTag('id');
128
- const arxivId = id.split('/').pop()?.replace(/v\d+$/, '') || '';
129
+ const identity = parseArxivId(id);
130
+ if (!identity)
131
+ throw new ResearchError(ResearchErrorCode.RF_301, 'Invalid arXiv entry identifier');
132
+ const arxivId = identity.id;
129
133
  const title = extractTag('title').replace(/\s+/g, ' ');
130
134
  const summary = extractTag('summary').replace(/\s+/g, ' ');
131
135
  const published = extractTag('published');
@@ -133,8 +137,8 @@ export class ArxivClient extends BaseClient {
133
137
  const authorNames = extractAllTags('name');
134
138
  const authors = authorNames.map((name) => ({ name }));
135
139
  // Extract DOI if present
136
- const doiMatch = entry.match(/doi:([^\s<]+)/i);
137
- const doi = doiMatch ? doiMatch[1] : undefined;
140
+ const doiMatch = entry.match(/<arxiv:doi[^>]*>([^<]+)<\/arxiv:doi>/i);
141
+ const doi = doiMatch ? normalizeDoi(doiMatch[1]) : undefined;
138
142
  // Extract PDF link
139
143
  const pdfLinkMatch = entry.match(/<link[^>]*title="pdf"[^>]*href="([^"]+)"/i);
140
144
  const pdfUrl = pdfLinkMatch ? pdfLinkMatch[1] : undefined;
@@ -145,6 +149,8 @@ export class ArxivClient extends BaseClient {
145
149
  year,
146
150
  abstract: summary,
147
151
  arxivId,
152
+ arxivVersion: identity.version,
153
+ publicationDate: published || undefined,
148
154
  doi,
149
155
  pdfUrl,
150
156
  type: 'preprint',
@@ -70,8 +70,6 @@ export class BaseClient {
70
70
  * Execute an HTTP request with rate limiting and retry logic
71
71
  */
72
72
  async request(url, options = {}) {
73
- // Apply rate limiting
74
- await this.rateLimiter.acquire();
75
73
  // Execute with retry
76
74
  return this.executeWithRetry(url, options);
77
75
  }
@@ -79,6 +77,8 @@ export class BaseClient {
79
77
  * Execute request with exponential backoff retry
80
78
  */
81
79
  async executeWithRetry(url, options, attempt = 0, firstError) {
80
+ // Every attempt consumes a token, after any retry backoff and before timeout.
81
+ await this.rateLimiter.acquire();
82
82
  const controller = new AbortController();
83
83
  let timeoutId;
84
84
  try {
@@ -184,8 +184,9 @@ export class BaseClient {
184
184
  /**
185
185
  * Build URL with query parameters
186
186
  */
187
- buildUrl(path, params) {
188
- const url = new URL(path, this.config.baseUrl);
187
+ buildUrl(path, params, baseUrl = this.config.baseUrl) {
188
+ // API endpoints are relative to the complete base path, even with a slash.
189
+ const url = new URL(path.replace(/^\/+/, ''), `${baseUrl.replace(/\/+$/, '')}/`);
189
190
  Object.entries(params).forEach(([key, value]) => {
190
191
  if (value !== undefined) {
191
192
  url.searchParams.append(key, String(value));
@@ -39,9 +39,16 @@ export class CrossRefClient extends BaseClient {
39
39
  * Search papers by query
40
40
  */
41
41
  async search(query, options = {}) {
42
+ return this.queryWorks('query', query, options);
43
+ }
44
+ /** Resolve a partial citation using CrossRef's bibliographic search field. */
45
+ async searchBibliographic(query, options = {}) {
46
+ return this.queryWorks('query.bibliographic', query, options);
47
+ }
48
+ async queryWorks(field, query, options) {
42
49
  const { limit = 10, offset = 0 } = options;
43
50
  const url = this.buildUrl('/works', {
44
- query,
51
+ [field]: query,
45
52
  rows: limit,
46
53
  offset,
47
54
  });
@@ -80,6 +87,7 @@ export class CrossRefClient extends BaseClient {
80
87
  title,
81
88
  authors,
82
89
  year,
90
+ publicationDate: response.published?.['date-parts']?.[0]?.map((part, i) => String(part).padStart(i === 0 ? 4 : 2, '0')).join('-'),
83
91
  abstract: response.abstract,
84
92
  doi: response.DOI,
85
93
  venue,
@@ -4,18 +4,21 @@
4
4
  * @module research/clients/semantic-scholar
5
5
  */
6
6
  import { BaseClient } from './base.js';
7
+ import { ResearchError, ResearchErrorCode, } from '../types.js';
8
+ const IDENTITY_FIELDS = 'paperId,title,abstract,year,authors,citationCount,venue,publicationDate,publicationVenue,externalIds,openAccessPdf';
7
9
  /**
8
10
  * Semantic Scholar API client
9
11
  */
10
12
  export class SemanticScholarClient extends BaseClient {
13
+ recommendationsBaseUrl;
11
14
  constructor(config) {
12
15
  super({
13
16
  baseUrl: 'https://api.semanticscholar.org/graph/v1',
14
17
  timeout: 30000,
15
18
  rateLimit: {
16
- maxTokens: 100,
19
+ maxTokens: 1,
17
20
  refillRate: 1, // 1 request per second
18
- currentTokens: 100,
21
+ currentTokens: 1,
19
22
  lastRefill: Date.now(),
20
23
  },
21
24
  retry: {
@@ -25,65 +28,86 @@ export class SemanticScholarClient extends BaseClient {
25
28
  backoffMultiplier: 2,
26
29
  },
27
30
  ...config,
31
+ apiKey: config?.apiKey ?? process.env.S2_API_KEY,
28
32
  });
33
+ this.recommendationsBaseUrl = config?.recommendationsBaseUrl ??
34
+ 'https://api.semanticscholar.org/recommendations/v1';
35
+ }
36
+ /** Request raw JSON in an explicit namespace; baseUrl overrides graph only. */
37
+ async requestApi(namespace, path, params = {}) {
38
+ const baseUrl = namespace === 'graph'
39
+ ? this.config.baseUrl
40
+ : this.recommendationsBaseUrl;
41
+ return this.request(this.buildUrl(path, params, baseUrl));
42
+ }
43
+ /** Attach credentials once for all endpoints and keep transport causes private. */
44
+ async request(url, options = {}) {
45
+ const key = this.config.apiKey;
46
+ try {
47
+ const headers = new Headers(options.headers);
48
+ if (key)
49
+ headers.set('x-api-key', key);
50
+ return await super.request(url, { ...options, headers });
51
+ }
52
+ catch (error) {
53
+ // A transport error can echo request headers, including in its cause/stack.
54
+ if (key) {
55
+ throw new ResearchError(error instanceof ResearchError ? error.code : ResearchErrorCode.RF_500, error instanceof ResearchError
56
+ ? error.message.replaceAll(key, '[REDACTED]')
57
+ : 'Semantic Scholar request failed');
58
+ }
59
+ throw error;
60
+ }
29
61
  }
30
62
  /**
31
63
  * Get paper by DOI
32
64
  */
33
65
  async getPaperByDoi(doi) {
34
- const fields = [
35
- 'paperId',
36
- 'title',
37
- 'abstract',
38
- 'year',
39
- 'authors',
40
- 'citationCount',
41
- 'venue',
42
- 'externalIds',
43
- 'openAccessPdf',
44
- ];
45
- const url = this.buildUrl(`/paper/DOI:${encodeURIComponent(doi)}`, {
46
- fields: fields.join(','),
47
- });
48
- const response = await this.request(url);
49
- return this.transformResponse(response);
66
+ return this.getPaperById(`DOI:${doi}`);
50
67
  }
51
68
  /**
52
69
  * Get paper by arXiv ID
53
70
  */
54
71
  async getPaperByArxivId(arxivId) {
55
- const fields = [
56
- 'paperId',
57
- 'title',
58
- 'abstract',
59
- 'year',
60
- 'authors',
61
- 'citationCount',
62
- 'venue',
63
- 'externalIds',
64
- 'openAccessPdf',
65
- ];
66
- const url = this.buildUrl(`/paper/ARXIV:${encodeURIComponent(arxivId)}`, {
67
- fields: fields.join(','),
68
- });
69
- const response = await this.request(url);
72
+ return this.getPaperById(`ARXIV:${arxivId}`);
73
+ }
74
+ /** Graph lookup by paperId, DOI:, ARXIV:, ACL:, CorpusId: or URL: identifier. */
75
+ async getPaperById(identifier) {
76
+ const colon = identifier.indexOf(':');
77
+ const encoded = colon < 0 ? encodeURIComponent(identifier)
78
+ : `${identifier.slice(0, colon + 1)}${encodeURIComponent(identifier.slice(colon + 1))}`;
79
+ const response = await this.requestApi('graph', `/paper/${encoded}`, { fields: IDENTITY_FIELDS });
70
80
  return this.transformResponse(response);
71
81
  }
82
+ /** Title matching uses the graph match endpoint, retaining every returned candidate. */
83
+ async matchTitle(query) {
84
+ const response = await this.requestApi('graph', '/paper/search/match', {
85
+ query, fields: IDENTITY_FIELDS,
86
+ });
87
+ return response.data.map(paper => this.transformResponse(paper));
88
+ }
89
+ /** Similar papers share the normal transport, key header, limiter and retries. */
90
+ async recommendations(identifier, limit = 20, from = 'recent') {
91
+ const colon = identifier.indexOf(':');
92
+ const encoded = `${identifier.slice(0, colon + 1)}${encodeURIComponent(identifier.slice(colon + 1))}`;
93
+ const response = await this.requestApi('recommendations', `/papers/forpaper/${encoded}`, { limit, from, fields: IDENTITY_FIELDS });
94
+ if (!Array.isArray(response.recommendedPapers) || response.recommendedPapers.some(p => !p?.paperId || !p.title)) {
95
+ throw new ResearchError(ResearchErrorCode.RF_301, 'Invalid recommendations response');
96
+ }
97
+ return response.recommendedPapers.map(paper => this.transformResponse(paper));
98
+ }
99
+ /** One graph lookup for each candidate selected for optional citation overlap. */
100
+ async recommendationReferences(paperId) {
101
+ const response = await this.requestApi('graph', `/paper/${encodeURIComponent(paperId)}`, { fields: 'references.paperId,references.title,references.externalIds' });
102
+ if (!Array.isArray(response.references))
103
+ throw new ResearchError(ResearchErrorCode.RF_301, 'Invalid references response');
104
+ return response.references.filter(paper => paper?.paperId).map(paper => this.transformResponse(paper));
105
+ }
72
106
  /**
73
107
  * Search papers by query
74
108
  */
75
109
  async search(query, options = {}) {
76
- const { limit = 10, offset = 0, fields = [
77
- 'paperId',
78
- 'title',
79
- 'abstract',
80
- 'year',
81
- 'authors',
82
- 'citationCount',
83
- 'venue',
84
- 'externalIds',
85
- 'openAccessPdf',
86
- ], } = options;
110
+ const { limit = 10, offset = 0, fields = IDENTITY_FIELDS.split(','), } = options;
87
111
  const url = this.buildUrl('/paper/search', {
88
112
  query,
89
113
  limit,
@@ -109,12 +133,17 @@ export class SemanticScholarClient extends BaseClient {
109
133
  }));
110
134
  return {
111
135
  id: response.paperId,
136
+ s2PaperId: response.paperId,
112
137
  title: response.title,
113
138
  authors,
114
139
  year: response.year || 0,
115
140
  abstract: response.abstract,
116
141
  doi: response.externalIds?.DOI,
117
142
  arxivId: response.externalIds?.ArXiv,
143
+ aclId: response.externalIds?.ACL,
144
+ openReviewId: response.externalIds?.OpenReview,
145
+ publicationDate: response.publicationDate ?? undefined,
146
+ publicationVenue: response.publicationVenue ?? undefined,
118
147
  venue: response.venue,
119
148
  citationCount: response.citationCount,
120
149
  pdfUrl: response.openAccessPdf?.url,