@reinsjs/lowering-fetch

A zero-dependency lowering layer for reins: timeline events → provider wire protocol → event drafts, using nothing but fetch and a hand-written SSE parser. No provider SDK, no node:*, the same code on Node, Workers, Deno and Bun.

Three wire protocols: OpenAI Chat Completions (the front door of the OpenAI-compatible ecosystem: DeepSeek, Qwen, vLLM, gateways), Anthropic Messages (mid-conversation system placement, signed thinking replay, explicit cache breakpoints) and OpenAI Responses (stateless store: false, encrypted reasoning replay, developer messages anywhere).

pnpm add @reinsjs/lowering-fetch

import { anthropic, anthropicMessages, deepseek, openai, openaiChat, openaiResponses, chatCompletions } from "@reinsjs/lowering-fetch"
import { createAgent } from "@reinsjs/agent"

const opus = anthropic("claude-opus-5", { apiKey: process.env.ANTHROPIC_API_KEY! })
const ds = deepseek("deepseek-flash", { apiKey: process.env.DEEPSEEK_API_KEY! })
const gpt = openai("gpt-5-mini", { apiKey: process.env.OPENAI_API_KEY!, requestOptions: { reasoning: { effort: "low", summary: "auto" } } })
const mini = openaiChat("gpt-4o-mini", { apiKey: process.env.OPENAI_API_KEY! })
// any Anthropic-protocol endpoint (DeepSeek's compatible port, a gateway)
const dsClaude = anthropicMessages("deepseek-v4-flash", {
  provider: "deepseek",
  baseUrl: "https://api.deepseek.com/anthropic",
  apiKey: process.env.DEEPSEEK_API_KEY!,
  reasoning: true,
  midConversationSystem: true,
})
const qwen = chatCompletions("qwen-max", {
  provider: "qwen",
  baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
  apiKey: process.env.DASHSCOPE_API_KEY!,
  contextWindow: 128_000,
})

export const agent = createAgent({ model: ds, store, tools })

Each factory returns a BoundModel = { model, lowering }. apiKey is required and never read from the environment. For several models on one lowering instance, construct FetchLowering yourself and pass models.

Choosing between @reinsjs/lowering-fetch and @reinsjs/lowering-pi

Both implement the same Lowering interface from @reinsjs/core and both declare every landing in a LOSS_MATRIX; createAgent does not care which one you pass. They coexist on purpose — pick per host, not per project.

Start with lowering-fetch for a new host: it covers everything lowering-pi covers plus the OpenAI-compatible ecosystem, ships nothing but this package, and the request you debug is the request that was sent. Stay on lowering-pi when you already run on it (there is nothing to migrate for), or when you want the provider table and new wire-protocol features to arrive through pi-ai rather than through this package. Events written by one layer replay through the other: replay.thinkingSignature uses the same shape on both, so switching does not invalidate a stored timeline.

Runtime

No node:*, no process, no Buffer — the same dist/index.js runs on Node ≥ 22 and on Cloudflare Workers with a 2023 compatibility_date and no compatibility flags (spikes/edge-runtime-check, tier "最严档": module load, a byte-sliced SSE stream against a local fake endpoint, and one live request per protocol). Bun 1.4, Deno 2.9 (only --allow-net needed — the layer reads no system information) and Vercel's edge-runtime (bare vm, no process, no eval) pass the same probes, all three protocols against live providers (spikes/runtime-matrix).

Options

How events land on Chat Completions

Every landing is declared in LOSS_MATRIX["openai-chat"] and asserted by tests — nothing is dropped silently.

• system_note → a mid-conversation system message (exact; verified on OpenAI and DeepSeek). Set midConversationSystem: false for an upstream that rejects it and the note goes out as a framed user message (lossy). A note marked directive: true (an instruction the model must act on, such as compact's request) always goes out as the framed user message, on all three protocols.
• A user message or note that arrives while tool results are still pending is moved after them on the wire (tool messages must directly follow the assistant that called them); the user message is recorded lossy(user), the log order is untouched.
• Thinking: Chat Completions has no replay slot (no signature, no encrypted item). On the official API thinking events are dropped. With chat.reasoningContent (DeepSeek) they are replayed as reasoning_content — and DeepSeek requires the field on every historical assistant message once tools is present (400 otherwise), so the layer always sends it, empty when there is nothing to replay.
• One turn with several text blocks is merged into one content string (lossy(merged-text)); tool messages carry text only: when the model takes images, each image leaves a pointer ([image n attached in the next user message]) and the images go into one user message right after the whole batch of tool messages — before any user message that was moved after the batch — with a line per result naming the tool, the call id and the image count and saying it is tool output, not the user; untrusted results keep their <untrusted> marking (lossy(tool+lifted-images); verified on DeepSeek's official API — check other OpenAI-compatible upstreams before relying on it, and turn it off with chat.liftToolImages: false if they reject the shape). Without image support, or with chat.liftToolImages: false, images become a placeholder (lossy(tool-text-only)); isError has no flag on this protocol and is expressed as a [tool error] prefix (lossy).
• No explicit cache breakpoints exist on this protocol; provider-side automatic prefix caching applies and cached_tokens is reported as cacheRead.
• Usage follows core semantics: input is the uncached prompt count. costUsd uses the built-in price table (DeepSeek: peak rates, an upper bound).

How events land on Anthropic Messages

Declared in LOSS_MATRIX["anthropic-messages"], cell for cell comparable with @reinsjs/lowering-pi.

• system_note → a mid-conversation { role: "system" } message on model families that accept it (Fable 5.x / Mythos 5.x / Opus 5 / Opus 4.8, or midConversationSystem: true). The provider requires such a message to follow a user turn and be followed by an assistant turn or end the request, so notes are held and emitted right before the next assistant turn (or at the end); when that slot follows an assistant turn — or the note would be the first message — the note goes out as a framed user text (lossy(user-role)). Other models always get the framed text.

• Tool results and anything moved after them (a user message that arrived while results were pending) share one user message, so tool_result blocks directly follow the tool_use turn. is_error is carried natively.

• Thinking is replayed only when the event carries a signature from the same provider, API and model (thinking / redacted_thinking blocks); unsigned thinking (an interrupted stream), thinking from another provider, or thinking from another model of the same provider is dropped and declared — it is not turned into visible text (a signature is only valid for the model that produced it: replaying one across models is a 400). Empty-text thinking blocks with a signature (display: "omitted") are kept and replayed.

• Cache breakpoints: one on the last system block, one on the last tool, one on the last block of the last user message. When a note is the last message, the conversation breakpoint becomes a top-level cache_control (measured on par with no injection). Never more than four in total.

• Usage: input_tokens is already the uncached count; cache_read_input_tokens / cache_creation_input_tokens map to cacheRead / cacheWrite. stop_reason: "refusal" becomes a non-retryable error carrying stop_details.

• Deferred tools (ToolSpec.deferLoading, set by lazyTools() when capabilities.deferredTools is true): defer_loading: true on the tool, the cache breakpoint moves to the last non-deferred tool (a deferred tool cannot carry cache_control), and if every tool would be deferred none is (the API rejects that). A tool_result whose content is only tool_reference parts, comes from a system-trusted result, and names tools present in this request's tools is sent as tool_reference blocks the API expands in place — the tool list never changes, so the cache prefix survives (exact / tool-reference); text parts in the same result are moved after the batch of tool_result blocks (lossy / tool-reference, they cannot be mixed). References to tools not in this request, or inside untrusted results, are rendered as text instead — the API validates every reference in the whole history and answers 400 for an unknown name.

How events land on OpenAI Responses

Declared in LOSS_MATRIX["openai-responses"], cell for cell comparable with @reinsjs/lowering-pi.

• Stateless by construction. Every request carries the whole history in input; store: false is forced and a previous_response_id in requestOptions is dropped — the timeline is the only source of truth, OpenAI's server-side conversation state is never relied on.
• The system prompt and system_note are developer messages (reasoning models) or system messages (others) at any position in input — no placement rules, always exact. compaction is a framed user text (lossy).
• Reasoning: reasoning models always request include: ["reasoning.encrypted_content"]; each reasoning item is stored whole in the event's replay.thinkingSignature and replayed verbatim (the provider verifies the encrypted payload — a forged one is a 400). Items without encrypted_content (an interrupted stream, include refused), from another provider, or from another model are dropped and declared, never turned into text. Reasoning items with an encrypted payload but no summary are kept as empty-text thinking events so the next turn can replay them.
• Assistant text becomes a type: "message" item per text block, replaying the provider's msg_ id (replay.textSignature, lowering-pi's JSON form is accepted too) or a generated one. Tool calls are function_call items: call_id is the event's toolCallId, the fc_ item id lives in replay.itemId and is replayed only for the same model (OpenAI validates the pairing of fc_ and rs_ items); arguments is a JSON string, so non-object arguments need no wrapping. Tools are sent with strict: false.
• Tool results are function_call_output items matched by call_id: a string when text-only, an array of input_text / input_image blocks when the result has images and the model accepts them; isError has no flag on this protocol and is expressed as a [tool error] prefix (lossy).
• Usage: input_tokens includes cached and cache-write tokens, so input is input_tokens − cached_tokens − cache_write_tokens, with the two mapped to cacheRead / cacheWrite. status: "incomplete" with max_output_tokens is length; with content_filter a non-retryable error; response.failed and error frames are errors carrying the provider's code and message. Automatic prefix caching is best-effort on OpenAI's side; pass prompt_cache_key in requestOptions to improve hit rates.
• Built-in table: the gpt-5 family (5.5 / 5.4 / 5.4-mini / 5.2 / 5.1 / 5 / 5-mini / 5-nano), o3 / o4-mini and gpt-4.1 / 4.1-mini / 4o-mini on Responses; the same OpenAI ids also exist as Chat Completions entries, which openaiChat() picks by protocol. A bare { provider: "openai", id } on a FetchLowering you construct yourself resolves to Responses.

Errors and retries

Non-2xx responses throw HttpError with status, headers and the raw body ("<status> <body>", the same shape the official SDKs use), so runLoop's transient-failure rule applies unchanged: 408 / 409 / 429 / 5xx retry, everything else does not. Network failures propagate from fetch untouched.

Documentation

docs/archive/implementation-plans/2026-09-08-技术方案v1.0.md §11, docs/系统全景图_模块盘点/lowering-fetch.md, spikes/f1-chat-live/, spikes/f2-anthropic-live/, spikes/f3-responses-live/ (live verification against DeepSeek and, through the Cloudflare AI Gateway, OpenAI and Anthropic) and spikes/edge-runtime-check/ (Cloudflare workerd) — in Chinese, at the repository root.

MIT © 2026 NewRate Limited.