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

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-d4jpn06f.js";
 import {
   TaskComponent
-} from "../shared/@ai-setting/roy-agent-core-39xejr39.js";
+} from "../shared/@ai-setting/roy-agent-core-e0wbq0qq.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-3kz6934b.js";
+import"../shared/@ai-setting/roy-agent-core-pemxr5n4.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-vmg30n5x.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-2044fbsd.js";
 import {
   EventSourceInitHooks,
   getDefaultConfigForType,
@@ -23,78 +23,79 @@ import {
   isValidEventSourceType,
   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-yhsssn86.js";
+import"../shared/@ai-setting/roy-agent-core-w7hnjhvx.js";
+import"../shared/@ai-setting/roy-agent-core-ezsyyjxw.js";
+import"../shared/@ai-setting/roy-agent-core-zmeka63k.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-xcq04fq0.js";
+import"../shared/@ai-setting/roy-agent-core-nntphgww.js";
 import {
   WorkflowComponent
-} from "../shared/@ai-setting/roy-agent-core-4vpk40ss.js";
-import"../shared/@ai-setting/roy-agent-core-vrsxhw9e.js";
+} from "../shared/@ai-setting/roy-agent-core-nhk0dsxr.js";
+import"../shared/@ai-setting/roy-agent-core-e677am8e.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-0bmk44ye.js";
+import"../shared/@ai-setting/roy-agent-core-bwzy00t2.js";
+import"../shared/@ai-setting/roy-agent-core-tc7gw38m.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-5rxs0ra3.js";
+import"../shared/@ai-setting/roy-agent-core-v2188rnk.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-833t16n1.js";
+import"../shared/@ai-setting/roy-agent-core-n3b7ztms.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-3dkzqqsd.js";
+import"../shared/@ai-setting/roy-agent-core-r9qe0ghe.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-tjg71zqp.js";
+import"../shared/@ai-setting/roy-agent-core-202v00x4.js";
+import"../shared/@ai-setting/roy-agent-core-3mc6vmvj.js";
 import"../shared/@ai-setting/roy-agent-core-ddwa0n6h.js";
-import"../shared/@ai-setting/roy-agent-core-8s9jd2qy.js";
+import"../shared/@ai-setting/roy-agent-core-nra8vfrs.js";
 import"../shared/@ai-setting/roy-agent-core-jrj30vq3.js";
 import"../shared/@ai-setting/roy-agent-core-rvxg1wps.js";
 import {
   AgentComponent,
   AgentComponentConfigSchema
-} from "../shared/@ai-setting/roy-agent-core-3tv1q6f2.js";
-import"../shared/@ai-setting/roy-agent-core-fvs48d38.js";
+} from "../shared/@ai-setting/roy-agent-core-9nv586rw.js";
+import"../shared/@ai-setting/roy-agent-core-98aa9r0x.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-97eyghsp.js";
 import {
   XDG_PATHS,
   getXDGPath,
   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-wafk25ff.js";
+import"../shared/@ai-setting/roy-agent-core-ns3pbyz4.js";
+import"../shared/@ai-setting/roy-agent-core-yv9x4wmg.js";
+import"../shared/@ai-setting/roy-agent-core-zjdzk1gg.js";
 import"../shared/@ai-setting/roy-agent-core-c1v263jn.js";
 import"../shared/@ai-setting/roy-agent-core-e25xkv53.js";
 import {
   PluginComponent
-} from "../shared/@ai-setting/roy-agent-core-t37wbysj.js";
+} from "../shared/@ai-setting/roy-agent-core-5gw6w424.js";
 import"../shared/@ai-setting/roy-agent-core-64f22h1g.js";
 import"../shared/@ai-setting/roy-agent-core-az13yzmc.js";
 import {
   McpComponent
-} from "../shared/@ai-setting/roy-agent-core-dwx9hjwx.js";
+} from "../shared/@ai-setting/roy-agent-core-c6at31ra.js";
 import"../shared/@ai-setting/roy-agent-core-8t7wny6v.js";
 import"../shared/@ai-setting/roy-agent-core-ctdhjv68.js";
 import"../shared/@ai-setting/roy-agent-core-7hh0brvs.js";
 import {
   BaseComponent
-} from "../shared/@ai-setting/roy-agent-core-tdbv7ff4.js";
+} from "../shared/@ai-setting/roy-agent-core-40xzbjtm.js";
 import {
   createHook,
   createPriorityHook
-} from "../shared/@ai-setting/roy-agent-core-qcspfszy.js";
+} from "../shared/@ai-setting/roy-agent-core-gngjkw3b.js";
 import {
   HookManager
-} from "../shared/@ai-setting/roy-agent-core-4z3rq5gw.js";
-import"../shared/@ai-setting/roy-agent-core-k8b440n3.js";
+} from "../shared/@ai-setting/roy-agent-core-1pnfkspm.js";
+import"../shared/@ai-setting/roy-agent-core-16t0zfbk.js";
 import {
   createEnvContext,
   getEnvContext,
@@ -103,8 +104,8 @@ import {
   mergeEnvContext,
   runWithEnvContext,
   runWithEnvContextAsync
-} from "../shared/@ai-setting/roy-agent-core-5apmk4qw.js";
-import"../shared/@ai-setting/roy-agent-core-dsevjbck.js";
+} from "../shared/@ai-setting/roy-agent-core-jszgaevt.js";
+import"../shared/@ai-setting/roy-agent-core-b599jgyd.js";
 import"../shared/@ai-setting/roy-agent-core-8seq65bp.js";
 import"../shared/@ai-setting/roy-agent-core-jnszp0jq.js";
 import"../shared/@ai-setting/roy-agent-core-fnv3ev18.js";

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

@@ -3,6 +3,12 @@ export declare class AiSdkAdapter implements LLMAdapter {
     readonly name: "ai-sdk";
     chat(req: ChatRequest): Promise<ChatResponse>;
     stream(req: ChatRequest): Promise<StreamHandle>;
+    /**
+     * ★ 2026-10-22：**只存摘要**（Task #4479）。embed 的 `input` 是大字符串数组，
+     * 返回值 embedding 向量更大 —— 正常路径由 filter 存「条数/维度」摘要。
+     * 这里额外保留 `recordResult: false` 作为兜底：万一 filter 失效，
+     * 宁可没有 result 列，也不能把整个向量数组写进 DB。
+     */
     embed(req: EmbedRequest): Promise<EmbedResponse>;
     resolveProvider(provider: string, modelId: string): Promise<ResolvedProvider>;
     private toInvokeConfig;

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 的消息结构
  */
@@ -34,6 +179,11 @@ export declare class PiAiAdapter implements LLMAdapter {
     readonly name: "pi-ai";
     chat(req: ChatRequest): Promise<ChatResponse>;
     stream(req: ChatRequest): Promise<StreamHandle>;
+    /**
+     * ★ 2026-10-22：**只存摘要**（Task #4479）。embed 的 `texts` 是大字符串数组，
+     * 绝不能入库；返回值向量同理。正常路径由 filter 存摘要，
+     * `recordResult: false` 只是 filter 失效时的兜底（见 ai_sdk.embed 的说明）。
+     */
     embed(_req: EmbedRequest): Promise<EmbedResponse>;
     resolveProvider(provider: string, modelId: string): Promise<ResolvedProvider>;
 }

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

@@ -7,17 +7,16 @@ import {
   LLMHooks,
   LLMTransform,
   ModelLimitsSchema,
-  PiAiAdapter,
   ProviderCapabilitiesSchema,
   ProviderConfigSchema,
   ProviderManager,
   createLLMAdapter,
   getLLMProviderOverride,
   setLLMProvider
-} from "../../shared/@ai-setting/roy-agent-core-p8ak03s0.js";
+} from "../../shared/@ai-setting/roy-agent-core-q7zksbw0.js";
 import"../../shared/@ai-setting/roy-agent-core-adg9ghbt.js";
-import"../../shared/@ai-setting/roy-agent-core-zjdzk1gg.js";
 import {
+  PiAiAdapter,
   buildOpencodeHeaders,
   convertToSDKMessages,
   createInvokeConfig,
@@ -28,15 +27,16 @@ import {
   isOpencodeEndpoint,
   isOpencodeProvider,
   parseModelString
-} from "../../shared/@ai-setting/roy-agent-core-zy3hqfwg.js";
+} from "../../shared/@ai-setting/roy-agent-core-yv9x4wmg.js";
+import"../../shared/@ai-setting/roy-agent-core-zjdzk1gg.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";
-import"../../shared/@ai-setting/roy-agent-core-qcspfszy.js";
-import"../../shared/@ai-setting/roy-agent-core-4z3rq5gw.js";
-import"../../shared/@ai-setting/roy-agent-core-k8b440n3.js";
-import"../../shared/@ai-setting/roy-agent-core-5apmk4qw.js";
-import"../../shared/@ai-setting/roy-agent-core-dsevjbck.js";
+import"../../shared/@ai-setting/roy-agent-core-40xzbjtm.js";
+import"../../shared/@ai-setting/roy-agent-core-gngjkw3b.js";
+import"../../shared/@ai-setting/roy-agent-core-1pnfkspm.js";
+import"../../shared/@ai-setting/roy-agent-core-16t0zfbk.js";
+import"../../shared/@ai-setting/roy-agent-core-jszgaevt.js";
+import"../../shared/@ai-setting/roy-agent-core-b599jgyd.js";
 import"../../shared/@ai-setting/roy-agent-core-8seq65bp.js";
 import"../../shared/@ai-setting/roy-agent-core-jnszp0jq.js";
 import"../../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";

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

@@ -5,7 +5,7 @@
  * Stream events are published via Environment.pushEnvEvent().
  */
 import { type ModelMessage } from "ai";
-import type { ToolInfo, ToolResult, LLMOutput, LLMMessage } from "./types";
+import type { ToolInfo, ToolResult, LLMOutput, LLMMessage, ProviderCapabilities } from "./types";
 import type { Environment } from "../interface";
 import { __clearOpencodeSessionIdCache } from "./opencode-session";
 /**
@@ -24,6 +24,15 @@ export interface InvokeConfig {
     baseURL?: string;
     /** API Key */
     apiKey: string;
+    /**
+     * Provider capabilities from config (`llm.providers.<id>.capabilities`).
+     *
+     * Task #4403: declared here so `LLMComponent.invoke()` can forward it to
+     * `ChatRequest.capabilities` without an `as any` cast. Typed as the full
+     * `ProviderCapabilities` shape (not just `{ reasoning?: boolean }`) because
+     * the runtime value is the whole object from config.
+     */
+    capabilities?: ProviderCapabilities;
     /** 额外选项 */
     options?: {
         /**
@@ -79,6 +88,18 @@ export interface InvokeOptions {
             name: string;
         };
     };
+    /**
+     * Prompt-cache retention preference (Task #4465).
+     *
+     * path A already honours this through `buildPiCacheOptions()`; path B (this
+     * AI SDK fallback) ignored it entirely, so every fallback request paid full
+     * input price. Forwarded to the outbound defence middleware, which emits
+     * `prompt_cache_key` / `prompt_cache_retention` on OpenAI-family protocols.
+     *
+     * Omitted → the middleware defaults to `"long"` for OpenAI-family protocols,
+     * matching path A's default for `openai-completions`.
+     */
+    cacheRetention?: "none" | "short" | "long";
 }
 /**
  * LLM Tool Context - Context for tool calls during LLM invocation
@@ -187,6 +208,37 @@ export declare function parseModelString(model?: string): {
  * `undefined` means the provider did not report the field at all.
  */
 export declare function extractUsageInfo(usage: AISDKUsage | undefined): ConvertedUsageInfo | undefined;
+/**
+ * 计算 prompt cache 命中率（0..1）。
+ *
+ * Task #4373：这是把「roy-agent 自己的缓存命中」变成可观测量的关键 helper。
+ *
+ * ⚠️ 语义陷阱（上一轮 #4369 已经踩过一次）：
+ *
+ *   pi-ai 上报的 `promptTokens` 是 **已扣除缓存后的新增量**：
+ *     `input = max(0, prompt_tokens - cacheRead - cacheWrite)`
+ *     `totalTokens = input + output + cacheRead + cacheWrite`
+ *   （见 `pi-ai/dist/providers/openai-completions.js::parseChunkUsage`、
+ *     以及 `anthropic.js` 的 message_start 分支——同样把 cacheRead /
+ *     cacheWrite 单独累加进 totalTokens）
+ *
+ *   所以 `cacheRead / promptTokens` 在真实暖流数据下会算出 20,960%
+ *   这种荒谬值。正确的分母是「模型实际处理过的全部 input token」：
+ *
+ *     promptTokensTotal = promptTokens + cacheRead + cacheWrite
+ *     hitRate = cacheRead / promptTokensTotal
+ *
+ * @param usage - 至少包含 promptTokens；cache 字段可选
+ * @returns 0..1 之间的命中率。无缓存信息 / 无 input token 时返回 0（不是 NaN）
+ */
+export declare function computeCacheHitRate(usage: {
+    promptTokens: number;
+    /** Cache-aware denominator; when present it wins over the derivation below. */
+    promptTokensTotal?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    cacheMiss?: number;
+}): number;
 /**
  * Recursively sort object keys for deterministic byte serialization.
  *
@@ -242,8 +294,28 @@ export declare function invoke(config: InvokeConfig, options: InvokeOptions, ctx
 /**
  * 创建 Provider 实例
  * 根据 providerId 创建对应的 AI SDK Provider
+ *
+ * Task #4465: every branch that can actually reach the wire installs an
+ * outbound defence `fetch` middleware (see outbound-defense.ts). The `google`
+ * branch is deliberately excluded: `createGoogleGenerativeAI` exposes no
+ * `fetch` option, and Google needs neither the DeepSeek-family
+ * `reasoning_content` field nor OpenAI-style prompt-cache keys. Rationale:
+ *
+ *   - path A (`adapter-pi-ai.ts`) has carried the `reasoning_content` defence
+ *     (#4398/#4403) and the explicit prompt-cache markers (#4383) for a while;
+ *     path B — this AI SDK fallback — had neither, so a single transient 429 on
+ *     path A turned into a hard 400 here.
+ *   - The middleware patches the serialised HTTP body, which is the only place
+ *     that is protocol-agnostic: `createOpenAI().languageModel()` speaks the
+ *     **responses** protocol (body key `input`), while the compatible branch
+ *     speaks **chat/completions** (body key `messages`).
+ *   - `fetch` is the only option all three provider factories share
+ *     (`transformRequestBody` exists on `openai-compatible` alone).
+ *
+ * The middleware is fail-open: anything it cannot parse is forwarded untouched,
+ * because path B only runs once we are already in a degraded state.
  */
-declare function createProviderInstance(providerId: string, apiKey: string, baseURL?: string, conversationId?: string): any;
+declare function createProviderInstance(providerId: string, apiKey: string, baseURL?: string, conversationId?: string, cacheRetention?: "none" | "short" | "long", modelId?: string): any;
 /**
  * Test-only re-export of createProviderInstance so that unit tests can verify
  * header injection behavior without booting the full invoke() stack.

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

@@ -1,5 +1,6 @@
 import { BaseComponent, type ComponentConfig } from "../component";
 import { type LLMConfig, type LLMInvokeRequest, type LLMInvokeResult, type ModelLimits } from "./types";
+import type { LLMAdapter } from "./adapter";
 import type { ConfigComponent } from "../../config/config-component";
 import { ContextError } from "../errors";
 /**
@@ -90,6 +91,14 @@ export declare class LLMComponent extends BaseComponent {
     private cachedAdapter?;
     /** The provider name that was used to create the cached adapter */
     private cachedAdapterProvider?;
+    /**
+     * Test-only adapter override (see `__setAdapterForTest`).
+     *
+     * Kept as an instance field rather than a module mock so the override is
+     * scoped to a single LLMComponent instance and cannot leak into other test
+     * files sharing the same Bun process.
+     */
+    private adapterOverride?;
     constructor();
     /**
      * 初始化组件
@@ -164,6 +173,14 @@ export declare class LLMComponent extends BaseComponent {
      * a rebuild on the next invoke().
      */
     private getAdapter;
+    /**
+     * Test-only: inject a fake adapter for this component instance.
+     *
+     * Preferred over `mock.module("./factory")` because it does not leak across
+     * test files in the same Bun process. Call `__setAdapterForTest(undefined)`
+     * to restore normal factory behaviour.
+     */
+    __setAdapterForTest(adapter: LLMAdapter | undefined): void;
     /**
      * P1-3: Invalidate the cached adapter.
      *
@@ -171,6 +188,19 @@ export declare class LLMComponent extends BaseComponent {
      * the adapter to be recreated on the next invoke().
      */
     invalidateAdapterCache(): void;
+    /**
+     * ★ 2026-10-22：**入参/返回值只存摘要**（Task #4479）。
+     *
+     * 改造前本 span 平均 473KB —— 因为 `request.messages`（全量 system prompt +
+     * 对话历史）被原样序列化进 DB attributes，完整模型响应又存了两遍
+     * （`attributes.result` + `result` 列）。
+     *
+     * 现在只存摘要：模型名 / provider / 消息条数 / 总字符数 / 工具数 /
+     * finishReason / output 长度 / usage —— 排障时最常问的问题的答案，
+     * 体积 < 1KB。
+     *
+     * 需要临时全量排查时：`ROY_TRACE_FULL=1` 重启即可恢复全量（不改代码）。
+     */
     invoke(request: LLMInvokeRequest): Promise<LLMInvokeResult>;
     /**
      * Task #2719: 消费 adapter.stream() 返回的事件流，把 pi-ai AssistantMessageEvent
@@ -190,6 +220,14 @@ export declare class LLMComponent extends BaseComponent {
      * 公共收尾逻辑：threshold check + return LLMInvokeResult
      */
     private finalizeOutput;
+    /**
+     * Task #4396: publish the `llm.completed` env event.
+     *
+     * Payload shape must match what `StreamOutputService.handleCompleted()`
+     * reads (`payload.metadata.usage` + `payload.metadata.model`), otherwise the
+     * TUI footer silently degrades to nothing.
+     */
+    private emitCompletedEvent;
     /**
      * 获取 Provider API Key
      */