@qilin-agent/llm-retry 0.0.0-stage → 3.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,70 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/llm/llm-retry/README.md
+/:
+  en: 48b7b8ee60e92601
+  zh: 28dfac5ed11f58ce
+/qilin-agent-llm-retry:
+  en: ad59c00359289bbf
+  zh: bad791a25b1b5c2e
+/qilin-agent-llm-retry/summary:
+  en: 8c6cf17ad639bcf9
+  zh: ca586c275d3f64db
+/qilin-agent-llm-retry/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-agent-llm-retry/use-this-package:
+  en: ecee4f255eaa53bd
+  zh: 2e7983fd7668fa00
+/qilin-agent-llm-retry/use-this-package/when-to-choose-it:
+  en: 7d3a9e96a556e1ff
+  zh: 7c9cce7e36ebc980
+/qilin-agent-llm-retry/use-this-package/minimal-configuration:
+  en: 95b1cf09ee2c77a9
+  zh: 4d45e437db4988c7
+/qilin-agent-llm-retry/use-this-package/what-you-can-observe:
+  en: 21267b22ad48e012
+  zh: 521bfad2c2d8e418
+/qilin-agent-llm-retry/use-this-package/failures-and-recovery:
+  en: 730567739a21a4d2
+  zh: 3ea222c68d960948
+/qilin-agent-llm-retry/understand-the-implementation:
+  en: cef3289094f94c25
+  zh: c7f40ff6e4e56de6
+/qilin-agent-llm-retry/understand-the-implementation/design-philosophy:
+  en: fc4f15a14435698c
+  zh: 3c6d83f5ba04ec0e
+/qilin-agent-llm-retry/understand-the-implementation/source-map:
+  en: f34b551859b68c88
+  zh: 813ffa32497b1d9a
+/qilin-agent-llm-retry/understand-the-implementation/recovery-flow:
+  en: 85bace285b029101
+  zh: 6e0237450ca6ccc0
+/qilin-agent-llm-retry/understand-the-implementation/waterfall-composition:
+  en: 388e8db333e03cb1
+  zh: 54b6446ac3584724
+/qilin-agent-llm-retry/further-exploration:
+  en: 1ff198a0626eba5b
+  zh: 089b833f44f42c2f
+/qilin-agent-llm-retry/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/qilin-agent-llm-retry/model-experience/model-request-recovery:
+  en: 8496b7aefbe6fa20
+  zh: ed7b60ef09380ec4
+/qilin-agent-llm-retry/model-experience/model-request-recovery/what-the-model-sees:
+  en: 9772b77e48e70dba
+  zh: df3d4105f7b8c256
+/qilin-agent-llm-retry/model-experience/model-request-recovery/token-effect:
+  en: f86254d7c2ed2444
+  zh: 7e0f7b9e026e0bf2
+/qilin-agent-llm-retry/model-experience/model-request-recovery/kv-cache-effect:
+  en: 82d6bdfc0ec747ea
+  zh: 14269c9dcd086611
+/qilin-agent-llm-retry/known-limitations-and-deferred-work:
+  en: bef1baa545592b9c
+  zh: 61984a1e10de8294
+/qilin-agent-llm-retry/known-limitations-and-deferred-work/dev-note:
+  en: add61ee91e4ae8e4
+  zh: 3877c147b541b2c9

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+---
+description: "The retry executor for users and maintainers configuring provider-routed model-request recovery at durable agent-step boundaries."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/llm-retry
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Mount `@qilin-agent/llm-retry` to retry failed model requests at durable agent-step boundaries. Provider `retryPolicy` settings choose bounded normal-mode retries or unlimited always-mode retries; scheduled attempts reach the session log before backoff, and cancellation leaves consistent history. Retries re-run the failed step in the same open turn, while direct `ctx.llm.stream()` calls remain single-attempt. Each retry is another billed provider request, and always mode continues until success, cancellation, or disposal.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount this plugin when agent runs should recover from transient model-request failures — rate limits, server errors, timeouts, transport errors — instead of ending the turn. It is the executor: the retry policy itself lives on each provider adapter's configuration, and this package has no configuration of its own.
+
+### When to choose it
+
+Choose it when a composition runs the agent loop and wants durable request recovery. The plugin is a function plugin with no config; provider adapters such as `qilin-llm-deepseek` and `qilin-llm-pi-ai` own the `retryPolicy` for their routes, and multi-provider adapters place it inside each provider profile. Skip it when calls go through `ctx.llm.stream()` directly without the agent loop: those consumers remain single-attempt because a raw stream cannot separate already-emitted chunks durably.
+
+### Minimal configuration
+
+```yaml
+- name: '@qilin-agent/llm-deepseek-api-key'
+  config:
+    apiKeyEnv: DEEPSEEK_API_KEY
+    retryPolicy:
+      mode: always
+      backoff:
+        initialDelayMs: 1000
+        maxDelayMs: 30000
+        jitterRatio: 0.2
+
+- name: '@qilin-agent/llm-retry'
+```
+
+Omission of `retryPolicy` uses normal mode: five retries for `EMPTY_RESPONSE`, `RATE_LIMIT`, `SERVER`, `TIMEOUT`, and `TRANSPORT`, with bounded exponential backoff from 500 ms to 10 seconds and 10 percent jitter. Normal mode can change its finite budget, eligible codes, and backoff; always mode asks downstream recovery first, then retries every model-request failure without an attempt limit, stopping only on success, cancellation, or plugin disposal.
+
+### What you can observe
+
+Each scheduled retry is durable before its wait: the plugin appends a non-surface `llm/retry` event carrying the retry id, provider, mode, policy key, failure, and scheduled delay, then a `llm/retry-started` event immediately before the retry begins. A valid `Retry-After` from the provider replaces local backoff when it fits the policy bounds. When the wait completes, the loop re-runs the failed step inside the same open turn over the same durable history, so the retried request is reconstructable from the session log exactly like the original. Cancellation or plugin disposal aborts active backoff, drains active delegated recovery, and makes a callback captured before disposal fail closed.
+
+### Failures and recovery
+
+A failure before any final adapter is selected has no provider policy and delegates downstream unchanged. In normal mode, a failure code outside the eligible set, or an exhausted budget, delegates; in always mode, an over-cap provider delay uses the configured local backoff so the policy cannot terminate on that instruction. Nothing here is model-visible: no retry event, delay, provider error, or failed partial output reaches the model or derived messages.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design behind the executor; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design philosophy
+
+The executor is built on one rule: **durable before wait, open-step boundaries.** A retry is scheduled through the session log before any timer starts, so a crash or cancellation never leaves an invisible pending retry. Recovery runs on the agent loop's `agent/request-error` waterfall, the open-step extension point, rather than wrapping `ctx.llm.stream()` — a raw stream cannot separate already-emitted chunks durably, while the loop can re-run the failed step inside the same open turn.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | The function plugin: waterfall listener, policy lookup, backoff, durable event appends |
+| [`src/history.ts`](src/history.ts) | Durable retry-history lookup from the session log |
+| [`src/types.ts`](src/types.ts) | Browser-safe `llm/retry` and `llm/retry-started` event payload types |
+| [`src/brand.ts`](src/brand.ts) | The `RetryId` brand shared by the event payloads |
+
+### Recovery flow
+
+A failed step arrives on the waterfall with its provider and resolved policy. Always mode settles downstream recovery first and honors a downstream `retry` decision; normal mode first checks that the failure code is eligible and the budget is not exhausted. The plugin computes the delay — provider `Retry-After` when valid and within bounds, otherwise local bounded exponential backoff with symmetric jitter — appends the `llm/retry` event, waits on a cancellable timer, appends `llm/retry-started`, and returns `{ kind: 'retry' }`. The loop then re-runs the failed step inside the same open turn over the same durable history.
+
+### Waterfall composition
+
+The plugin is one listener in the `agent/request-error` waterfall. Always mode's "downstream first" posture means a later policy that ignores cancellation and never settles also prevents fallback, turn quiescence, and plugin disposal from completing; success, cancellation, or disposal stops always mode after active delegated recovery reaches quiescence.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the service contract to the adapters that own retry policies.
+
+- [qilin-llm service](../llm/README.md) — the provider-neutral service whose adapters own `retryPolicy`.
+- [llm-deepseek adapter](../llm-deepseek/README.md) — a provider adapter with a route-level `retryPolicy`.
+- [llm-pi-ai adapter](../llm-pi-ai/README.md) — a multi-provider adapter with per-profile `retryPolicy`.
+- [Terminal LLM stream failures](../../../.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md) — how failures reach the service boundary as terminal chunks.
+- [LLM streaming subsystem](../../../docs/subsystems/llm-streaming.md) — the `StreamChunk` protocol and adapter contract.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Model-request recovery
+
+#### What the model sees
+
+No retry event, delay, provider error, or failed partial output is model-visible. The retried step reconstructs the same explicit provider/model request from durable surface history unless a downstream recovery policy deliberately changes that surface; failed chunks never enter derived messages.
+
+#### Token effect
+
+Each retry is a new provider request and may repeat input-token billing. Normal mode has a finite budget; always mode can consume unbounded requests until success or cancellation. `llm/retry` itself contributes no tokens.
+
+#### KV Cache effect
+
+The reconstructed request preserves the prior prefix and is eligible for provider cache reuse under that provider's rules. The non-surface retry event does not change cache identity.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define where the executor stops and future work begins. They are current package constraints, not a general retry comparison or a task backlog.
+
+- **Agent turns are the only retry boundary** — direct `ctx.llm.stream()` consumers remain single-attempt because a raw stream cannot separate already-emitted chunks durably.
+- **Always mode retries permanent failures** — authentication, quota, invalid-request, protocol, and unrecoverable context errors continue until success, cancellation, or disposal; deployments own provider-specific cost and latency controls.
+- **Finite plugin budgets add** — normal mode counts only its configured codes and exact provider policy, while context-overflow compaction owns a separate budget. Any overlapping policy must define registration-order behavior.
+- **Recovery policies compose by waterfall order** — always mode accepts a downstream retry before applying its fallback. A later policy that ignores cancellation and never settles also prevents fallback, turn quiescence, and plugin disposal from completing.
+- **`llm/retry` records scheduling, not completion** — later step and turn events establish success, exhaustion, or cancellation.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+This Dev Note is non-authoritative working context: notes for maintainers and open questions. Shipped behavior and accepted rationale live in the sections above, the package code, and the linked Agent Notes.
+
+- Retry numbers continue only across events with the same provider and complete policy key, so a route replacement with different limits, code membership, or backoff starts its own history; the key includes every behavior-affecting field and sorts normal-mode codes because eligibility uses set membership.
+
+</details>

package/README.zh.md

@@ -0,0 +1,148 @@
+---
+description: "面向用户与维护者的重试执行器说明：在持久 agent（智能体）步骤边界上配置按提供方路由的模型请求恢复。"
+kind: "package-reference"
+---
+
+# @qilin-agent/llm-retry
+
+[English](README.md) | 中文
+
+## 概述
+
+挂载 `@qilin-agent/llm-retry`，可在持久 agent 步骤边界重试失败的模型请求。提供方的 `retryPolicy` 设置可选择有界的 normal mode 重试或无上限的 always mode 重试；计划的尝试会在退避前写入会话日志，取消后历史仍保持一致。重试会在同一个打开的轮次内重跑失败步骤，而直接 `ctx.llm.stream()` 调用仍只尝试一次。每次重试都会产生另一次提供方请求计费，always mode 会持续到成功、取消或释放。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+当 agent 运行应从暂时性模型请求失败——速率限制、服务端错误、超时、传输错误——中恢复而不是结束轮次时，挂载本插件。它是执行器：重试策略本身位于各提供方适配器的配置上，本包没有任何自己的配置。
+
+### 何时选择
+
+当组合运行 agent loop（智能体循环）并需要持久请求恢复时选择它。本插件是无配置的函数插件；`qilin-llm-deepseek` 与 `qilin-llm-pi-ai` 等提供方适配器拥有各自路由的 `retryPolicy`，多提供方适配器把它放进每个 provider profile。当调用不经 agent loop、直接走 `ctx.llm.stream()` 时跳过它：这些消费方仍是单次尝试，因为原始流无法持久地区分已发出的分片。
+
+### 最小配置
+
+```yaml
+- name: '@qilin-agent/llm-deepseek-api-key'
+  config:
+    apiKeyEnv: DEEPSEEK_API_KEY
+    retryPolicy:
+      mode: always
+      backoff:
+        initialDelayMs: 1000
+        maxDelayMs: 30000
+        jitterRatio: 0.2
+
+- name: '@qilin-agent/llm-retry'
+```
+
+省略 `retryPolicy` 时使用 normal mode：对 `EMPTY_RESPONSE`、`RATE_LIMIT`、`SERVER`、`TIMEOUT` 与 `TRANSPORT` 最多重试五次，退避从 500 毫秒到 10 秒、带 10% 抖动。normal mode 可以更改其有界预算、合格 code 与退避；always mode 先询问下游恢复，然后无尝试上限地重试每个模型请求失败，只在成功、取消或插件释放时停止。
+
+### 你可以观察到什么
+
+每次计划的重试在等待前就是持久的：插件会先追加携带重试 id、提供方、模式、策略键、失败与计划延迟的非表层 `llm/retry` 事件，然后在重试开始前立即追加 `llm/retry-started` 事件。提供方给出且符合策略边界的有效 `Retry-After` 会替换本地退避。等待完成后，loop 会在同一个打开的轮次内重跑失败步骤，仍基于同一份持久历史，因此重试请求与原始请求一样可以从会话日志重建。取消或插件释放会中止进行中的退避、等待活跃的委派恢复结算，并使释放前捕获的回调只能以失败结束。
+
+### 失败与恢复
+
+在任何最终适配器被选中之前发生的失败没有提供方策略，原样委派下游。normal mode 中，不在合格集合内的失败 code 或已耗尽的预算会委派；always mode 中，超上限的提供方延迟使用配置的本地退避，因此策略不会因该指令终止。这里没有任何模型可见内容：重试事件、延迟、提供方错误或失败的部分输出都不会到达模型或派生消息。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释执行器背后的设计；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+执行器建立在一条规定之上：**先持久、后等待，打开步骤边界。** 任何定时器启动之前，重试就已通过会话日志计划，因此崩溃或取消永远不会留下不可见的待处理重试。恢复运行在 agent loop 的 `agent/request-error` waterfall（瀑布式事件），即打开步骤扩展点上，而不是包装 `ctx.llm.stream()`——原始流无法持久地区分已发出的分片，而 loop 可以在同一个打开的轮次内重跑失败步骤。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 函数插件：waterfall 监听器、策略查找、退避、持久事件追加 |
+| [`src/history.ts`](src/history.ts) | 从会话日志查找持久重试历史 |
+| [`src/types.ts`](src/types.ts) | 浏览器安全的 `llm/retry` 与 `llm/retry-started` 事件载荷类型 |
+| [`src/brand.ts`](src/brand.ts) | 事件载荷共享的 `RetryId` 品牌 |
+
+### 恢复流程
+
+失败步骤连同其提供方与解析后的策略一起到达 waterfall。always mode 先结算下游恢复，并遵循下游的 `retry` 决定；normal mode 先检查失败 code 是否合格、预算是否未耗尽。插件计算延迟——有效且在边界内的提供方 `Retry-After`，否则带对称抖动的本地有界指数退避——追加 `llm/retry` 事件，在可取消定时器上等待，追加 `llm/retry-started`，然后返回 `{ kind: 'retry' }`。loop 随后在同一个打开的轮次内重跑失败步骤（仍基于同一份持久历史）。
+
+### Waterfall 组合
+
+本插件是 `agent/request-error` waterfall 中的一个监听器。always mode 的"下游优先"姿态意味着，之后忽略取消且永不结算的策略也会阻止回退、轮次完全停稳与插件释放完成；成功、取消或释放会在活动委派恢复达到完全停稳后停止 always mode。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从服务约定逐步进入拥有重试策略的适配器。
+
+- [qilin-llm 服务](../llm/README.zh.md)——其适配器拥有 `retryPolicy` 的提供方无关服务。
+- [llm-deepseek 适配器](../llm-deepseek/README.zh.md)——带路由级 `retryPolicy` 的提供方适配器。
+- [llm-pi-ai 适配器](../llm-pi-ai/README.zh.md)——带逐 profile `retryPolicy` 的多提供方适配器。
+- [LLM 流终止失败](../../../.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md)——失败如何以终止分片到达服务边界。
+- [LLM 流式子系统](../../../docs/subsystems/llm-streaming.zh.md)——`StreamChunk` 协议与适配器约定（adapter contract）。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 模型请求恢复
+
+#### 模型看到什么
+
+重试事件、延迟、提供方错误或失败的部分输出都不会对模型可见。除非下游恢复策略刻意改变该表层，重试步骤会从持久表层历史中重建相同的显式提供方／模型请求；失败分片绝不进入派生消息。
+
+#### Token 影响
+
+每次重试都是一次新的提供方请求，可能重复输入 token 计费。normal mode 有有界预算；always mode 在成功或取消前可能消耗无上限请求。`llm/retry` 本身不贡献任何 token。
+
+#### KV Cache 影响
+
+重建的请求保留此前前缀，有资格按该提供方规则复用提供方缓存。非表层重试事件不改变缓存标识。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明执行器在哪里停止、由未来工作接续。它们是当前包约束，不是通用重试对比或任务积压。
+
+- **agent 轮次是唯一重试边界**——直接 `ctx.llm.stream()` 消费方仍是单次尝试，因为原始流无法持久地区分已发出的分片。
+- **always mode 会重试永久性失败**——认证、配额、无效请求、协议与不可恢复的上下文错误会持续到成功、取消或释放；部署方负责提供方专属的成本与延迟控制。
+- **有界插件预算相加**——normal mode 只统计其配置的 code 与精确提供方策略，而上下文溢出压缩（compaction）拥有独立预算。任何重叠策略都必须定义注册顺序行为。
+- **恢复策略按 waterfall 顺序组合**——always mode 先接受下游重试，再应用其回退。之后忽略取消且永不结算的策略也会阻止回退、轮次完全停稳与插件释放完成。
+- **`llm/retry` 记录调度，而非完成**——后续步骤与轮次事件才确立成功、耗尽或取消。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+本开发备注是不具权威性的工作上下文：维护者备注与开放问题。已交付的行为与既定理由以上文、包代码和相关 Agent Note 为准。
+
+- 重试编号只在同一提供方与完整策略键的事件间延续，因此限额、code 成员或退避不同的路由替换会开启自己的历史；该键包含每个影响行为的字段，并因资格判断使用集合成员而对 normal mode code 排序。
+
+</details>

package/lib/index.js

@@ -0,0 +1,186 @@
+import { randomUUID } from "node:crypto";
+import z from "@qilin-agent/schemastery";
+import { z as z$1 } from "zod";
+//#region lib/types/brand.js
+/**
+* Brand an implementation-minted retry-chain identity.
+* @param id - opaque retry identity.
+* @returns the same string, branded; no validation is performed.
+*/
+function RetryId(id) {
+	return id;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Provider-routed model-request retry policy on the agent loop's request
+* recovery extension point. Each scheduled retry is durable before its cancellable wait.
+*
+* @module @qilin-agent/llm-retry
+*/
+const name = "llm-retry";
+const inject = ["agents", "sessionProjections"];
+/** Runtime schema for {@link Config}. */
+const Config = z.object({});
+function validateConfig(config) {
+	const [key] = Object.keys(config);
+	if (key === void 0) return;
+	if (key === "retryPolicy") throw new Error("llm-retry: retryPolicy belongs under each provider configuration");
+	throw new Error(`llm-retry: unknown key "${key}"`);
+}
+async function settleDownstream(next) {
+	try {
+		return {
+			type: "decision",
+			decision: await next()
+		};
+	} catch (error) {
+		return {
+			type: "error",
+			error
+		};
+	}
+}
+function localDelay(config, retry, random) {
+	const exponent = Math.min(retry - 1, 1024);
+	const exponential = Math.min(config.initialDelayMs * 2 ** exponent, config.maxDelayMs);
+	const jitter = 1 - config.jitterRatio + 2 * config.jitterRatio * random();
+	return Math.min(exponential * jitter, config.maxDelayMs);
+}
+function retryPolicyKey(policy) {
+	return policy.mode === "always" ? JSON.stringify([
+		policy.mode,
+		policy.initialDelayMs,
+		policy.maxDelayMs,
+		policy.jitterRatio
+	]) : JSON.stringify([
+		policy.mode,
+		policy.maxRetries,
+		[...policy.retryableCodes].sort(),
+		policy.initialDelayMs,
+		policy.maxDelayMs,
+		policy.jitterRatio
+	]);
+}
+function retryStateKey(provider, policyKey) {
+	return JSON.stringify([provider, policyKey]);
+}
+function cancellableDelay(delayMs, signal) {
+	if (signal.aborted) return Promise.resolve(false);
+	return new Promise((resolve) => {
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(true);
+		}, delayMs);
+		function onAbort() {
+			clearTimeout(timer);
+			resolve(false);
+		}
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+const llmRetryStateSchema = z$1.record(z$1.string(), z$1.object({
+	retry: z$1.number().int().nonnegative(),
+	retryId: z$1.string()
+}));
+function apply(ctx, config = {}, internals = {}) {
+	validateConfig(config);
+	ctx.sessionProjections.register({
+		key: "llmRetry",
+		stateVersion: 1,
+		stateSchema: llmRetryStateSchema,
+		init: () => ({}),
+		apply: (state, event) => {
+			if (event.type === "step/start" || event.type === "turn/end") return {};
+			if (event.type !== "llm/retry") return state;
+			const key = retryStateKey(event.data.provider, event.data.policyKey);
+			const entry = state[key];
+			if (entry?.retry === event.data.retry && entry.retryId === event.data.retryId) return state;
+			return {
+				...state,
+				[key]: {
+					retry: event.data.retry,
+					retryId: event.data.retryId
+				}
+			};
+		}
+	});
+	const random = internals.random ?? Math.random;
+	const lifetime = new AbortController();
+	const active = /* @__PURE__ */ new Set();
+	function track(operation) {
+		const tracked = operation.finally(() => active.delete(tracked));
+		active.add(tracked);
+		return tracked;
+	}
+	async function backoff(agent, turn, step, failure, provider, policy, policyKey, retry, retryId, delayMs, signal) {
+		const fusedSignal = AbortSignal.any([signal, lifetime.signal]);
+		if (fusedSignal.aborted) return;
+		const eventData = policy.mode === "normal" ? {
+			retryId,
+			turn,
+			step,
+			provider,
+			mode: policy.mode,
+			policyKey,
+			retry,
+			maxRetries: policy.maxRetries,
+			delayMs,
+			failure
+		} : {
+			retryId,
+			turn,
+			step,
+			provider,
+			mode: policy.mode,
+			policyKey,
+			retry,
+			delayMs,
+			failure
+		};
+		agent.session.append("llm/retry", eventData);
+		if (!await cancellableDelay(delayMs, fusedSignal)) return;
+		agent.session.append("llm/retry-started", {
+			retryId,
+			turn,
+			step,
+			retry
+		});
+		return { kind: "retry" };
+	}
+	async function recover({ agent, turn, step, provider, failure, retryPolicy: policy, signal }, next) {
+		if (policy === void 0) return next();
+		if (policy.mode === "always") {
+			if (signal.aborted || lifetime.signal.aborted) return;
+			const fusedSignal = AbortSignal.any([signal, lifetime.signal]);
+			const downstream = await settleDownstream(next);
+			if (fusedSignal.aborted) return;
+			if (downstream.type === "error") ctx.logger.warn(`llm-retry: provider "${provider}" always policy ignored a downstream recovery failure: %o`, downstream.error);
+			if (downstream.type === "decision" && downstream.decision?.kind === "retry") return downstream.decision;
+		} else if (!policy.retryableCodes.includes(failure.code)) return next();
+		const policyKey = retryPolicyKey(policy);
+		const previous = ctx.sessionProjections.stateOf(agent.session, "llmRetry")[retryStateKey(provider, policyKey)];
+		const previousRetry = previous?.retry ?? 0;
+		if (policy.mode === "normal" && previousRetry >= policy.maxRetries) return next();
+		const retry = previousRetry + 1;
+		const retryId = previous?.retryId ?? RetryId(randomUUID());
+		let delayMs;
+		if (failure.providerRetryAfterMs !== void 0 && Number.isFinite(failure.providerRetryAfterMs) && failure.providerRetryAfterMs > 0) if (failure.providerRetryAfterMs > policy.maxDelayMs) {
+			if (policy.mode === "normal") return next();
+			delayMs = localDelay(policy, retry, random);
+		} else delayMs = failure.providerRetryAfterMs;
+		else delayMs = localDelay(policy, retry, random);
+		return backoff(agent, turn, step, failure, provider, policy, policyKey, retry, retryId, delayMs, signal);
+	}
+	const disposeListener = ctx.on("agent/request-error", (payload, next) => {
+		if (lifetime.signal.aborted) return Promise.resolve(void 0);
+		return track(recover(payload, next));
+	});
+	ctx.effect(() => async () => {
+		disposeListener();
+		lifetime.abort(/* @__PURE__ */ new Error("llm-retry plugin disposed"));
+		await Promise.allSettled([...active]);
+	}, "llm-retry: abort and drain active recovery");
+}
+//#endregion
+export { Config, RetryId, apply, inject, name };

package/lib/types/brand.d.ts

@@ -0,0 +1,10 @@
+import type { Branded } from '@qilin-agent/brand';
+/** Stable identity shared by every attempt in one request-step retry chain. */
+export type RetryId = Branded<'RetryId'>;
+/**
+ * Brand an implementation-minted retry-chain identity.
+ * @param id - opaque retry identity.
+ * @returns the same string, branded; no validation is performed.
+ */
+export declare function RetryId(id: string): RetryId;
+//# sourceMappingURL=brand.d.ts.map

package/lib/types/brand.js

@@ -0,0 +1,9 @@
+/**
+ * Brand an implementation-minted retry-chain identity.
+ * @param id - opaque retry identity.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function RetryId(id) {
+    return id;
+}
+//# sourceMappingURL=brand.js.map

package/lib/types/history.d.ts

@@ -0,0 +1,13 @@
+/** Durable request-route lookup for one open model step. @module @qilin-agent/llm-retry/history */
+import type { SessionEvent } from '@qilin-agent/session';
+/**
+ * Find the provider in force for one currently open step.
+ * Request headers remain effective across turn boundaries until a newer full
+ * snapshot changes them; every provider change requires a newer full snapshot.
+ * @param events - session events ending inside the open step.
+ * @param turn - turn that owns the failed step.
+ * @param step - failed step whose provider is required.
+ * @returns the provider from the request header in force for the step.
+ */
+export declare function providerForOpenStep(events: readonly SessionEvent[], turn: number, step: number): string | undefined;
+//# sourceMappingURL=history.d.ts.map

package/lib/types/history.js

@@ -0,0 +1,26 @@
+/** Durable request-route lookup for one open model step. @module @qilin-agent/llm-retry/history */
+/**
+ * Find the provider in force for one currently open step.
+ * Request headers remain effective across turn boundaries until a newer full
+ * snapshot changes them; every provider change requires a newer full snapshot.
+ * @param events - session events ending inside the open step.
+ * @param turn - turn that owns the failed step.
+ * @param step - failed step whose provider is required.
+ * @returns the provider from the request header in force for the step.
+ */
+export function providerForOpenStep(events, turn, step) {
+    const stepStartIndex = events.findLastIndex(event => event.type === 'step/start'
+        && event.data.turn === turn
+        && event.data.step === step);
+    if (stepStartIndex < 0 || events.slice(stepStartIndex + 1).some(event => event.type === 'step/end' || event.type === 'turn/end'))
+        return undefined;
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        // The loop bounds prove this indexed read exists.
+        // oxlint-disable-next-line typescript/no-non-null-assertion
+        const event = events[index];
+        if (event.type === 'request/header')
+            return event.data.header.config.provider;
+    }
+    return undefined;
+}
+//# sourceMappingURL=history.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Provider-routed model-request retry policy on the agent loop's request
+ * recovery extension point. Each scheduled retry is durable before its cancellable wait.
+ *
+ * @module @qilin-agent/llm-retry
+ */
+import type { Context } from '@qilin-agent/kylin';
+import z from '@qilin-agent/schemastery';
+import { RetryId } from './brand.ts';
+export type { LlmRetryEventData, LlmRetryStartedEventData } from './types.ts';
+export { RetryId } from './brand.ts';
+export declare const name = "llm-retry";
+export declare const inject: string[];
+/** This policy executor has no config; providers own `retryPolicy`. */
+export type Config = Readonly<Record<string, never>>;
+/** Runtime schema for {@link Config}. */
+export declare const Config: z<Config>;
+/** Non-serializable hooks used to make timing policy deterministic in tests. */
+export interface RetryInternals {
+    /** Random sample in the inclusive zero-to-one range used for jitter. */
+    random?: () => number;
+}
+/**
+ * Install provider-routed normal or unbounded request recovery.
+ * @param ctx - plugin context that owns the listener and active waits.
+ * @param config - empty executor config; provider registrations own policy.
+ * @param internals - non-serializable deterministic hooks for tests.
+ */
+interface RetryStateEntry {
+    retry: number;
+    retryId: RetryId;
+}
+type LlmRetryState = Record<string, RetryStateEntry>;
+declare module '@qilin-agent/session-projection/types' {
+    interface SessionProjectionStateMap {
+        /** Retry state for the current step by provider and policy. */
+        llmRetry: LlmRetryState;
+    }
+}
+export declare function apply(ctx: Context, config?: Config, internals?: RetryInternals): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,197 @@
+/**
+ * Provider-routed model-request retry policy on the agent loop's request
+ * recovery extension point. Each scheduled retry is durable before its cancellable wait.
+ *
+ * @module @qilin-agent/llm-retry
+ */
+import { randomUUID } from 'node:crypto';
+import z from '@qilin-agent/schemastery';
+import { z as zod } from 'zod';
+import { RetryId } from "./brand.js";
+export { RetryId } from "./brand.js";
+export const name = 'llm-retry';
+export const inject = ['agents', 'sessionProjections'];
+/** Runtime schema for {@link Config}. */
+export const Config = z.object({});
+function validateConfig(config) {
+    const [key] = Object.keys(config);
+    if (key === undefined)
+        return;
+    if (key === 'retryPolicy') {
+        throw new Error('llm-retry: retryPolicy belongs under each provider configuration');
+    }
+    throw new Error(`llm-retry: unknown key "${key}"`);
+}
+async function settleDownstream(next) {
+    try {
+        return { type: 'decision', decision: await next() };
+    }
+    catch (error) {
+        return { type: 'error', error };
+    }
+}
+function localDelay(config, retry, random) {
+    const exponent = Math.min(retry - 1, 1024);
+    const exponential = Math.min(config.initialDelayMs * 2 ** exponent, config.maxDelayMs);
+    const jitter = 1 - config.jitterRatio + 2 * config.jitterRatio * random();
+    return Math.min(exponential * jitter, config.maxDelayMs);
+}
+function retryPolicyKey(policy) {
+    return policy.mode === 'always'
+        ? JSON.stringify([policy.mode, policy.initialDelayMs, policy.maxDelayMs, policy.jitterRatio])
+        : JSON.stringify([
+            policy.mode,
+            policy.maxRetries,
+            [...policy.retryableCodes].sort(),
+            policy.initialDelayMs,
+            policy.maxDelayMs,
+            policy.jitterRatio,
+        ]);
+}
+function retryStateKey(provider, policyKey) {
+    return JSON.stringify([provider, policyKey]);
+}
+function cancellableDelay(delayMs, signal) {
+    if (signal.aborted)
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(true);
+        }, delayMs);
+        function onAbort() {
+            clearTimeout(timer);
+            resolve(false);
+        }
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+// The cast bridges the branded retry id, which Zod cannot express directly.
+const llmRetryStateSchema = zod.record(zod.string(), zod.object({
+    retry: zod.number().int().nonnegative(),
+    retryId: zod.string(),
+}));
+export function apply(ctx, config = {}, internals = {}) {
+    validateConfig(config);
+    ctx.sessionProjections.register({
+        key: 'llmRetry',
+        stateVersion: 1,
+        stateSchema: llmRetryStateSchema,
+        init: () => ({}),
+        apply: (state, event) => {
+            if (event.type === 'step/start' || event.type === 'turn/end')
+                return {};
+            if (event.type !== 'llm/retry')
+                return state;
+            const key = retryStateKey(event.data.provider, event.data.policyKey);
+            const entry = state[key];
+            if (entry?.retry === event.data.retry && entry.retryId === event.data.retryId)
+                return state;
+            return { ...state, [key]: { retry: event.data.retry, retryId: event.data.retryId } };
+        },
+    });
+    const random = internals.random ?? Math.random;
+    const lifetime = new AbortController();
+    const active = new Set();
+    function track(operation) {
+        const tracked = operation.finally(() => active.delete(tracked));
+        active.add(tracked);
+        return tracked;
+    }
+    async function backoff(agent, turn, step, failure, provider, policy, policyKey, retry, retryId, delayMs, signal) {
+        const fusedSignal = AbortSignal.any([signal, lifetime.signal]);
+        if (fusedSignal.aborted)
+            return;
+        const eventData = policy.mode === 'normal'
+            ? {
+                retryId,
+                turn,
+                step,
+                provider,
+                mode: policy.mode,
+                policyKey,
+                retry,
+                maxRetries: policy.maxRetries,
+                delayMs,
+                failure,
+            }
+            : {
+                retryId,
+                turn,
+                step,
+                provider,
+                mode: policy.mode,
+                policyKey,
+                retry,
+                delayMs,
+                failure,
+            };
+        agent.session.append('llm/retry', eventData);
+        if (!await cancellableDelay(delayMs, fusedSignal))
+            return;
+        agent.session.append('llm/retry-started', { retryId, turn, step, retry });
+        return { kind: 'retry' };
+    }
+    async function recover({ agent, turn, step, provider, failure, retryPolicy: policy, signal }, next) {
+        if (policy === undefined)
+            return next();
+        if (policy.mode === 'always') {
+            if (signal.aborted || lifetime.signal.aborted)
+                return;
+            const fusedSignal = AbortSignal.any([signal, lifetime.signal]);
+            // The loop and plugin lifetime stay open until delegated recovery settles.
+            // An abort then wins before the decision or fallback can mutate later state.
+            const downstream = await settleDownstream(next);
+            if (fusedSignal.aborted)
+                return;
+            if (downstream.type === 'error') {
+                ctx.logger.warn(`llm-retry: provider "${provider}" always policy ignored a downstream recovery failure: %o`, downstream.error);
+            }
+            if (downstream.type === 'decision' && downstream.decision?.kind === 'retry') {
+                return downstream.decision;
+            }
+        }
+        else if (!policy.retryableCodes.includes(failure.code)) {
+            return next();
+        }
+        const policyKey = retryPolicyKey(policy);
+        const retryState = ctx.sessionProjections.stateOf(agent.session, 'llmRetry');
+        const previous = retryState[retryStateKey(provider, policyKey)];
+        const previousRetry = previous?.retry ?? 0;
+        if (policy.mode === 'normal' && previousRetry >= policy.maxRetries)
+            return next();
+        const retry = previousRetry + 1;
+        const retryId = previous?.retryId ?? RetryId(randomUUID());
+        let delayMs;
+        if (failure.providerRetryAfterMs !== undefined
+            && Number.isFinite(failure.providerRetryAfterMs)
+            && failure.providerRetryAfterMs > 0) {
+            if (failure.providerRetryAfterMs > policy.maxDelayMs) {
+                if (policy.mode === 'normal')
+                    return next();
+                delayMs = localDelay(policy, retry, random);
+            }
+            else {
+                delayMs = failure.providerRetryAfterMs;
+            }
+        }
+        else {
+            delayMs = localDelay(policy, retry, random);
+        }
+        return backoff(agent, turn, step, failure, provider, policy, policyKey, retry, retryId, delayMs, signal);
+    }
+    const disposeListener = ctx.on('agent/request-error', (payload, next) => {
+        // A waterfall may have captured this callback before its registration was
+        // removed. Lifetime cancellation must prevent that stale callback from
+        // entering a downstream policy after disposal.
+        if (lifetime.signal.aborted)
+            return Promise.resolve(undefined);
+        return track(recover(payload, next));
+    });
+    ctx.effect(() => async () => {
+        disposeListener();
+        lifetime.abort(new Error('llm-retry plugin disposed'));
+        await Promise.allSettled([...active]);
+    }, 'llm-retry: abort and drain active recovery');
+}
+//# sourceMappingURL=index.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,42 @@
+import type { LlmFailure } from '@qilin-agent/llm/types';
+import type { RetryId } from './brand.ts';
+export type { RetryId };
+declare module '@qilin-agent/session/types' {
+    interface SessionEventMap {
+        /** Durable, non-surface record of one provider-routed retry scheduled after a failed request attempt. */
+        'llm/retry': LlmRetryEventData;
+        /** Durable transition written after a retry wait succeeds and before the next request attempt starts. */
+        'llm/retry-started': LlmRetryStartedEventData;
+    }
+}
+/** Durable payload recorded before one provider-routed model-request retry wait. */
+export type LlmRetryEventData = {
+    retryId: RetryId;
+    turn: number;
+    step: number;
+    provider: string;
+    mode: 'normal';
+    policyKey: string;
+    retry: number;
+    maxRetries: number;
+    delayMs: number;
+    failure: LlmFailure;
+} | {
+    retryId: RetryId;
+    turn: number;
+    step: number;
+    provider: string;
+    mode: 'always';
+    policyKey: string;
+    retry: number;
+    delayMs: number;
+    failure: LlmFailure;
+};
+/** Durable transition recorded after one retry delay completes. */
+export interface LlmRetryStartedEventData {
+    retryId: RetryId;
+    turn: number;
+    step: number;
+    retry: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@qilin-agent/llm-retry",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Provider-routed LLM request retry policy for the QiLin",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/llm/llm-retry"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/session": "3.1.4",
+    "@qilin-agent/agent": "3.1.4",
+    "@qilin-agent/brand": "3.1.4",
+    "@qilin-agent/timeout": "3.1.4",
+    "@qilin-agent/session-projection": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@qilin-agent/schemastery": "~3.18.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/brand": "3.1.4",
+    "@qilin-agent/kylin-plugin-include": "~1.0.8",
+    "@qilin-agent/kylin-plugin-loader": "~1.0.4",
+    "@qilin-agent/agent": "3.1.4",
+    "@qilin-agent/agent-loop": "3.1.4",
+    "@qilin-agent/agent-loop-testkit": "3.1.4",
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/llm-deepseek": "3.1.4",
+    "@qilin-agent/llm-mock-server": "3.1.4",
+    "@qilin-agent/llm-deepseek-api-key": "3.1.4",
+    "@qilin-agent/system-prompt": "3.1.4",
+    "@qilin-agent/session-persistence-jsonl": "3.1.4",
+    "@qilin-agent/timeout": "3.1.4",
+    "@qilin-agent/session-projection": "3.1.4",
+    "@qilin-agent/session": "3.1.4",
+    "@qilin-agent/tools": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3"
+  }
 }