Skip to content

ADR-0016: Universal runtime APIs in the core

ADR-0016: Universal runtime APIs in the core

Section titled “ADR-0016: Universal runtime APIs in the core”

Status: Accepted (amends ADR-0004) · Date: 2026-10-25 (released in v7.1.3)

ADR-0004 declared src/core/services/ free of runtime I/O and listed two “breaches”: OpenAiCompatibleStrategy and agent.service.ts calling the global fetch, and agent.service.ts reading process.env.DASHSCOPE_API_KEY as a documented fallback. Both are universal runtime APIs: fetch, URL and crypto exist in every supported runtime (Node, Bun, workers), and process.env is available in Node and Bun and read behind a typeof process !== "undefined" guard elsewhere. The toolkit ships an HTTP client, so fetch is domain logic here. The contributor rules (AGENTS.md, CONTRIBUTING.md) already permitted them, which left the ADR and the rule telling different stories.

Platform-specific APIs are a different matter: node:* modules, the filesystem, framework globals and provider SDKs do not exist in every runtime and must stay out of the core.

src/core/services/ may use the universal runtime APIs every supported runtime provides: fetch, URL, crypto, TextEncoder, plus guarded reads of process.env and browser globals. It must not statically import platform modules (node:*), the filesystem, frameworks or provider SDKs; a platform module may only enter through a lazy import() inside a method — the pattern generator.service.ts uses for node:crypto.

http.service.ts remains the HTTP facade (interceptors, Safe Results, the SSRF redirect policy). agent.service.ts and OpenAiCompatibleStrategy are reclassified as compliant under this rule; their behavior does not change. The two items stay recorded in ADR-0004 and are noted here so nobody “fixes” them into a behavior change by accident.

Better. The written rule matches the code and the enforced test (tests/architecture.test.ts still forbids core/ importing infrastructure/). A reviewer can classify a new API with one question: does it exist in every supported runtime?

Worse. The boundary is a convention, not a compiler check: a future contributor can still add a platform import that fails in one runtime only. The lazy-import exception is invisible to the architecture test.