@aiwg/cli 2026.10.14 → 2026.10.16

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 (210) 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/agentic/code/providers/pi/aiwg-bridge.ts +45 -7
  4. package/dist/src/artifacts/citation-parser.js +7 -6
  5. package/dist/src/artifacts/corpus-tools/citation-densify.js +4 -2
  6. package/dist/src/artifacts/corpus-tools/cli.js +37 -0
  7. package/dist/src/artifacts/corpus-tools/discovery-log.js +27 -25
  8. package/dist/src/artifacts/corpus-tools/expand-cli.js +90 -0
  9. package/dist/src/artifacts/corpus-tools/expand-dates.js +107 -0
  10. package/dist/src/artifacts/corpus-tools/expand-queue.js +41 -0
  11. package/dist/src/artifacts/corpus-tools/expand-review.js +104 -0
  12. package/dist/src/artifacts/corpus-tools/expand-state.js +56 -0
  13. package/dist/src/artifacts/corpus-tools/expand.js +124 -0
  14. package/dist/src/artifacts/corpus-tools/induction-audit.js +7 -6
  15. package/dist/src/artifacts/corpus-tools/integrity-scan.js +3 -3
  16. package/dist/src/artifacts/corpus-tools/radar-shared.js +7 -9
  17. package/dist/src/artifacts/corpus-tools/ref-files.js +11 -0
  18. package/dist/src/artifacts/corpus-tools/resolve-cli.js +99 -0
  19. package/dist/src/artifacts/corpus-tools/resolve-corpus.js +41 -0
  20. package/dist/src/artifacts/corpus-tools/resolve.js +119 -0
  21. package/dist/src/artifacts/corpus-tools/retrieval-lab.js +2 -1
  22. package/dist/src/artifacts/corpus-tools/sidecar-lint.js +4 -4
  23. package/dist/src/artifacts/corpus-tools/sidecar-repair.js +2 -1
  24. package/dist/src/artifacts/corpus-views/ref-parser.js +3 -17
  25. package/dist/src/artifacts/graph-query.js +5 -3
  26. package/dist/src/artifacts/hybrid-query.js +11 -2
  27. package/dist/src/artifacts/index-refresh.js +2 -0
  28. package/dist/src/cli/handlers/daemon.js +17 -1
  29. package/dist/src/cli/handlers/doctor-args.js +45 -0
  30. package/dist/src/cli/handlers/doctor-help.js +8 -3
  31. package/dist/src/cli/handlers/index.js +2 -2
  32. package/dist/src/cli/handlers/models-resource-sample.js +10 -0
  33. package/dist/src/cli/handlers/models.js +3 -2
  34. package/dist/src/cli/handlers/regenerate.js +8 -16
  35. package/dist/src/cli/handlers/sessions.js +7 -7
  36. package/dist/src/cli/handlers/subcommands.js +8 -0
  37. package/dist/src/cli/handlers/update.js +157 -0
  38. package/dist/src/cli/handlers/use.js +14 -4
  39. package/dist/src/cli/handlers/utilities.js +3 -586
  40. package/dist/src/cli/handlers/utility-doctor.js +412 -0
  41. package/dist/src/cli/services/deployment-verification.js +0 -1
  42. package/dist/src/config/aiwg-config.js +2 -1
  43. package/dist/src/config/authorization-cli.js +7 -3
  44. package/dist/src/config/dispatch-thresholds-runtime.d.mts +3 -2
  45. package/dist/src/config/dispatch-thresholds-runtime.mjs +17 -7
  46. package/dist/src/config/framework-aliases.js +12 -0
  47. package/dist/src/config/host-resource-report.d.mts +19 -0
  48. package/dist/src/config/host-resource-report.mjs +80 -0
  49. package/dist/src/config/host-resource-runtime.d.mts +34 -0
  50. package/dist/src/config/host-resource-runtime.mjs +293 -0
  51. package/dist/src/config/installed-selection.js +22 -0
  52. package/dist/src/config/worker-context.js +33 -4
  53. package/dist/src/config/worker-invocation-marker.d.mts +1 -0
  54. package/dist/src/config/worker-invocation-marker.mjs +2 -0
  55. package/dist/src/decision/heldout/access.js +74 -0
  56. package/dist/src/decision/heldout/calibration.js +1 -0
  57. package/dist/src/decision/heldout/collector.js +9 -2
  58. package/dist/src/effects/verifiers/file.js +22 -5
  59. package/dist/src/extensions/claude-attribution.js +82 -0
  60. package/dist/src/extensions/claude-hooks-installer.js +115 -69
  61. package/dist/src/extensions/commands/daemon.js +109 -0
  62. package/dist/src/extensions/commands/definitions.js +5 -89
  63. package/dist/src/features/catalog.js +1 -1
  64. package/dist/src/gates/evaluate.js +2 -2
  65. package/dist/src/gates/heldout.js +52 -0
  66. package/dist/src/gates/index.js +2 -1
  67. package/dist/src/lint/check-patterns.js +163 -0
  68. package/dist/src/lint/checks.js +268 -0
  69. package/dist/src/lint/reference-resolution.js +54 -0
  70. package/dist/src/lint/runner.js +3 -465
  71. package/dist/src/mcp/helpers.mjs +11 -1
  72. package/dist/src/memory/project-registry.js +44 -4
  73. package/dist/src/models/worker-installation-store.mjs +228 -0
  74. package/dist/src/models/worker-installation.mjs +7 -162
  75. package/dist/src/models/worker-plan.js +36 -5
  76. package/dist/src/models/wrapper-deployment.js +25 -12
  77. package/dist/src/models/wrapper-enforcement.js +47 -7
  78. package/dist/src/network-analysis/research.js +2 -1
  79. package/dist/src/policy/hitl-check.js +14 -4
  80. package/dist/src/policy/hitl-consume.js +54 -0
  81. package/dist/src/policy/hitl-receipt.js +2 -0
  82. package/dist/src/policy/hitl.js +11 -3
  83. package/dist/src/providers/provider-context-contracts.js +162 -0
  84. package/dist/src/providers/provider-definition-schema.js +136 -0
  85. package/dist/src/providers/provider-definitions.js +8 -1298
  86. package/dist/src/providers/provider-seeds-1.js +360 -0
  87. package/dist/src/providers/provider-seeds-2.js +387 -0
  88. package/dist/src/providers/provider-seeds-3.js +262 -0
  89. package/dist/src/research/clients/arxiv.js +14 -34
  90. package/dist/src/research/clients/base.js +53 -26
  91. package/dist/src/research/clients/crossref.js +9 -1
  92. package/dist/src/research/clients/semantic-scholar.js +73 -44
  93. package/dist/src/research/identity.js +117 -0
  94. package/dist/src/research/index.js +1 -0
  95. package/dist/src/research/query-cli.js +3 -87
  96. package/dist/src/research/query-options.js +87 -0
  97. package/dist/src/research/reference-match.js +135 -0
  98. package/dist/src/research/services/acquisition.js +9 -7
  99. package/dist/src/research/services/citation.js +5 -2
  100. package/dist/src/research/types.js +2 -0
  101. package/dist/src/rules/core-startup.d.mts +2 -0
  102. package/dist/src/rules/core-startup.mjs +31 -0
  103. package/dist/src/serve/mission-conductor.js +48 -4
  104. package/dist/src/sessions/adapters/grok-build-native.js +23 -0
  105. package/dist/src/sessions/adapters/grok-build.js +14 -7
  106. package/dist/src/sessions/workspace-discovery.js +5 -5
  107. package/dist/src/smiths/context-pipeline/agents-md.js +34 -0
  108. package/dist/src/smiths/context-pipeline/aiwg-md.js +19 -46
  109. package/dist/src/smiths/context-pipeline/bridge-ownership.js +50 -0
  110. package/dist/src/smiths/context-pipeline/claude-hook.js +1 -1
  111. package/dist/src/smiths/context-pipeline/code-regions.js +28 -0
  112. package/dist/src/smiths/context-pipeline/finalization.js +81 -51
  113. package/dist/src/smiths/context-pipeline/generator.js +49 -114
  114. package/dist/src/smiths/context-pipeline/managed-hook.js +11 -1
  115. package/dist/src/smiths/context-pipeline/muse-bridge.js +2 -2
  116. package/dist/src/smiths/context-pipeline/provider-policy.js +6 -12
  117. package/dist/src/smiths/context-pipeline/workspace-audit.js +299 -0
  118. package/dist/src/smiths/context-pipeline/workspace-bootstrap.js +148 -0
  119. package/dist/src/smiths/context-pipeline/workspace-context-shared.js +111 -0
  120. package/dist/src/smiths/context-pipeline/workspace-context.js +8 -1373
  121. package/dist/src/smiths/context-pipeline/workspace-doctor.js +192 -0
  122. package/dist/src/smiths/context-pipeline/workspace-document.js +201 -0
  123. package/dist/src/smiths/context-pipeline/workspace-extraction.js +205 -0
  124. package/dist/src/smiths/context-pipeline/workspace-migration.js +250 -0
  125. package/package.json +13 -2
  126. package/schemas/decision/D29Study.v10.schema.json +65 -0
  127. package/tools/agents/deploy-agents.mjs +12 -123
  128. package/tools/agents/providers/antigravity.mjs +1 -1
  129. package/tools/agents/providers/claude-post-deploy.mjs +12 -1
  130. package/tools/agents/providers/context-write.mjs +16 -0
  131. package/tools/agents/providers/grok-build.mjs +8 -5
  132. package/tools/agents/providers/hermes-skill-lifecycle.mjs +144 -0
  133. package/tools/agents/providers/hermes-startup.mjs +209 -0
  134. package/tools/agents/providers/hermes.mjs +9 -359
  135. package/tools/agents/providers/model-wrapper.mjs +5 -1
  136. package/tools/agents/providers/muse.mjs +3 -3
  137. package/tools/agents/providers/pi.mjs +4 -2
  138. package/tools/agents/providers/rule-delivery-surface.mjs +332 -0
  139. package/tools/agents/providers/rule-delivery.mjs +20 -1346
  140. package/tools/agents/providers/rule-deployment-commit.mjs +144 -0
  141. package/tools/agents/providers/rule-deployment-prepare.mjs +452 -0
  142. package/tools/agents/providers/rule-deployment-state.mjs +300 -0
  143. package/tools/agents/providers/rule-presentation.mjs +13 -4
  144. package/tools/agents/providers/rule-projection.mjs +119 -0
  145. package/tools/agents/providers/rule-startup.mjs +70 -0
  146. package/tools/agents/providers/stale-artifact-prune.mjs +128 -0
  147. package/tools/agents/providers/warp.mjs +2 -2
  148. package/tools/agents/providers/windsurf.mjs +11 -57
  149. package/tools/daemon/README.md +511 -0
  150. package/tools/daemon/adapters/base-adapter.mjs +84 -0
  151. package/tools/daemon/adapters/webhook-adapter.mjs +107 -0
  152. package/tools/daemon/agent-supervisor.mjs +299 -0
  153. package/tools/daemon/automation-engine.mjs +310 -0
  154. package/tools/daemon/autonomous-engine.mjs +346 -0
  155. package/tools/daemon/behavior-loader.mjs +316 -0
  156. package/tools/daemon/behavior.mjs +174 -0
  157. package/tools/daemon/concierge/intent-router.mjs +401 -0
  158. package/tools/daemon/concierge/orchestrator.mjs +272 -0
  159. package/tools/daemon/concierge/response-translator.mjs +462 -0
  160. package/tools/daemon/config.mjs +377 -0
  161. package/tools/daemon/cron-scheduler.mjs +178 -0
  162. package/tools/daemon/daemon-main.mjs +1169 -0
  163. package/tools/daemon/event-router.mjs +84 -0
  164. package/tools/daemon/file-watcher.mjs +383 -0
  165. package/tools/daemon/index.mjs +1181 -0
  166. package/tools/daemon/init-profile.mjs +124 -0
  167. package/tools/daemon/ipc-client.mjs +197 -0
  168. package/tools/daemon/ipc-ops-handlers.mjs +236 -0
  169. package/tools/daemon/ipc-server.mjs +275 -0
  170. package/tools/daemon/maintenance-owner.mjs +79 -0
  171. package/tools/daemon/memory-manager.mjs +386 -0
  172. package/tools/daemon/message-router.mjs +194 -0
  173. package/tools/daemon/provider-watcher.mjs +585 -0
  174. package/tools/daemon/pty-adapter.mjs +420 -0
  175. package/tools/daemon/repl-chat.mjs +359 -0
  176. package/tools/daemon/resource-bounds.mjs +88 -0
  177. package/tools/daemon/sandbox-transport.mjs +295 -0
  178. package/tools/daemon/scheduled-task-runner.mjs +535 -0
  179. package/tools/daemon/task-store.mjs +450 -0
  180. package/tools/daemon/tmux-manager.mjs +324 -0
  181. package/tools/daemon/update-policy.mjs +517 -0
  182. package/tools/daemon/web-server.mjs +399 -0
  183. package/tools/daemon/web-ui/index.html +585 -0
  184. package/tools/daemon/web-ui/styles.css +156 -0
  185. package/tools/docker/Dockerfile.daemon +35 -0
  186. package/tools/docker/container-manager.mjs +291 -0
  187. package/tools/messaging/adapter-registry.mjs +230 -0
  188. package/tools/messaging/adapters/base.mjs +326 -0
  189. package/tools/messaging/adapters/discord.mjs +462 -0
  190. package/tools/messaging/adapters/slack.mjs +402 -0
  191. package/tools/messaging/adapters/telegram.mjs +552 -0
  192. package/tools/messaging/chat-handler.mjs +297 -0
  193. package/tools/messaging/command-router.mjs +269 -0
  194. package/tools/messaging/event-bus.mjs +199 -0
  195. package/tools/messaging/index.mjs +456 -0
  196. package/tools/messaging/message-formatter.mjs +320 -0
  197. package/tools/messaging/room-manager.mjs +277 -0
  198. package/tools/messaging/types.mjs +94 -0
  199. package/tools/plugin/plugin-links.mjs +3 -0
  200. package/tools/providers/pi-bridge-policy.mjs +4 -0
  201. package/tools/ralph-external/daemon-supervisor.mjs +394 -0
  202. package/tools/ralph-external/lib/behavior-registry.mjs +270 -0
  203. package/tools/ralph-external/lib/worker-invocation-processes.mjs +3 -2
  204. package/tools/ralph-external/lib/worker-isolation-args.mjs +217 -0
  205. package/tools/ralph-external/lib/worker-isolation-status.mjs +19 -0
  206. package/tools/ralph-external/lib/worker-isolation.mjs +11 -237
  207. package/tools/ralph-external/lib/worker-overflow.mjs +10 -2
  208. package/tools/ralph-external/lib/worker-unit-cleanup.mjs +72 -0
  209. package/tools/ralph-external/session-launcher.mjs +7 -7
  210. package/tools/scripts/resource-preflight.mjs +3 -242
@@ -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
@@ -14,9 +15,9 @@ export class ArxivClient extends BaseClient {
14
15
  baseUrl: 'http://export.arxiv.org/api',
15
16
  timeout: 30000,
16
17
  rateLimit: {
17
- maxTokens: 3,
18
+ maxTokens: 1,
18
19
  refillRate: 1 / 3, // 1 request per 3 seconds
19
- currentTokens: 3,
20
+ currentTokens: 1,
20
21
  lastRefill: Date.now(),
21
22
  },
22
23
  retry: {
@@ -33,12 +34,12 @@ 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,
40
41
  });
41
- const xmlText = await this.requestXml(url);
42
+ const xmlText = await this.requestText(url);
42
43
  const papers = this.parseAtomFeed(xmlText);
43
44
  if (papers.length === 0) {
44
45
  throw new ResearchError(ResearchErrorCode.RF_300, `arXiv paper not found: ${arxivId}`);
@@ -55,7 +56,7 @@ export class ArxivClient extends BaseClient {
55
56
  start: offset,
56
57
  max_results: limit,
57
58
  });
58
- const xmlText = await this.requestXml(url);
59
+ const xmlText = await this.requestText(url);
59
60
  const papers = this.parseAtomFeed(xmlText);
60
61
  // arXiv doesn't provide total count, so we estimate
61
62
  const hasMore = papers.length === limit;
@@ -67,32 +68,6 @@ export class ArxivClient extends BaseClient {
67
68
  hasMore,
68
69
  };
69
70
  }
70
- /**
71
- * Request XML from arXiv API
72
- */
73
- async requestXml(url) {
74
- await this.rateLimiter.acquire();
75
- const controller = new AbortController();
76
- const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
77
- try {
78
- const response = await fetch(url, {
79
- signal: controller.signal,
80
- });
81
- if (!response.ok) {
82
- throw new ResearchError(ResearchErrorCode.RF_200, `arXiv API error: ${response.status}`);
83
- }
84
- return await response.text();
85
- }
86
- catch (error) {
87
- if (error instanceof Error && error.name === 'AbortError') {
88
- throw new ResearchError(ResearchErrorCode.RF_104, `Request timeout after ${this.config.timeout}ms`, error);
89
- }
90
- throw error;
91
- }
92
- finally {
93
- clearTimeout(timeoutId);
94
- }
95
- }
96
71
  /**
97
72
  * Parse Atom XML feed from arXiv
98
73
  */
@@ -125,7 +100,10 @@ export class ArxivClient extends BaseClient {
125
100
  });
126
101
  };
127
102
  const id = extractTag('id');
128
- const arxivId = id.split('/').pop()?.replace(/v\d+$/, '') || '';
103
+ const identity = parseArxivId(id);
104
+ if (!identity)
105
+ throw new ResearchError(ResearchErrorCode.RF_301, 'Invalid arXiv entry identifier');
106
+ const arxivId = identity.id;
129
107
  const title = extractTag('title').replace(/\s+/g, ' ');
130
108
  const summary = extractTag('summary').replace(/\s+/g, ' ');
131
109
  const published = extractTag('published');
@@ -133,8 +111,8 @@ export class ArxivClient extends BaseClient {
133
111
  const authorNames = extractAllTags('name');
134
112
  const authors = authorNames.map((name) => ({ name }));
135
113
  // Extract DOI if present
136
- const doiMatch = entry.match(/doi:([^\s<]+)/i);
137
- const doi = doiMatch ? doiMatch[1] : undefined;
114
+ const doiMatch = entry.match(/<arxiv:doi[^>]*>([^<]+)<\/arxiv:doi>/i);
115
+ const doi = doiMatch ? normalizeDoi(doiMatch[1]) : undefined;
138
116
  // Extract PDF link
139
117
  const pdfLinkMatch = entry.match(/<link[^>]*title="pdf"[^>]*href="([^"]+)"/i);
140
118
  const pdfUrl = pdfLinkMatch ? pdfLinkMatch[1] : undefined;
@@ -145,6 +123,8 @@ export class ArxivClient extends BaseClient {
145
123
  year,
146
124
  abstract: summary,
147
125
  arxivId,
126
+ arxivVersion: identity.version,
127
+ publicationDate: published || undefined,
148
128
  doi,
149
129
  pdfUrl,
150
130
  type: 'preprint',
@@ -4,6 +4,8 @@
4
4
  * @module research/clients/base
5
5
  */
6
6
  import { ResearchError, ResearchErrorCode, } from '../types.js';
7
+ // Bound server-directed cooldowns for both retries and later shared-client requests.
8
+ const MAX_RETRY_AFTER_MS = 30_000;
7
9
  /**
8
10
  * Token bucket rate limiter
9
11
  */
@@ -11,6 +13,8 @@ export class RateLimiter {
11
13
  config;
12
14
  tokens;
13
15
  lastRefill;
16
+ blockedUntil = 0;
17
+ queue = Promise.resolve();
14
18
  constructor(config) {
15
19
  this.config = config;
16
20
  this.tokens = config.currentTokens;
@@ -29,19 +33,25 @@ export class RateLimiter {
29
33
  /**
30
34
  * Acquire a token, waiting if necessary
31
35
  */
32
- async acquire() {
33
- this.refill();
34
- if (this.tokens >= 1) {
35
- this.tokens -= 1;
36
- return;
36
+ acquire() {
37
+ const pending = this.queue.then(() => this.acquireToken());
38
+ this.queue = pending.catch(() => { });
39
+ return pending;
40
+ }
41
+ /** Share a server cooldown with subsequent requests, including exhausted retries. */
42
+ defer(ms) {
43
+ this.blockedUntil = Math.max(this.blockedUntil, Date.now() + ms);
44
+ }
45
+ async acquireToken() {
46
+ for (;;) {
47
+ this.refill();
48
+ const waitMs = Math.max(this.blockedUntil - Date.now(), (1 - this.tokens) / this.config.refillRate * 1000);
49
+ if (waitMs <= 0) {
50
+ this.tokens -= 1;
51
+ return;
52
+ }
53
+ await this.sleep(Math.ceil(waitMs));
37
54
  }
38
- // Calculate wait time
39
- const deficit = 1 - this.tokens;
40
- const waitMs = (deficit / this.config.refillRate) * 1000;
41
- await this.sleep(waitMs);
42
- // Refill again after waiting
43
- this.refill();
44
- this.tokens -= 1;
45
55
  }
46
56
  sleep(ms) {
47
57
  return new Promise((resolve) => setTimeout(resolve, ms));
@@ -70,15 +80,19 @@ export class BaseClient {
70
80
  * Execute an HTTP request with rate limiting and retry logic
71
81
  */
72
82
  async request(url, options = {}) {
73
- // Apply rate limiting
74
- await this.rateLimiter.acquire();
75
83
  // Execute with retry
76
84
  return this.executeWithRetry(url, options);
77
85
  }
86
+ /** XML clients use the same limiter, timeout and HTTP retry policy as JSON. */
87
+ requestText(url, options = {}) {
88
+ return this.executeWithRetry(url, options, 0, undefined, response => response.text());
89
+ }
78
90
  /**
79
91
  * Execute request with exponential backoff retry
80
92
  */
81
- async executeWithRetry(url, options, attempt = 0, firstError) {
93
+ async executeWithRetry(url, options, attempt = 0, firstError, read = response => response.json()) {
94
+ // Every attempt consumes a token, after any retry backoff and before timeout.
95
+ await this.rateLimiter.acquire();
82
96
  const controller = new AbortController();
83
97
  let timeoutId;
84
98
  try {
@@ -104,7 +118,7 @@ export class BaseClient {
104
118
  const error = await this.handleHttpError(response);
105
119
  throw error;
106
120
  }
107
- return (await response.json());
121
+ return await read(response);
108
122
  }
109
123
  catch (error) {
110
124
  // Clear timeout on error
@@ -117,13 +131,18 @@ export class BaseClient {
117
131
  }
118
132
  // Track the first error for better error reporting
119
133
  const currentFirstError = firstError || (error instanceof ResearchError ? error : undefined);
120
- // Don't retry ResearchErrors (they're already handled)
134
+ // A throttle cooldown survives exhaustion so the next batch line also waits.
135
+ const delay = Math.max(this.calculateBackoff(attempt), error instanceof ResearchError ? Math.min(error.retryAfterMs ?? 0, MAX_RETRY_AFTER_MS) : 0);
136
+ if (error instanceof ResearchError && error.code === ResearchErrorCode.RF_103) {
137
+ this.rateLimiter.defer(delay);
138
+ }
139
+ // Retry transient HTTP failures with the same limiter on every attempt.
121
140
  if (error instanceof ResearchError) {
122
141
  // Retry on transient errors
123
142
  if (this.isRetriable(error) && attempt < this.retryConfig.maxRetries) {
124
- const delay = this.calculateBackoff(attempt);
125
- await this.sleep(delay);
126
- return this.executeWithRetry(url, options, attempt + 1, currentFirstError);
143
+ if (error.code !== ResearchErrorCode.RF_103)
144
+ await this.sleep(delay);
145
+ return this.executeWithRetry(url, options, attempt + 1, currentFirstError, read);
127
146
  }
128
147
  throw error;
129
148
  }
@@ -131,7 +150,7 @@ export class BaseClient {
131
150
  if (attempt < this.retryConfig.maxRetries) {
132
151
  const delay = this.calculateBackoff(attempt);
133
152
  await this.sleep(delay);
134
- return this.executeWithRetry(url, options, attempt + 1, currentFirstError);
153
+ return this.executeWithRetry(url, options, attempt + 1, currentFirstError, read);
135
154
  }
136
155
  // If we have a first error from an HTTP response, throw that instead of generic network error
137
156
  if (currentFirstError) {
@@ -149,7 +168,14 @@ export class BaseClient {
149
168
  return new ResearchError(ResearchErrorCode.RF_300, 'Resource not found');
150
169
  }
151
170
  if (status === 429) {
152
- return new ResearchError(ResearchErrorCode.RF_103, 'Rate limit exceeded');
171
+ const error = new ResearchError(ResearchErrorCode.RF_103, 'Rate limit exceeded');
172
+ const value = response.headers?.get('retry-after');
173
+ if (value) {
174
+ const ms = /^\d+(?:\.\d+)?$/.test(value.trim()) ? Number(value) * 1000 : Date.parse(value) - Date.now();
175
+ if (Number.isFinite(ms))
176
+ error.retryAfterMs = Math.max(0, ms);
177
+ }
178
+ return error;
153
179
  }
154
180
  if (status === 401 || status === 403) {
155
181
  return new ResearchError(ResearchErrorCode.RF_102, 'Invalid API key or unauthorized');
@@ -164,8 +190,8 @@ export class BaseClient {
164
190
  */
165
191
  isRetriable(error) {
166
192
  if (error instanceof ResearchError) {
167
- // Only retry on server errors (not rate limits or client errors)
168
- return error.code === ResearchErrorCode.RF_200;
193
+ // Rate limits and server errors are transient.
194
+ return error.code === ResearchErrorCode.RF_200 || error.code === ResearchErrorCode.RF_103;
169
195
  }
170
196
  // Retry on network errors
171
197
  return true;
@@ -184,8 +210,9 @@ export class BaseClient {
184
210
  /**
185
211
  * Build URL with query parameters
186
212
  */
187
- buildUrl(path, params) {
188
- const url = new URL(path, this.config.baseUrl);
213
+ buildUrl(path, params, baseUrl = this.config.baseUrl) {
214
+ // API endpoints are relative to the complete base path, even with a slash.
215
+ const url = new URL(path.replace(/^\/+/, ''), `${baseUrl.replace(/\/+$/, '')}/`);
189
216
  Object.entries(params).forEach(([key, value]) => {
190
217
  if (value !== undefined) {
191
218
  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,
@@ -0,0 +1,117 @@
1
+ const ARXIV = '(?:\\d{4}\\.\\d{4,5}|[a-z][a-z.-]*(?:\\.[A-Z]{2})?/\\d{7})(?:v\\d+)?';
2
+ /** Parse abs/pdf/html URLs, arXiv DOIs, new/old IDs and an optional version. */
3
+ export function parseArxivId(input) {
4
+ const text = input.trim().replace(/\.pdf(?:[?#].*)?$/i, '').replace(/[?#].*$/, '');
5
+ const match = text.match(new RegExp(`^(?:(?:https?://(?:export\\.)?arxiv\\.org/(?:abs|pdf|html)/)|(?:https?://(?:dx\\.)?doi\\.org/)?10\\.48550/arxiv\\.|arxiv:\\s*)?(${ARXIV})$`, 'i'));
6
+ if (!match)
7
+ return undefined;
8
+ const version = match[1].match(/v(\d+)$/i);
9
+ return { id: match[1].replace(/v\d+$/i, '').toLowerCase(), ...(version ? { version: Number(version[1]) } : {}) };
10
+ }
11
+ /** Canonical DOI spelling, including DOI URLs; trailing citation punctuation is ignored. */
12
+ export function normalizeDoi(input) {
13
+ let text = input.trim().replace(/^(?:https?:\/\/(?:dx\.)?doi\.org\/|doi:\s*)/i, '');
14
+ try {
15
+ text = decodeURIComponent(text);
16
+ }
17
+ catch { /* Keep a literal DOI on malformed escapes. */ }
18
+ text = text.replace(/[.,;]+$/, '');
19
+ while (text.endsWith(')') && (text.match(/\)/g)?.length ?? 0) > (text.match(/\(/g)?.length ?? 0))
20
+ text = text.slice(0, -1);
21
+ return /^10\.\d{4,9}\/\S+$/i.test(text) ? text.toLowerCase() : undefined;
22
+ }
23
+ /** Parse a recognized identifier even when embedded in a bibliography line. */
24
+ export function parseResearchIdentifier(input) {
25
+ const arxiv = input.match(new RegExp(`(?:https?://(?:export\\.)?arxiv\\.org/(?:abs|pdf|html)/|(?:https?://(?:dx\\.)?doi\\.org/)?10\\.48550/arxiv\\.|arxiv:\\s*)${ARXIV}(?:\\.pdf)?(?:[?#][^\\s<>]*)?|(?<![\\w./])${ARXIV}(?![\\w.])`, 'i'));
26
+ if (arxiv) {
27
+ const parsed = parseArxivId(arxiv[0]);
28
+ if (parsed)
29
+ return { kind: 'arxiv', ...parsed, matched: arxiv[0] };
30
+ }
31
+ const doi = input.match(/(?:https?:\/\/(?:dx\.)?doi\.org\/|doi:\s*)?10\.\d{4,9}\/[^\s<>"\]]+/i);
32
+ if (doi) {
33
+ const id = normalizeDoi(doi[0]);
34
+ if (id)
35
+ return { kind: 'doi', id, matched: doi[0] };
36
+ }
37
+ const review = input.match(/https?:\/\/(?:www\.)?openreview\.net\/(?:forum|pdf)\?[^\s<>]*/i);
38
+ if (review) {
39
+ const id = new URL(review[0]).searchParams.get('id');
40
+ if (id)
41
+ return { kind: 'openreview', id, matched: review[0] };
42
+ }
43
+ const reviewId = input.match(/\bopenreview:\s*([\w-]+)/i);
44
+ if (reviewId)
45
+ return { kind: 'openreview', id: reviewId[1], matched: reviewId[0] };
46
+ const acl = input.match(/https?:\/\/(?:www\.)?aclanthology\.org\/([\w.-]+)\/?(?:[?#][^\s<>]*)?|\bacl:\s*([\w.-]+)|\b((?:\d{4}\.[a-z][\w-]*\.\d+|[A-Z]\d{2}-\d{4}))\b/i);
47
+ if (acl)
48
+ return { kind: 'acl', id: (acl[1] ?? acl[2] ?? acl[3]).replace(/\.pdf$/i, ''), matched: acl[0] };
49
+ const s2 = input.match(/https?:\/\/(?:www\.)?semanticscholar\.org\/paper\/(?:[^\s/]+\/)?([a-f\d]{40})\b|\b(?:s2|semanticscholar):\s*([a-f\d]{40})\b|\b(CorpusId:\d+)\b/i);
50
+ if (s2)
51
+ return { kind: 's2', id: (s2[1] ?? s2[2] ?? s2[3]).toLowerCase().replace(/^corpusid:/, 'CorpusId:'), matched: s2[0] };
52
+ return undefined;
53
+ }
54
+ /** Remove LaTeX formatting while retaining its text, then normalize Unicode and punctuation. */
55
+ export function normalizeTitle(input) {
56
+ return input.normalize('NFKC')
57
+ .replace(/\\(?:begin|end)\{[^}]*\}/g, ' ')
58
+ .replace(/\\[a-zA-Z]+\*?/g, '')
59
+ .replace(/\\([^a-zA-Z])/g, '$1')
60
+ .toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, ' ')
61
+ .replace(/\s+/g, ' ').trim();
62
+ }
63
+ /** Accept both corpus frontmatter spellings and canonical client metadata. */
64
+ export function normalizeIdentity(value) {
65
+ const fields = value;
66
+ const str = (...keys) => keys.map(k => fields[k])
67
+ .map(v => typeof v === 'number' && Number.isFinite(v) ? String(v) : v)
68
+ .find(v => typeof v === 'string' && v.trim());
69
+ const arxiv = parseArxivId(str('arxivId', 'arxiv_id', 'arxiv') ?? '') ?? parseArxivId(str('doi') ?? '');
70
+ return {
71
+ ...(arxiv ? { arxivId: arxiv.id, arxivVersion: arxiv.version ?? (typeof fields.arxivVersion === 'number' ? fields.arxivVersion : undefined) } : {}),
72
+ doi: normalizeDoi(str('doi', 'DOI') ?? ''),
73
+ s2PaperId: str('s2PaperId', 's2_paper_id', 'paperId')?.toLowerCase(),
74
+ openReviewId: str('openReviewId', 'openreview_id')?.toLowerCase(),
75
+ aclId: str('aclId', 'acl_id')?.toLowerCase(),
76
+ title: str('title') ? normalizeTitle(str('title')) : undefined,
77
+ };
78
+ }
79
+ /** Stable keys for matching any identifier or a normalized title across corpus sources. */
80
+ export function identityKeys(value) {
81
+ const identity = normalizeIdentity(value);
82
+ return ['arxivId', 'doi', 's2PaperId', 'openReviewId', 'aclId', 'title']
83
+ .flatMap(key => identity[key] ? [`${key}:${identity[key]}`] : []);
84
+ }
85
+ /** REF spelling is case-sensitive, including the optional legacy suffix letter. */
86
+ export const REF_ID_SOURCE = 'REF-\\d+[a-zA-Z]?';
87
+ /** Match whole tokens in prose and paths without accepting a malformed ID prefix. */
88
+ export const REF_ID_PATTERN = `(?<![A-Za-z0-9_])${REF_ID_SOURCE}(?![A-Za-z0-9_])`;
89
+ const REF_ID_FULL = new RegExp(`^${REF_ID_SOURCE}$`);
90
+ export function refIdsInText(text) {
91
+ return text.match(new RegExp(REF_ID_PATTERN, 'g')) ?? [];
92
+ }
93
+ /** Exact lexical REF identity: preserve zero padding and suffix case. */
94
+ export function isRefId(value) {
95
+ return value.trim() === value && REF_ID_FULL.test(value);
96
+ }
97
+ /** Read the REF token before a slug or extension; never normalize its spelling. */
98
+ export function refIdFromFilename(filename, extension = '.md') {
99
+ if (!filename.endsWith(extension))
100
+ return null;
101
+ const stem = filename.slice(0, -extension.length);
102
+ const slug = stem.indexOf('-', 4);
103
+ const ref = slug === -1 ? stem : stem.slice(0, slug);
104
+ return isRefId(ref) ? ref : null;
105
+ }
106
+ /** Sort key for REF ids: [numeric, alpha-suffix]. Mirrors build.py ref_sort_key. */
107
+ export function refSortKey(refId) {
108
+ const m = isRefId(refId) ? refId.match(/^REF-(\d+)([a-zA-Z]?)$/) : null;
109
+ return m ? [parseInt(m[1], 10), m[2]] : [999999, refId];
110
+ }
111
+ /** Compare two REF ids by (numeric, suffix). */
112
+ export function compareRefId(a, b) {
113
+ const [an, as_] = refSortKey(a);
114
+ const [bn, bs] = refSortKey(b);
115
+ return an !== bn ? an - bn : as_ < bs ? -1 : as_ > bs ? 1 : 0;
116
+ }
117
+ //# sourceMappingURL=identity.js.map
@@ -4,6 +4,7 @@
4
4
  * @module research
5
5
  */
6
6
  export * from './types.js';
7
+ export * from './identity.js';
7
8
  export * from './clients/base.js';
8
9
  export * from './clients/semantic-scholar.js';
9
10
  export * from './clients/crossref.js';