dsh-arxiv

A small DeepSeek Harness function plugin for looking papers up on arXiv. It registers exactly two model-facing tools — arxiv_search and arxiv_get — over arXiv's public Atom API, and owns nothing else.

It is deliberately not a science platform. There is no PDF ingest, no full-text extraction, no embedding store, no citation graph, no reference manager. It answers two questions — what has been written about this? and what is this paper? — and hands back metadata and the abstract. If you want the PDF, the tools tell you where it lives; fetching it is somebody else's job.

Read-only, no API key, no credentials, no state.

Install

dsh plugin --profile web add github:jwilson411/dsh-arxiv

dsh plugin forwards to pnpm inside $DSH_HOME/profiles/web, then reconciles the profile against the installed state: because this package's manifest declares dsh.bundle.patch, it is appended to the profile manifest's ordered dsh.profile.bundles list and its patch becomes a layer.

Remove it the same way, with remove in place of add.

Pinned DSH release candidate

This package is written and tested against the pinned release candidate 0.1.1-rc.2 — the current @deepseek-ai/dsh release and the matching @deepseek-ai/dsh-tools@0.1.1-rc.2, which is pinned exactly in devDependencies so tests run against one known API. The peer range is ^0.1.1-rc.2, matching how the harness's own tool packages declare it.

Note that @deepseek-ai/dsh-tools's npm latest tag still points at the older 0.0.1-rc.1; the 0.1.1-rc.2 line is published under next. Pin explicitly rather than relying on the tag.

What it registers

Cordis plugin id	arxiv (the row id in cordis.patch.yml)
Injects	tools — a hard dependency; the plugin waits rather than degrading

Tool	Arguments	Returns
arxiv_search	query (string, required), max_results (integer, optional, 1–25, default 5)	{ query, search_query, max_results, returned, papers[], plugin }
arxiv_get	id (string, required)	{ requested_id, paper, plugin }

Every paper is the same object in both tools:

{
  "id": "1706.03762v7",
  "title": "Attention Is All You Need",
  "authors": ["Ashish Vaswani", "Noam Shazeer", "..."],
  "published": "2017-06-12T17:57:34Z",
  "abstract": "The dominant sequence transduction models are based on …",
  "pdf_url": "https://arxiv.org/pdf/1706.03762v7",
  "abs_url": "https://arxiv.org/abs/1706.03762v7"
}

pdf_url is reported so a caller can open it. This plugin never fetches it.

arxiv_search sends a plain phrase across all fields. A query that opens with one of arXiv's field prefixes (ti:, au:, abs:, cat:, all:, …) is passed through as written, so au:Hinton AND cat:cs.LG works. max_results is clamped into 1–25 rather than rejected — this is a lookup tool, not a harvester.

arxiv_get accepts 1706.03762, 1706.03762v7, arxiv:1706.03762, an /abs/ or /pdf/ URL, and the pre-2007 hep-th/9901001 form; all normalize to the bare identifier. A version suffix is kept, since dropping it would quietly answer about a different revision than the one asked for. arXiv answers an unknown id with HTTP 200 and an error entry, so arxiv_get checks and throws ARXIV_NOT_FOUND rather than reporting a silent nothing.

Talking to arXiv

One endpoint, over HTTPS, with no key: https://export.arxiv.org/api/query. Nothing scrapes an HTML page.

Every request is bounded twice and fails closed on either bound — an AbortSignal deadline (15s) and a response byte cap (2 MiB) enforced while the body streams, so an oversized response is abandoned rather than buffered. Both are configurable from the plugin's patch row:

- insert:
    - id: arxiv
      name: dsh-arxiv
      config:
        timeoutMs: 15000
        maxBytes: 2097152

Failures carry a stable code — ARXIV_TIMEOUT, ARXIV_HTTP_ERROR, ARXIV_RESPONSE_TOO_LARGE, ARXIV_NOT_FOUND, ARXIV_BAD_ID, ARXIV_BAD_QUERY, ARXIV_PARSE_ERROR, ARXIV_UNREACHABLE — so a caller can tell a timeout from a missing paper without matching on prose.

Requests identify themselves with a User-Agent naming the plugin and its repository, as arXiv's terms of use ask.

Headless use

The tool factories take the fetch to use, so you can drive either tool from a plain Node script without booting a profile:

// titles.mjs — node titles.mjs
import { createArxivSearchTool } from 'dsh-arxiv'

// Omit `fetch` to use the global one and hit the real API. Doing so sends live
// requests to export.arxiv.org: be polite, and read the terms linked below.
const search = createArxivSearchTool({ fetch: globalThis.fetch })

const exec = { signal: AbortSignal.timeout(20_000) }
const result = await search.execute({ query: 'au:Hinton AND cat:cs.LG', max_results: 5 }, exec)

console.log(`${result.returned} paper(s) for ${result.search_query}`)
for (const paper of result.papers) {
  console.log(`  ${paper.id}  ${paper.title}`)
}

Swap in a stub fetch and the same script runs entirely offline — this is exactly how the test suite drives it:

const canned = async () =>
  new Response(await readFile('feed.xml', 'utf8'), {
    status: 200,
    headers: { 'content-type': 'application/atom+xml' },
  })

const search = createArxivSearchTool({ fetch: canned })

execute validates its arguments before the body runs, so a bad call rejects with ToolArgsError and never reaches the network.

arXiv's terms, and whose text this is

This plugin is an API client. It is not affiliated with or endorsed by arXiv.

Use of the API is governed by the arXiv API Terms of Use. In short: identify your client, do not hammer the service, and respect the metadata's licensing.

Abstracts and metadata returned by these tools are arXiv's and their authors', not this plugin's. They are passed through unaltered except for collapsing the newlines arXiv wraps prose with. Attribute them to arXiv and to the paper's authors, and cite the paper — the abs_url on every result is the place to point. Thank you to arXiv for making the API and its data openly available.

Layout

package.json        manifest + `dsh.bundle.patch` — what makes this a bundle
cordis.patch.yml    the bundle's patch layer: one insert, one plugin row
src/index.js        the plugin: `name`, `inject`, `apply(ctx)`, both tools
src/arxiv.js        the HTTP client: endpoint, bounds, id and query handling
src/atom.js         a small dedicated parser for arXiv's Atom feed
src/errors.js       `ArxivError` and its codes
test/               offline tests, with checked-in feed fixtures

The Atom parser is hand-written against arXiv's one documented response shape rather than pulling in a general XML library, which is why this package has no runtime dependencies at all.

Tests

npm install
npm test

Offline by construction. Every test injects a fetch double answering from a checked-in fixture, and each test file replaces the global fetch with a guard that throws — so a code path that forgot its injected fetch fails as a test failure instead of a live request to export.arxiv.org. npm test opens no socket and reads no credential.

The suite covers registration, the Atom parser against captured real feeds, clamping, id normalization, both render projections, output-schema validation, loud failure on timeout, oversize, non-2xx, unknown id and bad arguments, and the manifest/patch wiring.

CI (.github/workflows/ci.yml) runs the same two commands on Node 22 and 24 with contents: read and no secrets.

License

MIT — see LICENSE. Covers this plugin's code only, not the arXiv content it retrieves.