@aiwg/cli 2026.10.15 → 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 (180) hide show
  1. package/agentic/code/providers/pi/aiwg-bridge.ts +45 -7
  2. package/dist/src/artifacts/citation-parser.js +7 -6
  3. package/dist/src/artifacts/corpus-tools/citation-densify.js +4 -2
  4. package/dist/src/artifacts/corpus-tools/cli.js +8 -3
  5. package/dist/src/artifacts/corpus-tools/discovery-log.js +26 -24
  6. package/dist/src/artifacts/corpus-tools/expand-cli.js +3 -2
  7. package/dist/src/artifacts/corpus-tools/expand-dates.js +107 -0
  8. package/dist/src/artifacts/corpus-tools/expand-queue.js +4 -1
  9. package/dist/src/artifacts/corpus-tools/expand-review.js +104 -0
  10. package/dist/src/artifacts/corpus-tools/expand-state.js +17 -1
  11. package/dist/src/artifacts/corpus-tools/expand.js +16 -17
  12. package/dist/src/artifacts/corpus-tools/induction-audit.js +7 -6
  13. package/dist/src/artifacts/corpus-tools/integrity-scan.js +3 -3
  14. package/dist/src/artifacts/corpus-tools/radar-shared.js +7 -9
  15. package/dist/src/artifacts/corpus-tools/ref-files.js +11 -0
  16. package/dist/src/artifacts/corpus-tools/resolve-cli.js +11 -3
  17. package/dist/src/artifacts/corpus-tools/resolve.js +23 -9
  18. package/dist/src/artifacts/corpus-tools/retrieval-lab.js +2 -1
  19. package/dist/src/artifacts/corpus-tools/sidecar-lint.js +4 -4
  20. package/dist/src/artifacts/corpus-tools/sidecar-repair.js +2 -1
  21. package/dist/src/artifacts/corpus-views/ref-parser.js +3 -17
  22. package/dist/src/artifacts/graph-query.js +5 -3
  23. package/dist/src/artifacts/hybrid-query.js +11 -2
  24. package/dist/src/artifacts/index-refresh.js +2 -0
  25. package/dist/src/cli/handlers/daemon.js +17 -1
  26. package/dist/src/cli/handlers/doctor-args.js +10 -5
  27. package/dist/src/cli/handlers/doctor-help.js +4 -1
  28. package/dist/src/cli/handlers/index.js +2 -2
  29. package/dist/src/cli/handlers/models-resource-sample.js +10 -0
  30. package/dist/src/cli/handlers/models.js +3 -2
  31. package/dist/src/cli/handlers/regenerate.js +8 -16
  32. package/dist/src/cli/handlers/sessions.js +7 -7
  33. package/dist/src/cli/handlers/subcommands.js +8 -0
  34. package/dist/src/cli/handlers/update.js +157 -0
  35. package/dist/src/cli/handlers/use.js +14 -4
  36. package/dist/src/cli/handlers/utilities.js +3 -560
  37. package/dist/src/cli/handlers/utility-doctor.js +412 -0
  38. package/dist/src/cli/services/deployment-verification.js +0 -1
  39. package/dist/src/config/aiwg-config.js +2 -1
  40. package/dist/src/config/authorization-cli.js +7 -3
  41. package/dist/src/config/dispatch-thresholds-runtime.d.mts +3 -2
  42. package/dist/src/config/dispatch-thresholds-runtime.mjs +17 -7
  43. package/dist/src/config/framework-aliases.js +12 -0
  44. package/dist/src/config/host-resource-report.d.mts +19 -0
  45. package/dist/src/config/host-resource-report.mjs +80 -0
  46. package/dist/src/config/host-resource-runtime.d.mts +34 -0
  47. package/dist/src/config/host-resource-runtime.mjs +293 -0
  48. package/dist/src/config/installed-selection.js +22 -0
  49. package/dist/src/config/worker-invocation-marker.d.mts +1 -0
  50. package/dist/src/config/worker-invocation-marker.mjs +2 -0
  51. package/dist/src/decision/heldout/access.js +74 -0
  52. package/dist/src/decision/heldout/calibration.js +1 -0
  53. package/dist/src/decision/heldout/collector.js +8 -1
  54. package/dist/src/effects/verifiers/file.js +22 -5
  55. package/dist/src/extensions/claude-attribution.js +82 -0
  56. package/dist/src/extensions/claude-hooks-installer.js +115 -69
  57. package/dist/src/extensions/commands/daemon.js +109 -0
  58. package/dist/src/extensions/commands/definitions.js +5 -89
  59. package/dist/src/gates/heldout.js +17 -7
  60. package/dist/src/lint/check-patterns.js +163 -0
  61. package/dist/src/lint/checks.js +268 -0
  62. package/dist/src/lint/reference-resolution.js +54 -0
  63. package/dist/src/lint/runner.js +3 -465
  64. package/dist/src/mcp/helpers.mjs +11 -1
  65. package/dist/src/memory/project-registry.js +44 -4
  66. package/dist/src/models/worker-plan.js +36 -5
  67. package/dist/src/models/wrapper-deployment.js +25 -12
  68. package/dist/src/models/wrapper-enforcement.js +47 -7
  69. package/dist/src/network-analysis/research.js +2 -1
  70. package/dist/src/policy/hitl-check.js +14 -4
  71. package/dist/src/policy/hitl-consume.js +54 -0
  72. package/dist/src/policy/hitl-receipt.js +2 -0
  73. package/dist/src/policy/hitl.js +11 -3
  74. package/dist/src/providers/provider-context-contracts.js +162 -0
  75. package/dist/src/providers/provider-definition-schema.js +136 -0
  76. package/dist/src/providers/provider-definitions.js +8 -1298
  77. package/dist/src/providers/provider-seeds-1.js +360 -0
  78. package/dist/src/providers/provider-seeds-2.js +387 -0
  79. package/dist/src/providers/provider-seeds-3.js +262 -0
  80. package/dist/src/research/clients/arxiv.js +4 -30
  81. package/dist/src/research/clients/base.js +48 -22
  82. package/dist/src/research/identity.js +34 -2
  83. package/dist/src/research/query-cli.js +3 -87
  84. package/dist/src/research/query-options.js +87 -0
  85. package/dist/src/research/reference-match.js +70 -24
  86. package/dist/src/research/services/acquisition.js +9 -7
  87. package/dist/src/research/services/citation.js +5 -2
  88. package/dist/src/research/types.js +2 -0
  89. package/dist/src/serve/mission-conductor.js +48 -4
  90. package/dist/src/sessions/adapters/grok-build-native.js +23 -0
  91. package/dist/src/sessions/adapters/grok-build.js +14 -7
  92. package/dist/src/sessions/workspace-discovery.js +5 -5
  93. package/dist/src/smiths/context-pipeline/aiwg-md.js +16 -46
  94. package/dist/src/smiths/context-pipeline/claude-hook.js +1 -1
  95. package/dist/src/smiths/context-pipeline/code-regions.js +28 -0
  96. package/dist/src/smiths/context-pipeline/finalization.js +81 -51
  97. package/dist/src/smiths/context-pipeline/generator.js +9 -10
  98. package/dist/src/smiths/context-pipeline/managed-hook.js +1 -1
  99. package/dist/src/smiths/context-pipeline/muse-bridge.js +2 -2
  100. package/dist/src/smiths/context-pipeline/provider-policy.js +6 -12
  101. package/dist/src/smiths/context-pipeline/workspace-audit.js +299 -0
  102. package/dist/src/smiths/context-pipeline/workspace-bootstrap.js +148 -0
  103. package/dist/src/smiths/context-pipeline/workspace-context-shared.js +111 -0
  104. package/dist/src/smiths/context-pipeline/workspace-context.js +8 -1373
  105. package/dist/src/smiths/context-pipeline/workspace-doctor.js +192 -0
  106. package/dist/src/smiths/context-pipeline/workspace-document.js +201 -0
  107. package/dist/src/smiths/context-pipeline/workspace-extraction.js +205 -0
  108. package/dist/src/smiths/context-pipeline/workspace-migration.js +250 -0
  109. package/package.json +10 -1
  110. package/schemas/decision/D29Study.v10.schema.json +65 -0
  111. package/tools/agents/deploy-agents.mjs +10 -0
  112. package/tools/agents/providers/claude-post-deploy.mjs +12 -1
  113. package/tools/agents/providers/context-write.mjs +4 -0
  114. package/tools/agents/providers/pi.mjs +3 -1
  115. package/tools/agents/providers/rule-delivery-surface.mjs +332 -0
  116. package/tools/agents/providers/rule-delivery.mjs +20 -1144
  117. package/tools/agents/providers/rule-deployment-commit.mjs +144 -0
  118. package/tools/agents/providers/rule-deployment-prepare.mjs +452 -0
  119. package/tools/agents/providers/rule-deployment-state.mjs +300 -0
  120. package/tools/daemon/README.md +511 -0
  121. package/tools/daemon/adapters/base-adapter.mjs +84 -0
  122. package/tools/daemon/adapters/webhook-adapter.mjs +107 -0
  123. package/tools/daemon/agent-supervisor.mjs +299 -0
  124. package/tools/daemon/automation-engine.mjs +310 -0
  125. package/tools/daemon/autonomous-engine.mjs +346 -0
  126. package/tools/daemon/behavior-loader.mjs +316 -0
  127. package/tools/daemon/behavior.mjs +174 -0
  128. package/tools/daemon/concierge/intent-router.mjs +401 -0
  129. package/tools/daemon/concierge/orchestrator.mjs +272 -0
  130. package/tools/daemon/concierge/response-translator.mjs +462 -0
  131. package/tools/daemon/config.mjs +377 -0
  132. package/tools/daemon/cron-scheduler.mjs +178 -0
  133. package/tools/daemon/daemon-main.mjs +1169 -0
  134. package/tools/daemon/event-router.mjs +84 -0
  135. package/tools/daemon/file-watcher.mjs +383 -0
  136. package/tools/daemon/index.mjs +1181 -0
  137. package/tools/daemon/init-profile.mjs +124 -0
  138. package/tools/daemon/ipc-client.mjs +197 -0
  139. package/tools/daemon/ipc-ops-handlers.mjs +236 -0
  140. package/tools/daemon/ipc-server.mjs +275 -0
  141. package/tools/daemon/maintenance-owner.mjs +79 -0
  142. package/tools/daemon/memory-manager.mjs +386 -0
  143. package/tools/daemon/message-router.mjs +194 -0
  144. package/tools/daemon/provider-watcher.mjs +585 -0
  145. package/tools/daemon/pty-adapter.mjs +420 -0
  146. package/tools/daemon/repl-chat.mjs +359 -0
  147. package/tools/daemon/resource-bounds.mjs +88 -0
  148. package/tools/daemon/sandbox-transport.mjs +295 -0
  149. package/tools/daemon/scheduled-task-runner.mjs +535 -0
  150. package/tools/daemon/task-store.mjs +450 -0
  151. package/tools/daemon/tmux-manager.mjs +324 -0
  152. package/tools/daemon/update-policy.mjs +517 -0
  153. package/tools/daemon/web-server.mjs +399 -0
  154. package/tools/daemon/web-ui/index.html +585 -0
  155. package/tools/daemon/web-ui/styles.css +156 -0
  156. package/tools/docker/Dockerfile.daemon +35 -0
  157. package/tools/docker/container-manager.mjs +291 -0
  158. package/tools/messaging/adapter-registry.mjs +230 -0
  159. package/tools/messaging/adapters/base.mjs +326 -0
  160. package/tools/messaging/adapters/discord.mjs +462 -0
  161. package/tools/messaging/adapters/slack.mjs +402 -0
  162. package/tools/messaging/adapters/telegram.mjs +552 -0
  163. package/tools/messaging/chat-handler.mjs +297 -0
  164. package/tools/messaging/command-router.mjs +269 -0
  165. package/tools/messaging/event-bus.mjs +199 -0
  166. package/tools/messaging/index.mjs +456 -0
  167. package/tools/messaging/message-formatter.mjs +320 -0
  168. package/tools/messaging/room-manager.mjs +277 -0
  169. package/tools/messaging/types.mjs +94 -0
  170. package/tools/providers/pi-bridge-policy.mjs +4 -0
  171. package/tools/ralph-external/daemon-supervisor.mjs +394 -0
  172. package/tools/ralph-external/lib/behavior-registry.mjs +270 -0
  173. package/tools/ralph-external/lib/worker-invocation-processes.mjs +3 -2
  174. package/tools/ralph-external/lib/worker-isolation-args.mjs +217 -0
  175. package/tools/ralph-external/lib/worker-isolation-status.mjs +19 -0
  176. package/tools/ralph-external/lib/worker-isolation.mjs +11 -237
  177. package/tools/ralph-external/lib/worker-overflow.mjs +10 -2
  178. package/tools/ralph-external/lib/worker-unit-cleanup.mjs +72 -0
  179. package/tools/ralph-external/session-launcher.mjs +7 -7
  180. package/tools/scripts/resource-preflight.mjs +3 -242
@@ -15,9 +15,9 @@ export class ArxivClient extends BaseClient {
15
15
  baseUrl: 'http://export.arxiv.org/api',
16
16
  timeout: 30000,
17
17
  rateLimit: {
18
- maxTokens: 3,
18
+ maxTokens: 1,
19
19
  refillRate: 1 / 3, // 1 request per 3 seconds
20
- currentTokens: 3,
20
+ currentTokens: 1,
21
21
  lastRefill: Date.now(),
22
22
  },
23
23
  retry: {
@@ -39,7 +39,7 @@ export class ArxivClient extends BaseClient {
39
39
  id_list: normalizedId,
40
40
  max_results: 1,
41
41
  });
42
- const xmlText = await this.requestXml(url);
42
+ const xmlText = await this.requestText(url);
43
43
  const papers = this.parseAtomFeed(xmlText);
44
44
  if (papers.length === 0) {
45
45
  throw new ResearchError(ResearchErrorCode.RF_300, `arXiv paper not found: ${arxivId}`);
@@ -56,7 +56,7 @@ export class ArxivClient extends BaseClient {
56
56
  start: offset,
57
57
  max_results: limit,
58
58
  });
59
- const xmlText = await this.requestXml(url);
59
+ const xmlText = await this.requestText(url);
60
60
  const papers = this.parseAtomFeed(xmlText);
61
61
  // arXiv doesn't provide total count, so we estimate
62
62
  const hasMore = papers.length === limit;
@@ -68,32 +68,6 @@ export class ArxivClient extends BaseClient {
68
68
  hasMore,
69
69
  };
70
70
  }
71
- /**
72
- * Request XML from arXiv API
73
- */
74
- async requestXml(url) {
75
- await this.rateLimiter.acquire();
76
- const controller = new AbortController();
77
- const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
78
- try {
79
- const response = await fetch(url, {
80
- signal: controller.signal,
81
- });
82
- if (!response.ok) {
83
- throw new ResearchError(ResearchErrorCode.RF_200, `arXiv API error: ${response.status}`);
84
- }
85
- return await response.text();
86
- }
87
- catch (error) {
88
- if (error instanceof Error && error.name === 'AbortError') {
89
- throw new ResearchError(ResearchErrorCode.RF_104, `Request timeout after ${this.config.timeout}ms`, error);
90
- }
91
- throw error;
92
- }
93
- finally {
94
- clearTimeout(timeoutId);
95
- }
96
- }
97
71
  /**
98
72
  * Parse Atom XML feed from arXiv
99
73
  */
@@ -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));
@@ -73,10 +83,14 @@ export class BaseClient {
73
83
  // Execute with retry
74
84
  return this.executeWithRetry(url, options);
75
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
+ }
76
90
  /**
77
91
  * Execute request with exponential backoff retry
78
92
  */
79
- async executeWithRetry(url, options, attempt = 0, firstError) {
93
+ async executeWithRetry(url, options, attempt = 0, firstError, read = response => response.json()) {
80
94
  // Every attempt consumes a token, after any retry backoff and before timeout.
81
95
  await this.rateLimiter.acquire();
82
96
  const controller = new AbortController();
@@ -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;
@@ -71,8 +71,8 @@ export function normalizeIdentity(value) {
71
71
  ...(arxiv ? { arxivId: arxiv.id, arxivVersion: arxiv.version ?? (typeof fields.arxivVersion === 'number' ? fields.arxivVersion : undefined) } : {}),
72
72
  doi: normalizeDoi(str('doi', 'DOI') ?? ''),
73
73
  s2PaperId: str('s2PaperId', 's2_paper_id', 'paperId')?.toLowerCase(),
74
- openReviewId: str('openReviewId', 'openreview_id'),
75
- aclId: str('aclId', 'acl_id'),
74
+ openReviewId: str('openReviewId', 'openreview_id')?.toLowerCase(),
75
+ aclId: str('aclId', 'acl_id')?.toLowerCase(),
76
76
  title: str('title') ? normalizeTitle(str('title')) : undefined,
77
77
  };
78
78
  }
@@ -82,4 +82,36 @@ export function identityKeys(value) {
82
82
  return ['arxivId', 'doi', 's2PaperId', 'openReviewId', 'aclId', 'title']
83
83
  .flatMap(key => identity[key] ? [`${key}:${identity[key]}`] : []);
84
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
+ }
85
117
  //# sourceMappingURL=identity.js.map
@@ -1,4 +1,6 @@
1
1
  import fs from "node:fs";
2
+ import { parseArgs, usage } from "./query-options.js";
3
+ import { refIdsInText } from "./identity.js";
2
4
  import path from "node:path";
3
5
  import { parseFrontmatter } from "../artifacts/index-builder.js";
4
6
  import { loadGraphIndexFile } from "../artifacts/index-reader.js";
@@ -36,92 +38,6 @@ const STOPWORDS = new Set([
36
38
  "say",
37
39
  "evidence",
38
40
  ]);
39
- function usage() {
40
- return [
41
- "Usage: aiwg research-query <question> [--backend fortemi-core|local] [--graph <name>]",
42
- " [--depth quick|thorough] [--sources-only] [--max-sources N]",
43
- " [--include-diagnostics] [--json] [--save]",
44
- ].join("\n");
45
- }
46
- function flagValue(args, flag, errorMessage) {
47
- const index = args.indexOf(flag);
48
- if (index < 0)
49
- return undefined;
50
- const value = args[index + 1];
51
- if (!value || value.startsWith("--")) {
52
- throw new Error(errorMessage);
53
- }
54
- return value;
55
- }
56
- function positiveIntegerFlag(args, flag, defaultValue, errorMessage) {
57
- const value = flagValue(args, flag, errorMessage);
58
- if (value === undefined)
59
- return defaultValue;
60
- const parsed = Number.parseInt(value, 10);
61
- if (!Number.isInteger(parsed) || parsed < 1 || String(parsed) !== value) {
62
- throw new Error(errorMessage);
63
- }
64
- return parsed;
65
- }
66
- function hasFlag(args, flag) {
67
- return args.includes(flag);
68
- }
69
- function stripFlags(args) {
70
- const valueFlags = new Set([
71
- "--backend",
72
- "--graph",
73
- "--depth",
74
- "--max-sources",
75
- ]);
76
- const bareFlags = new Set([
77
- "--sources-only",
78
- "--include-diagnostics",
79
- "--json",
80
- "--save",
81
- ]);
82
- const question = [];
83
- for (let index = 0; index < args.length; index++) {
84
- const arg = args[index];
85
- if (valueFlags.has(arg)) {
86
- index++;
87
- continue;
88
- }
89
- if (bareFlags.has(arg))
90
- continue;
91
- question.push(arg);
92
- }
93
- return question;
94
- }
95
- function parseArgs(args) {
96
- if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
97
- console.log(usage());
98
- process.exit(0);
99
- }
100
- const backend = flagValue(args, "--backend", "--backend must be local or fortemi-core");
101
- if (backend && backend !== "local" && backend !== "fortemi-core") {
102
- throw new Error("--backend must be local or fortemi-core");
103
- }
104
- const depth = (flagValue(args, "--depth", "--depth must be quick or thorough") ?? "thorough");
105
- if (depth !== "quick" && depth !== "thorough") {
106
- throw new Error("--depth must be quick or thorough");
107
- }
108
- const maxSources = positiveIntegerFlag(args, "--max-sources", 10, "--max-sources must be a positive integer");
109
- const question = stripFlags(args).join(" ").trim();
110
- if (!question)
111
- throw new Error("question is required");
112
- return {
113
- question,
114
- backend: backend ?? "fortemi-core",
115
- graph: (flagValue(args, "--graph", "--graph requires a graph name") ??
116
- "project"),
117
- depth,
118
- maxSources,
119
- sourcesOnly: hasFlag(args, "--sources-only"),
120
- includeDiagnostics: hasFlag(args, "--include-diagnostics"),
121
- json: hasFlag(args, "--json"),
122
- save: hasFlag(args, "--save"),
123
- };
124
- }
125
41
  function tokens(text) {
126
42
  return text
127
43
  .toLowerCase()
@@ -141,7 +57,7 @@ function readEntryBody(cwd, entryPath) {
141
57
  }
142
58
  function entryId(entry) {
143
59
  const text = [entry.name, entry.title, entry.path].filter(Boolean).join(" ");
144
- return (text.match(/\bREF-\d+\b/i)?.[0]?.toUpperCase() ??
60
+ return (refIdsInText(text)[0] ??
145
61
  text.match(/\bPROF-[A-Z0-9-]+/i)?.[0]?.toUpperCase() ??
146
62
  path.basename(entry.path).replace(/\.[^.]+$/, ""));
147
63
  }
@@ -0,0 +1,87 @@
1
+ export function usage() {
2
+ return [
3
+ "Usage: aiwg research-query <question> [--backend fortemi-core|local] [--graph <name>]",
4
+ " [--depth quick|thorough] [--sources-only] [--max-sources N]",
5
+ " [--include-diagnostics] [--json] [--save]",
6
+ ].join("\n");
7
+ }
8
+ function flagValue(args, flag, errorMessage) {
9
+ const index = args.indexOf(flag);
10
+ if (index < 0)
11
+ return undefined;
12
+ const value = args[index + 1];
13
+ if (!value || value.startsWith("--")) {
14
+ throw new Error(errorMessage);
15
+ }
16
+ return value;
17
+ }
18
+ function positiveIntegerFlag(args, flag, defaultValue, errorMessage) {
19
+ const value = flagValue(args, flag, errorMessage);
20
+ if (value === undefined)
21
+ return defaultValue;
22
+ const parsed = Number.parseInt(value, 10);
23
+ if (!Number.isInteger(parsed) || parsed < 1 || String(parsed) !== value) {
24
+ throw new Error(errorMessage);
25
+ }
26
+ return parsed;
27
+ }
28
+ function hasFlag(args, flag) {
29
+ return args.includes(flag);
30
+ }
31
+ function stripFlags(args) {
32
+ const valueFlags = new Set([
33
+ "--backend",
34
+ "--graph",
35
+ "--depth",
36
+ "--max-sources",
37
+ ]);
38
+ const bareFlags = new Set([
39
+ "--sources-only",
40
+ "--include-diagnostics",
41
+ "--json",
42
+ "--save",
43
+ ]);
44
+ const question = [];
45
+ for (let index = 0; index < args.length; index++) {
46
+ const arg = args[index];
47
+ if (valueFlags.has(arg)) {
48
+ index++;
49
+ continue;
50
+ }
51
+ if (bareFlags.has(arg))
52
+ continue;
53
+ question.push(arg);
54
+ }
55
+ return question;
56
+ }
57
+ export function parseArgs(args) {
58
+ if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
59
+ console.log(usage());
60
+ process.exit(0);
61
+ }
62
+ const backend = flagValue(args, "--backend", "--backend must be local or fortemi-core");
63
+ if (backend && backend !== "local" && backend !== "fortemi-core") {
64
+ throw new Error("--backend must be local or fortemi-core");
65
+ }
66
+ const depth = (flagValue(args, "--depth", "--depth must be quick or thorough") ?? "thorough");
67
+ if (depth !== "quick" && depth !== "thorough") {
68
+ throw new Error("--depth must be quick or thorough");
69
+ }
70
+ const maxSources = positiveIntegerFlag(args, "--max-sources", 10, "--max-sources must be a positive integer");
71
+ const question = stripFlags(args).join(" ").trim();
72
+ if (!question)
73
+ throw new Error("question is required");
74
+ return {
75
+ question,
76
+ backend: backend ?? "fortemi-core",
77
+ graph: (flagValue(args, "--graph", "--graph requires a graph name") ??
78
+ "project"),
79
+ depth,
80
+ maxSources,
81
+ sourcesOnly: hasFlag(args, "--sources-only"),
82
+ includeDiagnostics: hasFlag(args, "--include-diagnostics"),
83
+ json: hasFlag(args, "--json"),
84
+ save: hasFlag(args, "--save"),
85
+ };
86
+ }
87
+ //# sourceMappingURL=query-options.js.map
@@ -1,5 +1,5 @@
1
1
  // Parse partial citations and score distinct candidate identities without choosing close matches.
2
- import { normalizeIdentity, normalizeTitle, parseResearchIdentifier } from './identity.js';
2
+ import { normalizeIdentity, normalizeTitle, parseArxivId, parseResearchIdentifier } from './identity.js';
3
3
  /** Common quoted, APA-style and title-plus-year citations; retain the untouched input. */
4
4
  export function parsePartialReference(input, year) {
5
5
  const identifier = parseResearchIdentifier(input);
@@ -22,12 +22,39 @@ export function parsePartialReference(input, year) {
22
22
  rest = rest.replace(/^[\s.,;:()[\]{}"']+|[\s.,;:()[\]{}"']+$/g, '').trim();
23
23
  return { input, identifier, title: normalizeTitle(rest) ? rest : undefined, year: year ?? (inferredYear ? Number(inferredYear) : undefined), firstAuthor };
24
24
  }
25
- /** Jaccard token-set similarity avoids substring matches scoring as exact titles. */
25
+ /** Token coverage discounted by sequence order; ordered prefixes retain coverage scores. */
26
26
  export function titleSimilarity(left, right) {
27
- const a = new Set(normalizeTitle(left).split(' ').filter(Boolean));
28
- const b = new Set(normalizeTitle(right).split(' ').filter(Boolean));
29
- const union = new Set([...a, ...b]).size;
30
- return union ? [...a].filter(token => b.has(token)).length / union : 0;
27
+ if (normalizeTitle(left) && normalizeTitle(left) === normalizeTitle(right))
28
+ return 1;
29
+ const a = normalizeTitle(left).split(' ').filter(Boolean);
30
+ const b = normalizeTitle(right).split(' ').filter(Boolean);
31
+ if (!a.length || !b.length)
32
+ return 0;
33
+ const uniqueA = new Set(a), uniqueB = new Set(b);
34
+ const coverage = [...uniqueA].filter(token => uniqueB.has(token)).length / new Set([...a, ...b]).size;
35
+ const row = Array(b.length + 1).fill(0);
36
+ for (const token of a) {
37
+ let diagonal = 0;
38
+ for (let j = 1; j <= b.length; j++) {
39
+ const previous = row[j];
40
+ row[j] = token === b[j - 1] ? diagonal + 1 : Math.max(row[j], row[j - 1]);
41
+ diagonal = previous;
42
+ }
43
+ }
44
+ // Repeated tokens must also reduce similarity even when their token sets agree.
45
+ const repetition = Math.min(uniqueA.size / a.length, uniqueB.size / b.length);
46
+ return coverage * row[b.length] / Math.min(a.length, b.length) * repetition;
47
+ }
48
+ /** Incomplete short/generic titles require an ID; unqualified very short titles need metadata. */
49
+ export function needsTitleDisambiguation(reference, candidates, incomplete) {
50
+ if (!reference.title || candidates[0]?.score_parts.identifier === 1)
51
+ return false;
52
+ const title = normalizeTitle(reference.title);
53
+ const tokens = title.split(' ');
54
+ const informative = tokens.filter(token => !/^(?:a|an|the|of|for|in|on|and|with|to|is|all|you)$/.test(token));
55
+ const exact = candidates.filter(candidate => normalizeTitle(candidate.paper.title) === title).length;
56
+ return (incomplete && (tokens.length <= 4 || informative.length <= 4 || exact > 1)) ||
57
+ (tokens.length <= 2 && reference.year === undefined && !reference.firstAuthor);
31
58
  }
32
59
  function surname(name) {
33
60
  return normalizeTitle(name.includes(',') ? name.split(',')[0] : name.trim().split(/\s+/).at(-1) ?? '');
@@ -60,29 +87,48 @@ export function classifyCandidates(candidates) {
60
87
  const margin = best - (candidates[1]?.score ?? 0);
61
88
  return best + 1e-12 >= 0.92 && margin + 1e-12 >= 0.05 ? 'resolved' : 'ambiguous';
62
89
  }
63
- /** Merge only corroborated identifiers; title equality alone does not establish identity. */
90
+ /** Shared IDs require title similarity >= 0.5; title agreement never establishes identity. */
64
91
  export function mergePapers(papers) {
92
+ const ids = ['arxivId', 'doi', 's2PaperId', 'openReviewId', 'aclId'];
93
+ const published = (paper) => Boolean(paper.doi && !parseArxivId(paper.doi));
94
+ const linked = (left, right) => {
95
+ const a = normalizeIdentity(left), b = normalizeIdentity(right);
96
+ if (titleSimilarity(a.title ?? '', b.title ?? '') < 0.5)
97
+ return false;
98
+ if (ids.some(key => a[key] && b[key] && a[key] !== b[key] &&
99
+ !(key === 'doi' && a.arxivId && a.arxivId === b.arxivId && (parseArxivId(a.doi) || parseArxivId(b.doi)))))
100
+ return false;
101
+ return ids.some(key => a[key] && a[key] === b[key]);
102
+ };
103
+ const combine = (left, right) => {
104
+ // A published CrossRef record owns proceedings metadata; other sources fill gaps.
105
+ const preferRight = (published(right) && !published(left)) ||
106
+ (published(right) && right.source === 'crossref' && left.source !== 'crossref');
107
+ const [primary, alternate] = preferRight ? [right, left] : [left, right];
108
+ const result = { ...primary };
109
+ for (const [key, value] of Object.entries(alternate)) {
110
+ if (value !== undefined && (!result[key] ||
111
+ (Array.isArray(result[key]) && result[key].length === 0))) {
112
+ result[key] = value;
113
+ }
114
+ }
115
+ return result;
116
+ };
65
117
  const merged = [];
66
118
  for (const paper of papers) {
67
- const identity = normalizeIdentity(paper);
68
- const previous = merged.find(existing => {
69
- const other = normalizeIdentity(existing);
70
- const ids = ['arxivId', 'doi', 's2PaperId', 'openReviewId', 'aclId'];
71
- if (ids.some(key => identity[key] && other[key] && identity[key] !== other[key]))
72
- return false;
73
- return ids.some(key => identity[key] && identity[key] === other[key]);
74
- });
75
- if (!previous) {
76
- merged.push({ ...paper });
77
- continue;
78
- }
79
- // Source order determines metadata precedence; later sources only fill missing fields.
80
- for (const [key, value] of Object.entries(paper)) {
81
- if (value !== undefined && (!previous[key] ||
82
- (Array.isArray(previous[key]) && previous[key].length === 0))) {
83
- previous[key] = value;
119
+ // Comparison keys are canonical; OpenReview/ACL spelling remains source metadata.
120
+ const { title: _title, openReviewId: _review, aclId: _acl, ...identity } = normalizeIdentity(paper);
121
+ let work = { ...paper, ...Object.fromEntries(Object.entries(identity).filter(([, value]) => value !== undefined)) };
122
+ // A late S2 bridge may join two components already encountered in source order.
123
+ for (let i = 0; i < merged.length;) {
124
+ if (!linked(work, merged[i])) {
125
+ i++;
126
+ continue;
84
127
  }
128
+ work = combine(merged.splice(i, 1)[0], work);
129
+ i = 0;
85
130
  }
131
+ merged.push(work);
86
132
  }
87
133
  return merged;
88
134
  }
@@ -6,6 +6,7 @@
6
6
  import { promises as fs } from 'fs';
7
7
  import { join, dirname } from 'path';
8
8
  import { createHash } from 'crypto';
9
+ import { isRefId, refIdFromFilename, refSortKey } from '../identity.js';
9
10
  import { UnpaywallClient } from '../clients/unpaywall.js';
10
11
  /**
11
12
  * Acquisition service for downloading research papers
@@ -87,8 +88,8 @@ export class AcquisitionService {
87
88
  }
88
89
  // Extract numbers from REF-XXX format
89
90
  const refNumbers = refs
90
- .filter((ref) => /^REF-\d{3}$/.test(ref))
91
- .map((ref) => parseInt(ref.substring(4), 10))
91
+ .filter(isRefId)
92
+ .map((ref) => refSortKey(ref)[0])
92
93
  .filter((n) => !isNaN(n));
93
94
  // Find next available number
94
95
  const maxNumber = refNumbers.length > 0 ? Math.max(...refNumbers) : 0;
@@ -138,7 +139,7 @@ export class AcquisitionService {
138
139
  {
139
140
  id: 'F1',
140
141
  description: 'Assigned globally unique identifier (REF-XXX)',
141
- met: !!source.refId && /^REF-\d{3}$/.test(source.refId),
142
+ met: isRefId(source.refId),
142
143
  },
143
144
  {
144
145
  id: 'F2',
@@ -283,12 +284,13 @@ export class AcquisitionService {
283
284
  async scanExistingRefs() {
284
285
  const refs = [];
285
286
  try {
286
- const files = await fs.readdir(this.downloadDir);
287
+ const files = await fs.readdir(this.downloadDir, { withFileTypes: true });
287
288
  for (const file of files) {
288
- if (file.startsWith('REF-') && file.endsWith('.pdf')) {
289
- const refId = file.substring(0, 7); // REF-XXX
289
+ if (!file.isFile())
290
+ continue;
291
+ const refId = refIdFromFilename(file.name, '.pdf');
292
+ if (refId)
290
293
  refs.push(refId);
291
- }
292
294
  }
293
295
  }
294
296
  catch (error) {
@@ -4,6 +4,7 @@
4
4
  * @module research/services/citation
5
5
  */
6
6
  import { promises as fs } from 'fs';
7
+ import { isRefId, refIdFromFilename } from '../identity.js';
7
8
  /**
8
9
  * Citation service for managing citations and networks
9
10
  */
@@ -37,10 +38,12 @@ export class CitationService {
37
38
  * Validate that a citation exists in corpus
38
39
  */
39
40
  async validateCitation(refId, corpusPath) {
41
+ if (!isRefId(refId))
42
+ return false;
40
43
  const path = corpusPath || this.corpusPath;
41
44
  try {
42
- const files = await fs.readdir(path);
43
- return files.some((file) => file.startsWith(refId));
45
+ const files = await fs.readdir(path, { withFileTypes: true });
46
+ return files.some((file) => file.isFile() && refIdFromFilename(file.name) === refId);
44
47
  }
45
48
  catch (error) {
46
49
  return false;
@@ -37,6 +37,8 @@ export var ResearchErrorCode;
37
37
  export class ResearchError extends Error {
38
38
  code;
39
39
  cause;
40
+ /** Server-directed cooldown, shared by all requests through the client limiter. */
41
+ retryAfterMs;
40
42
  constructor(code, message, cause) {
41
43
  super(message);
42
44
  this.code = code;