@ai-setting/roy-agent-core 1.7.53 → 1.7.55

package/dist/env/agent/index.js

@@ -2,14 +2,14 @@ import {
   AgentComponent,
   AgentComponentConfigSchema,
   SummaryAgent
-} from "../../shared/@ai-setting/roy-agent-core-3tv1q6f2.js";
+} from "../../shared/@ai-setting/roy-agent-core-ytr2w0vb.js";
 import"../../shared/@ai-setting/roy-agent-core-fvs48d38.js";
 import"../../shared/@ai-setting/roy-agent-core-kzg1jwt8.js";
 import"../../shared/@ai-setting/roy-agent-core-rx16h2m1.js";
 import"../../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";
 import"../../shared/@ai-setting/roy-agent-core-dv714bqh.js";
-import"../../shared/@ai-setting/roy-agent-core-pk1b3kvf.js";
-import"../../shared/@ai-setting/roy-agent-core-zy3hqfwg.js";
+import"../../shared/@ai-setting/roy-agent-core-2b8jtv7m.js";
+import"../../shared/@ai-setting/roy-agent-core-0hq21px2.js";
 import"../../shared/@ai-setting/roy-agent-core-c1v263jn.js";
 import"../../shared/@ai-setting/roy-agent-core-e25xkv53.js";
 import"../../shared/@ai-setting/roy-agent-core-ctdhjv68.js";

package/dist/env/error-reply.d.ts

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview Task #4418: React 循环异常中断 → 给飞书发 reply
+ *
+ * ## 问题（用户飞书 p2p 2026-10-21）
+ *
+ * ```
+ * RetryError [AI_RetryError]: Failed after 4 attempts.
+ * Last error: Upstream request failed: Endpoint is unavailable.
+ * statusCode: 429 / isRetryable: true
+ * ```
+ *
+ * 上游 429 不是 roy-agent 的 bug；但**异常中断后飞书侧完全静默**是。
+ * 用户原话：「这个失败导致的 react 中断，也需要找到对应的 triggerEvent
+ * 构建 response 让飞书方知道（送一个 reply 哈）」。
+ *
+ * ## 为什么必须由框架直接发（不能靠 prompt 引导 agent）
+ *
+ * 正常路径的 reply 是 **LLM 自己调 lark-cli**（prompt 由
+ * `buildNotifyHandlePrompt` / event-source-handlers 生成，告诉 agent
+ * 用 `recommendedAction.replyTo` 回消息）。
+ *
+ * 但异常路径的根本问题是：**LLM 调用本身失败了**，React 循环从未拿到
+ * 一个可用的 assistant turn，自然也不可能再调工具发消息。所以框架必须
+ * 自己 spawn `lark-cli`，这是与正常路径的本质区别。
+ *
+ * ## 断点（为什么曾经没 reply）
+ *
+ * 1. `agent-component.ts:2096` 捕获异常 → `result.error` + `result.originalError`
+ * 2. `environment.ts:430` 非 ContextError → `throw new Error(result.error)`
+ *    ⚠️ 类型在这里丢掉，下游只能拿到字符串
+ * 3. `context-handler.service.ts:224` 直接 rethrow
+ * 4. `query-executor.ts:287` 只处理 ContextError，其余 rethrow
+ * 5. `interactive.ts:1301` / `event-handler.ts:620` 的 catch **只 console.error**
+ *    → 静默丢失
+ *
+ * ## 现在的接线（四处，去重保证不重复）
+ *
+ * 1. `QueryExecutor.execute` 的 catch —— 唯一执行入口，覆盖
+ *    interactive / run / run --es 三种模式，带完整 `agentContext.envEvent`
+ * 2. `EventHandler.processQueue` 的 catch —— 兜住「还没走到 QueryExecutor
+ *    就失败」的路径（session 解析 / 事件分发），并作为 TUI 层吞异常时的
+ *    最后一道防线
+ * 3. REPL `executeInternal` 的 catch —— 兜住 agentContext 组装 / plugin
+ *    加载 / REPL 包装层（这些异常会被 REPL 自己吞掉，到不了 EventHandler）
+ * 4. `LarkCliInstance.handleEvent` 的 catch —— event-source 自身的解析 /
+ *    落库 / 分发失败
+ *
+ * 四处都调用本模块，意味着**任何 React 中断都至少有一个出口到飞书**。
+ *
+ * ## 设计原则
+ *
+ * - **规则表驱动（rule base）**：错误分类 + 是否通知 + 用户文案收敛成
+ *   `FAILURE_RULES` 有序表；表尾 `UNKNOWN_RULE` 是 `notify: true` 的
+ *   catch-all —— 结构上保证**任何未分类错误也不会沉默**。只有
+ *   `ask_user`（正常交互）显式 `notify: false`
+ * - **best-effort**：任何异常（spawn 失败 / lark-cli 非 0 / 库挂了）
+ *   都不得向上抛，绝不污染原始错误传播链
+ * - **有硬超时**：兜底 reply 在 5s 内一定 settle（超时 kill 子进程）。
+ *   否则 lark-cli 卡住会把 `QueryExecutor` 的 rethrow 拖死 → 事件队列堵死
+ * - **复用现有机制**：spawn 参数形态与 `LarkCliNotificationChannel` /
+ *   `event-source-handlers.sendLarkMessage` 保持一致（`--profile` 前置、
+ *   messageId → `+messages-reply`、chatId → `+messages-send`）
+ * - **去重**：同一 triggerEvent（messageId）只回一次；chat-only 通道走
+ *   5 分钟窗口，**不会**把整个群永久封锁；发送失败回滚去重标记
+ * - **无 channel 不崩但也不静默**：本地 REPL / `act` 没有飞书上下文 → debug；
+ *   有 triggerEvent 却拿不到 replyChannel = 衔接 bug → warn
+ * - **用户可读**：给用户看中文原因，技术细节单独放 `technical` 字段（截断）
+ */
+/**
+ * 失败分类。
+ *
+ * 顺序即优先级：越具体的越先匹配。
+ */
+export type ReactFailureKind = "ask_user" | "upstream_retry" | "timeout" | "upstream_aborted" | "aborted" | "context_overflow" | "unknown";
+export interface ReactFailureInfo {
+    kind: ReactFailureKind;
+    /** 命中的规则 id（可观测性 / 测试锚点） */
+    ruleId: string;
+    /** 一行标题（中文，给用户看） */
+    title: string;
+    /** 可读原因（中文，不含 stack trace） */
+    reason: string;
+    /** 是否值得用户稍后重试 */
+    retryable: boolean;
+    /**
+     * 是否应该把这条失败反馈到飞书。
+     *
+     * 只有 `ask_user`（正常交互）为 false —— **所有真正的失败/中断都必须通知**，
+     * 这是 #4418 的硬契约：不允许静默。
+     */
+    notify: boolean;
+    /** 技术细节（截断，供定位；不直接展示给用户） */
+    technical?: string;
+}
+/** replyChannel 的最小形态（同时兼容 EnvReplyChannel / event-source ReplyChannel） */
+export interface FailureReplyChannelLike {
+    type?: string;
+    chatId?: string;
+    messageId?: string;
+    profile?: string;
+    appId?: string;
+    userId?: string;
+}
+export interface NotifyReactFailureOptions {
+    /** 触发 React 中断的错误（任意类型，内部会做类型安全处理） */
+    error: unknown;
+    /**
+     * 触发本次执行的 EnvEvent。
+     *
+     * 从中提取 replyChannel（优先 `metadata.replyChannel`，
+     * 兼容 `payload.replyChannel`），这就是用户说的「找到对应的 triggerEvent」。
+     */
+    envEvent?: unknown;
+    /** 显式 replyChannel（优先级最高，便于调用方直接指定） */
+    replyChannel?: FailureReplyChannelLike;
+    /** 原始 query 摘要（会被截断后放进 reply，便于用户对上号） */
+    query?: string;
+    /** 会话 ID（仅用于日志 / 去重兜底） */
+    sessionId?: string;
+    /** 去重 key 覆盖（默认从 messageId/chatId 推导） */
+    dedupKey?: string;
+    /**
+     * 兜底 reply 的硬超时（ms）。
+     *
+     * 生产默认 5s；仅测试注入短值用。超时后 kill 子进程并按失败返回，
+     * 保证 `QueryExecutor` 的 catch 不会被 lark-cli 挂住。
+     */
+    replyTimeoutMs?: number;
+}
+export interface NotifyReactFailureResult {
+    /** 是否成功投递到飞书 */
+    sent: boolean;
+    /** 失败分类（即使没发送也会返回，调用方可记日志） */
+    kind: ReactFailureKind;
+    /** 结构化失败信息 */
+    info: ReactFailureInfo;
+    /** 跳过原因（sent=false 时有值） */
+    skipped?: "no_channel" | "duplicate" | "not_a_failure";
+    /** 投递错误（sent=false 且确实尝试过时有值） */
+    error?: string;
+}
+/** 当前生效的规则 id 列表（供可观测性 / 文档 / 测试锚定顺序）。 */
+export declare function getFailureRuleIds(): string[];
+/**
+ * 把任意错误分类成结构化、用户可读的失败信息。
+ *
+ * ⚠️ 关键：必须能处理**类型已丢失**的场景 —— 真实调用链上
+ * `environment.ts` 会把 RetryError 字符串化成普通 `Error`，所以只能靠
+ * message 文本特征识别，不能依赖 `instanceof RetryError`。
+ */
+export declare function classifyReactFailure(error: unknown): ReactFailureInfo;
+/**
+ * 生成发给用户的 reply 正文（Markdown）。
+ *
+ * 契约：
+ * - 不含裸 stack trace（`    at `）
+ * - 含「怎么办」的可操作建议
+ * - 总长度远小于飞书 4096 单条上限
+ */
+export declare function buildFailureReplyMarkdown(info: ReactFailureInfo, opts?: {
+    query?: string;
+    sessionId?: string;
+}): string;
+/** 测试用：清空去重状态 */
+export declare function __resetFailureReplyDedupForTest(): void;
+/**
+ * React 循环异常中断时，尽最大努力给飞书发一条失败说明。
+ *
+ * **绝不抛异常** —— 所有错误都被吞掉并记日志，保证不污染原始错误传播。
+ *
+ * @example
+ * ```ts
+ * // interactive.ts executeInternal 的 catch 分支
+ * } catch (error) {
+ *   await notifyReactFailure({
+ *     error,
+ *     envEvent: this.currentAgentContext?.envEvent,
+ *     sessionId: agentContext?.eventSessionId,
+ *   });
+ *   // …原有错误处理继续
+ * }
+ * ```
+ */
+export declare function notifyReactFailure(options: NotifyReactFailureOptions): Promise<NotifyReactFailureResult>;

package/dist/env/event-source/event-source-handlers.d.ts

@@ -106,11 +106,9 @@ export declare class LarkCliInstance implements EventSourceInstance {
     /**
      * ★ Task #4230 follow-up：卡片路由端口（lookup/getTask 侧）
      *
-     * 构建一次、多处复用（含 loadPlugins 收尾时补 ensureTaskGroupChat）。
+     * ★ Task #4394：只剩 `getTask`（无触发群时 lineage 上溯兜底用）。
      */
     private cardRoutingPorts?;
-    /** ★ Task #4230 follow-up：群名缓存（判定"触发群是不是别 task 的专属群"） */
-    private chatNameCache;
     /** ★ Task #4230 follow-up：已加载插件实例（收尾 cross-wire 用） */
     private pluginInstances;
     /**
@@ -269,13 +267,6 @@ export declare class LarkCliInstance implements EventSourceInstance {
      * 任意一环缺失（如没配 task component）→ 不注入，行为与之前一致（warn + skip）。
      */
     private wireCardActionPorts;
-    /**
-     * Task #4230 follow-up：把「按需建专属群」能力接到卡片路由端口上
-     *
-     * 顺序问题：两个插件是分别 import + registerPluginHooks 的，NotifyHook 在
-     * PerTaskGroupChatPlugin 之前加载，所以只能在 loadPlugins 收尾时补一次。
-     */
-    private wireCardRoutingGroupProvider;
     /**
      * 获取插件的 hook 点列表
      */
@@ -330,22 +321,17 @@ export declare class LarkCliInstance implements EventSourceInstance {
      */
     private injectTaskGetter;
     /**
-     * ★ Task #4230 follow-up：给支持 setCardRoutingPorts 的 plugin 注入「卡片路由端口」
+     * ★ Task #4230 follow-up / ★ Task #4394 精简：注入「卡片路由端口」
      *
-     * 端口负责三件"需要 IO"的事（让 plugin 保持纯逻辑 + 可单测）：
-     * 1. lookupChatOwnership(chatId)：这个群是不是某个 task 的专属群（多重信号）
-     * 2. getTask(id)：lineage 上溯
-     * 3. ensureTaskGroupChat(task)：按需建专属群（由 PerTaskGroupChatPlugin 提供，
-     *    在 loadPlugins 收尾时 cross-wire）
-     */
-    private injectCardRoutingPorts;
-    /**
-     * 取群名（带进程内缓存）
+     * ★ Task #4394 删除：`lookupChatOwnership` + `lookupChatName` + `chatNameCache`
+     *   —— 卡片不再判定"触发群是不是别 task 的专属群"，因此整套群归属反查
+     *   （session chat↔task 绑定 + `findTasksByContextValue` DB LIKE + lark-cli
+     *   查群名）都不再需要。这同时省掉了每张卡一次 DB 查询 + 一次 lark-cli 调用。
      *
-     * 只在需要判定"触发群是不是别 task 的群"时调用（DB 信号为空才会走到）。
-     * lark-cli 失败 / 未安装 → 返回 undefined（判定退化为"不是专属群"）。
+     * 保留 `getTask(id)`：无触发群时，仍需要沿 lineage 上溯找本 task / 祖先
+     * 已有的专属群兜底（卡片不能丢）。
      */
-    private lookupChatName;
+    private injectCardRoutingPorts;
     /**
      * ★ Task #4023：如果 plugin 支持 setSessionComponent，自动注入 SessionComponent 引用
      *

package/dist/env/event-source/index.js

@@ -11,7 +11,7 @@ import {
   larkCliHandler,
   resolveBountyIMSystemPrompt,
   timerHandler
-} from "../../shared/@ai-setting/roy-agent-core-ph5qbqcx.js";
+} from "../../shared/@ai-setting/roy-agent-core-j2nvedt6.js";
 import {
   BUILT_IN_EVENT_SOURCE_TYPES,
   BUILT_IN_EVENT_SOURCE_TYPE_LIST,
@@ -22,7 +22,7 @@ import {
   validateEventSourceConfig
 } from "../../shared/@ai-setting/roy-agent-core-ck60j1q9.js";
 import"../../shared/@ai-setting/roy-agent-core-rnwr39b0.js";
-import"../../shared/@ai-setting/roy-agent-core-hch2geta.js";
+import"../../shared/@ai-setting/roy-agent-core-g36jevrk.js";
 import {
   EventStoreImpl,
   getSharedEventStore,
@@ -30,11 +30,11 @@ import {
   setSharedEventStore
 } from "../../shared/@ai-setting/roy-agent-core-yhsssn86.js";
 import"../../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
-import"../../shared/@ai-setting/roy-agent-core-gdsqp6j8.js";
-import"../../shared/@ai-setting/roy-agent-core-brwzs8wf.js";
-import"../../shared/@ai-setting/roy-agent-core-j8e92gj8.js";
+import"../../shared/@ai-setting/roy-agent-core-6masakz4.js";
+import"../../shared/@ai-setting/roy-agent-core-9h72sk1n.js";
+import"../../shared/@ai-setting/roy-agent-core-b5ew8t0k.js";
 import"../../shared/@ai-setting/roy-agent-core-9csa89jx.js";
-import"../../shared/@ai-setting/roy-agent-core-na73mym1.js";
+import"../../shared/@ai-setting/roy-agent-core-a4vzsn0g.js";
 import"../../shared/@ai-setting/roy-agent-core-8s9jd2qy.js";
 import"../../shared/@ai-setting/roy-agent-core-jrj30vq3.js";
 import"../../shared/@ai-setting/roy-agent-core-dv714bqh.js";

package/dist/env/index.js

@@ -1,21 +1,21 @@
 import {
   BaseEnvironment
-} from "../shared/@ai-setting/roy-agent-core-4sx6sdb2.js";
+} from "../shared/@ai-setting/roy-agent-core-cd62e9p1.js";
 import {
   TaskComponent
-} from "../shared/@ai-setting/roy-agent-core-39xejr39.js";
+} from "../shared/@ai-setting/roy-agent-core-e2z1etk4.js";
 import"../shared/@ai-setting/roy-agent-core-amkqnyzy.js";
 import"../shared/@ai-setting/roy-agent-core-qm9jda8p.js";
 import"../shared/@ai-setting/roy-agent-core-7g03zkkb.js";
 import"../shared/@ai-setting/roy-agent-core-rn57psp0.js";
 import"../shared/@ai-setting/roy-agent-core-8gxth0eh.js";
-import"../shared/@ai-setting/roy-agent-core-p2r27era.js";
+import"../shared/@ai-setting/roy-agent-core-mxdc756a.js";
 import"../shared/@ai-setting/roy-agent-core-tbrn9wdm.js";
 import {
   EventSourceComponent,
   builtInHandlers,
   larkCliHandler
-} from "../shared/@ai-setting/roy-agent-core-ph5qbqcx.js";
+} from "../shared/@ai-setting/roy-agent-core-j2nvedt6.js";
 import {
   EventSourceInitHooks,
   getDefaultConfigForType,
@@ -24,33 +24,33 @@ import {
   validateEventSourceConfig
 } from "../shared/@ai-setting/roy-agent-core-ck60j1q9.js";
 import"../shared/@ai-setting/roy-agent-core-rnwr39b0.js";
-import"../shared/@ai-setting/roy-agent-core-hch2geta.js";
+import"../shared/@ai-setting/roy-agent-core-g36jevrk.js";
 import"../shared/@ai-setting/roy-agent-core-yhsssn86.js";
 import"../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
-import"../shared/@ai-setting/roy-agent-core-gdsqp6j8.js";
-import"../shared/@ai-setting/roy-agent-core-brwzs8wf.js";
-import"../shared/@ai-setting/roy-agent-core-j8e92gj8.js";
+import"../shared/@ai-setting/roy-agent-core-6masakz4.js";
+import"../shared/@ai-setting/roy-agent-core-9h72sk1n.js";
+import"../shared/@ai-setting/roy-agent-core-b5ew8t0k.js";
 import {
   WorkflowComponent
-} from "../shared/@ai-setting/roy-agent-core-4vpk40ss.js";
+} from "../shared/@ai-setting/roy-agent-core-8eqngasy.js";
 import"../shared/@ai-setting/roy-agent-core-vrsxhw9e.js";
 import"../shared/@ai-setting/roy-agent-core-h0x19xgn.js";
 import"../shared/@ai-setting/roy-agent-core-1ce3fqrk.js";
-import"../shared/@ai-setting/roy-agent-core-vvxb9522.js";
-import"../shared/@ai-setting/roy-agent-core-yd21n6c7.js";
-import"../shared/@ai-setting/roy-agent-core-h93v6p6y.js";
+import"../shared/@ai-setting/roy-agent-core-6qxh4xrm.js";
+import"../shared/@ai-setting/roy-agent-core-zvemdfx5.js";
+import"../shared/@ai-setting/roy-agent-core-7qy3nffr.js";
 import"../shared/@ai-setting/roy-agent-core-hhrg314p.js";
 import"../shared/@ai-setting/roy-agent-core-7evvpfwc.js";
-import"../shared/@ai-setting/roy-agent-core-35s1w7tc.js";
+import"../shared/@ai-setting/roy-agent-core-aer5kw1j.js";
 import"../shared/@ai-setting/roy-agent-core-6atd905e.js";
 import"../shared/@ai-setting/roy-agent-core-6167phd4.js";
-import"../shared/@ai-setting/roy-agent-core-x8n1r7h4.js";
+import"../shared/@ai-setting/roy-agent-core-2bscfrr1.js";
 import"../shared/@ai-setting/roy-agent-core-1db4vpc6.js";
 import"../shared/@ai-setting/roy-agent-core-ze068vc9.js";
 import"../shared/@ai-setting/roy-agent-core-fs36xgcs.js";
 import"../shared/@ai-setting/roy-agent-core-9csa89jx.js";
 import"../shared/@ai-setting/roy-agent-core-7exqwax1.js";
-import"../shared/@ai-setting/roy-agent-core-na73mym1.js";
+import"../shared/@ai-setting/roy-agent-core-a4vzsn0g.js";
 import"../shared/@ai-setting/roy-agent-core-tjg71zqp.js";
 import"../shared/@ai-setting/roy-agent-core-ddwa0n6h.js";
 import"../shared/@ai-setting/roy-agent-core-8s9jd2qy.js";
@@ -59,7 +59,7 @@ import"../shared/@ai-setting/roy-agent-core-rvxg1wps.js";
 import {
   AgentComponent,
   AgentComponentConfigSchema
-} from "../shared/@ai-setting/roy-agent-core-3tv1q6f2.js";
+} from "../shared/@ai-setting/roy-agent-core-ytr2w0vb.js";
 import"../shared/@ai-setting/roy-agent-core-fvs48d38.js";
 import"../shared/@ai-setting/roy-agent-core-kzg1jwt8.js";
 import"../shared/@ai-setting/roy-agent-core-rx16h2m1.js";
@@ -69,8 +69,8 @@ import {
   getXDGPaths
 } from "../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";
 import"../shared/@ai-setting/roy-agent-core-dv714bqh.js";
-import"../shared/@ai-setting/roy-agent-core-pk1b3kvf.js";
-import"../shared/@ai-setting/roy-agent-core-zy3hqfwg.js";
+import"../shared/@ai-setting/roy-agent-core-2b8jtv7m.js";
+import"../shared/@ai-setting/roy-agent-core-0hq21px2.js";
 import"../shared/@ai-setting/roy-agent-core-c1v263jn.js";
 import"../shared/@ai-setting/roy-agent-core-e25xkv53.js";
 import {

package/dist/env/llm/adapter-pi-ai.d.ts

@@ -11,16 +11,161 @@
  * - AssistantMessage.stopReason → ChatResponse.finishReason
  * - usage {input, output, totalTokens} → UsageInfo
  */
-import { type Model, type Context } from "@earendil-works/pi-ai";
+import { type Model, type Context, type CacheRetention } from "@earendil-works/pi-ai";
 import type { LLMAdapter, ChatRequest, ChatResponse, StreamHandle, ResolvedProvider, EmbedRequest, EmbedResponse } from "./adapter";
 import type { LLMMessage, ToolInfo } from "./types";
+/**
+ * Known provider list — 驱动 resolveProvider 的硬编码能力映射
+ *
+ * `apiProtocol`（Task #4383 P1）是**显式**协议声明，优先于任何 baseURL 猜测。
+ * 历史背景：`api` 字段曾被 `resolvePiModel()` 里的字面量特判
+ * （`baseURL?.includes("anthropic")`）绕过 —— minimax 因为真实 baseURL 恰好是
+ * `https://api.minimaxi.com/anthropic` 才「误打误撞」走对 anthropic-messages，
+ * 从而成为三家 provider 里唯一挂上显式 `cache_control` 的那个（#4381 实测 99.86%）。
+ * 现在把它变成声明式的，避免「换个 baseURL 就悄悄改了协议」。
+ *
+ * `api` 保留为**向后兼容**的遗留字段（只在既无 `apiProtocol` 也无 baseURL 线索时兜底）。
+ */
+export declare const KNOWN_PROVIDER_APIS: Record<string, {
+    api: string;
+    apiProtocol?: string;
+    contextLimit: number;
+    maxTokensLimit: number;
+}>;
+/**
+ * Resolve the pi-ai API protocol for a provider (Task #4383 P1).
+ *
+ * Resolution order (first match wins):
+ *   1. `explicitProtocol` — caller/config pins it, highest priority
+ *   2. `PROVIDER_API_OVERRIDES` — deliberate id-variant pins
+ *   3. `PROVIDER_ENDPOINT_APIS[provider]` — declared per-endpoint mapping
+ *      (only for vendors that genuinely ship two protocols)
+ *   4. `KNOWN_PROVIDER_APIS[provider].apiProtocol` — declarative vendor default
+ *   5. generic `baseURL` heuristics — backward compat for user-defined proxies
+ *      (`/responses` → openai-responses, `anthropic` → anthropic-messages).
+ *      This path logs a warning so we notice configs that should be declared.
+ *   6. `KNOWN_PROVIDER_APIS[provider].api` — legacy field
+ *   7. `openai-completions` — final fallback
+ *
+ * @param provider         roy-agent provider id from config (e.g. "minimax")
+ * @param baseURL          resolved provider base URL (may be undefined)
+ * @param explicitProtocol optional explicit protocol from caller/config
+ */
+export declare function resolveApiProtocol(provider: string, baseURL?: string, explicitProtocol?: string): string;
+/**
+ * pi-ai `Model.compat` overrides that make `reasoning: true` a **byte-level
+ * no-op** for the openai-completions request body (Task #4403).
+ *
+ * Both entries are load-bearing and were derived empirically by capturing the
+ * real payload through pi-ai's public `onPayload` hook and diffing it against
+ * the `reasoning: false` baseline:
+ *
+ * - `supportsDeveloperRole: false` — without it, `openai-completions.js:591`
+ *   computes `useDeveloperRole = model.reasoning && compat.supportsDeveloperRole`
+ *   and rewrites the first message's role from `system` to `developer`.
+ *   That difference lands at **JSON offset ~40** (the very start of the body),
+ *   so prompt caching — which is a prefix match — would miss on every turn.
+ * - `thinkingFormat: "openai"` — without it, `openai-completions.js:433-475`
+ *   picks the vendor's native thinking branch and, because roy-agent never
+ *   passes `options.reasoningEffort`, emits an explicit
+ *   `thinking: {type: "disabled"}` (deepseek) / `enable_thinking: false`
+ *   (zai/qwen). That is a new top-level field the provider never saw before.
+ *
+ * With all three pins the payload is byte-identical to the `reasoning: false`
+ * baseline for every CUSTOM provider in the real config (verified for
+ * opencodego / glm / minimax / ali / volcengine / tong / opencode, plus
+ * deepseek once the Task #4398 `reasoning_content` hook is attached), so
+ * turning reasoning on can never regress the cache.
+ *
+ * Scope caveat: this guarantee covers the **fallback** (custom-provider)
+ * branch of `resolvePiModel()`. pi-ai built-ins keep their own hand-tuned
+ * `compat`/`reasoning` in the descriptor and are deliberately left alone.
+ */
+export declare const REASONING_COMPAT_PIN: {
+    readonly supportsDeveloperRole: false;
+    readonly thinkingFormat: "openai";
+    readonly supportsReasoningEffort: false;
+};
+/**
+ * Protocols where {@link REASONING_COMPAT_PIN} can actually hold the payload
+ * byte-stable.
+ *
+ * `openai-responses` is deliberately excluded: pi-ai flips the system prompt
+ * role there **unconditionally** —
+ *   `openai-responses-shared.js:66: const role = model.reasoning ? "developer" : "system"`
+ * — with no `compat` escape hatch (its `getCompat()` only exposes
+ * `sendSessionIdHeader` / `supportsLongCacheRetention`). So on that path
+ * `reasoning: true` is a guaranteed prefix break, and we keep it off.
+ */
+export declare const REASONING_SAFE_PROTOCOLS: ReadonlySet<string>;
+/**
+ * Decide the `reasoning` flag for a pi-ai model descriptor (Task #4403).
+ *
+ * This replaces the hardcoded `reasoning: false` that `resolvePiModel()` used
+ * to emit for every non-built-in (i.e. every custom) provider — the root
+ * problem flagged by Task #4398, because that literal silently disabled every
+ * `model.reasoning`-gated pi-ai capability.
+ *
+ * Resolution order:
+ *   1. protocol safety guard — see {@link REASONING_SAFE_PROTOCOLS}. Even an
+ *      explicit `capabilities.reasoning: true` cannot win here, because on
+ *      `openai-responses` the request prefix is guaranteed to change.
+ *   2. explicit config `capabilities.reasoning` (either `true` or `false`).
+ *   3. conservative default `false`.
+ *
+ * Deliberately NO model-name pattern matching. Guessing from names (e.g.
+ * "looks like a reasoner") risks emitting provider-specific thinking fields
+ * that the backend rejects (400), makes calls slower, and bills thinking
+ * tokens as output. Config is the only source of truth; absence means off.
+ *
+ * @param provider    roy-agent provider id (may be a gateway)
+ * @param modelId     model id requested from the provider
+ * @param capabilities `llm.providers.<id>.capabilities` from config
+ * @param apiProtocol resolved pi-ai API protocol for this target
+ */
+export declare function resolveModelReasoning(provider: string, modelId: string, capabilities?: {
+    reasoning?: boolean;
+}, apiProtocol?: string): boolean;
+/**
+ * Build the pi-ai cache-related request options (Task #4383 P0).
+ *
+ * Why this exists (#4381 root cause): pi-ai only emits an explicit cache
+ * marker when it is handed the right options. Two independent code paths:
+ *
+ * - **openai-completions** (`openai-completions.js:394-398`): `prompt_cache_key`
+ *   is only set when `baseUrl` contains `api.openai.com` **or**
+ *   `cacheRetention === "long" && compat.supportsLongCacheRetention`.
+ *   deepseek / glm are neither `api.openai.com` nor passed any retention, so
+ *   `prompt_cache_key` was permanently `undefined` → they fell back to implicit
+ *   caching. Passing `cacheRetention: "long"` also sets
+ *   `prompt_cache_retention: "24h"`.
+ * - **anthropic-messages** (`anthropic.js:25-36, 667-707`): `cache_control`
+ *   markers are attached whenever `cacheRetention !== "none"`, and pi-ai
+ *   already defaults to `"short"` (ephemeral, no ttl). That default is exactly
+ *   what makes minimax hit 99.86%, so we must NOT override it — passing
+ *   `"long"` would add `ttl: "1h"` and silently change current behaviour.
+ *
+ * Hence: openai-completions defaults to `"long"`, everything else keeps pi-ai's
+ * own default unless the caller explicitly asks for a retention.
+ *
+ * @returns options fragment to spread into `complete()` / `stream()` options.
+ *          Only keys that should actually be sent are present (no `undefined`
+ *          values), so `"sessionId" in opts` stays a meaningful assertion.
+ */
+export declare function buildPiCacheOptions(args: {
+    apiProtocol: string;
+    sessionId?: string;
+    cacheRetention?: CacheRetention;
+}): Record<string, unknown>;
 /**
  * Resolve built-in models and models declared by roy-agent configuration.
  * pi-ai's generated registry only contains its bundled provider/model pairs;
  * custom provider ids (for example minimax-openai) need a complete Model
  * descriptor before complete()/stream() can dispatch by API.
  */
-export declare function resolvePiModel(provider: string, modelId: string, baseURL?: string): Model<any>;
+export declare function resolvePiModel(provider: string, modelId: string, baseURL?: string, capabilities?: {
+    reasoning?: boolean;
+}): Model<any>;
 /**
  * 将 LLMMessage 转换为 pi-ai 的消息结构
  */

package/dist/env/llm/adapter.d.ts

@@ -8,7 +8,7 @@
  *
  * 通过 {@link createLLMAdapter} 选择，由环境变量 `ROY_LLM_PROVIDER` 控制。
  */
-import type { LLMMessage, ToolInfo, UsageInfo } from "./types";
+import type { LLMMessage, ToolInfo, UsageInfo, ProviderCapabilities } from "./types";
 /** Adapter 名称（联合类型 + 运行时数组） */
 export type AdapterName = "pi-ai" | "ai-sdk";
 /** 运行时可用的 adapter 列表 */
@@ -40,6 +40,26 @@ export interface ChatRequest {
      * `x-opencode-session` header (see opencode-session.ts).
      */
     sessionId?: string;
+    /**
+     * Prompt-cache retention preference (Task #4383 P0).
+     *
+     * Forwarded to pi-ai's `ProviderStreamOptions.cacheRetention`. When omitted,
+     * `buildPiCacheOptions()` applies a protocol-aware default:
+     * - `openai-completions` → `"long"` (needed for `prompt_cache_key`)
+     * - anything else → pi-ai's own default (`anthropic` uses `"short"` =
+     *   ephemeral `cache_control`, which is the behaviour minimax already relies on)
+     */
+    cacheRetention?: "none" | "short" | "long";
+    /**
+     * Provider capabilities from config (`llm.providers.<id>.capabilities`).
+     *
+     * Task #4403: this is the data path that was missing. `resolvePiModel()` used
+     * to hardcode `reasoning: false` for every custom provider, so
+     * `capabilities.reasoning` in config never influenced the pi-ai model
+     * descriptor at all. Threading it through here lets the descriptor reflect
+     * what the user actually configured.
+     */
+    capabilities?: ProviderCapabilities;
 }
 /** Chat 响应（统一形状） */
 export interface ChatResponse {

package/dist/env/llm/index.js

@@ -14,7 +14,7 @@ import {
   createLLMAdapter,
   getLLMProviderOverride,
   setLLMProvider
-} from "../../shared/@ai-setting/roy-agent-core-p8ak03s0.js";
+} from "../../shared/@ai-setting/roy-agent-core-w527pcpe.js";
 import"../../shared/@ai-setting/roy-agent-core-adg9ghbt.js";
 import"../../shared/@ai-setting/roy-agent-core-zjdzk1gg.js";
 import {
@@ -28,7 +28,7 @@ import {
   isOpencodeEndpoint,
   isOpencodeProvider,
   parseModelString
-} from "../../shared/@ai-setting/roy-agent-core-zy3hqfwg.js";
+} from "../../shared/@ai-setting/roy-agent-core-0hq21px2.js";
 import"../../shared/@ai-setting/roy-agent-core-ctdhjv68.js";
 import"../../shared/@ai-setting/roy-agent-core-7hh0brvs.js";
 import"../../shared/@ai-setting/roy-agent-core-tdbv7ff4.js";