@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.
- package/agentic/code/addons/aiwg-utils/rules/anti-laziness.core.md +13 -0
- package/agentic/code/addons/aiwg-utils/rules/anti-laziness.md +118 -0
- package/dist/src/artifacts/corpus-tools/cli.js +32 -0
- package/dist/src/artifacts/corpus-tools/discovery-log.js +1 -1
- package/dist/src/artifacts/corpus-tools/expand-cli.js +89 -0
- package/dist/src/artifacts/corpus-tools/expand-queue.js +38 -0
- package/dist/src/artifacts/corpus-tools/expand-state.js +40 -0
- package/dist/src/artifacts/corpus-tools/expand.js +125 -0
- package/dist/src/artifacts/corpus-tools/resolve-cli.js +91 -0
- package/dist/src/artifacts/corpus-tools/resolve-corpus.js +41 -0
- package/dist/src/artifacts/corpus-tools/resolve.js +105 -0
- package/dist/src/cli/handlers/doctor-args.js +40 -0
- package/dist/src/cli/handlers/doctor-help.js +4 -2
- package/dist/src/cli/handlers/utilities.js +5 -31
- package/dist/src/config/worker-context.js +33 -4
- package/dist/src/decision/heldout/collector.js +1 -1
- package/dist/src/features/catalog.js +1 -1
- package/dist/src/gates/evaluate.js +2 -2
- package/dist/src/gates/heldout.js +42 -0
- package/dist/src/gates/index.js +2 -1
- package/dist/src/models/worker-installation-store.mjs +228 -0
- package/dist/src/models/worker-installation.mjs +7 -162
- package/dist/src/providers/provider-definitions.js +10 -10
- package/dist/src/research/clients/arxiv.js +10 -4
- package/dist/src/research/clients/base.js +5 -4
- package/dist/src/research/clients/crossref.js +9 -1
- package/dist/src/research/clients/semantic-scholar.js +73 -44
- package/dist/src/research/identity.js +85 -0
- package/dist/src/research/index.js +1 -0
- package/dist/src/research/reference-match.js +89 -0
- package/dist/src/rules/core-startup.d.mts +2 -0
- package/dist/src/rules/core-startup.mjs +31 -0
- package/dist/src/smiths/context-pipeline/agents-md.js +34 -0
- package/dist/src/smiths/context-pipeline/aiwg-md.js +3 -0
- package/dist/src/smiths/context-pipeline/bridge-ownership.js +50 -0
- package/dist/src/smiths/context-pipeline/generator.js +40 -104
- package/dist/src/smiths/context-pipeline/managed-hook.js +10 -0
- package/package.json +4 -2
- package/tools/agents/deploy-agents.mjs +2 -123
- package/tools/agents/providers/antigravity.mjs +1 -1
- package/tools/agents/providers/context-write.mjs +12 -0
- package/tools/agents/providers/grok-build.mjs +8 -5
- package/tools/agents/providers/hermes-skill-lifecycle.mjs +144 -0
- package/tools/agents/providers/hermes-startup.mjs +209 -0
- package/tools/agents/providers/hermes.mjs +9 -359
- package/tools/agents/providers/model-wrapper.mjs +5 -1
- package/tools/agents/providers/muse.mjs +3 -3
- package/tools/agents/providers/pi.mjs +1 -1
- package/tools/agents/providers/rule-delivery.mjs +23 -225
- package/tools/agents/providers/rule-presentation.mjs +13 -4
- package/tools/agents/providers/rule-projection.mjs +119 -0
- package/tools/agents/providers/rule-startup.mjs +70 -0
- package/tools/agents/providers/stale-artifact-prune.mjs +128 -0
- package/tools/agents/providers/warp.mjs +2 -2
- package/tools/agents/providers/windsurf.mjs +11 -57
- 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 {
|
|
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
|
-
|
|
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
|
-
|
|
970
|
-
|
|
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
|
-
}
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
|
814
|
-
// indexed
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
|
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
|
|
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(
|
|
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
|
-
|
|
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:
|
|
19
|
+
maxTokens: 1,
|
|
17
20
|
refillRate: 1, // 1 request per second
|
|
18
|
-
currentTokens:
|
|
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
|
-
|
|
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
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
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,
|