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

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

@@ -88,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
@@ -282,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

@@ -188,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

package/dist/env/llm/outbound-defense.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview HTTP outbound defence middleware for the AI SDK (path B).
+ *
+ * ── Why this file exists (Task #4457 → #4465) ──────────────────────────
+ *
+ * roy-agent has TWO independent LLM request paths:
+ *
+ *   path A  `adapter-pi-ai.ts`  → pi-ai `stream()` / `complete()`
+ *   path B  `invoke.ts`         → AI SDK `streamText()` / `generateText()`
+ *
+ * path A is the normal route. path B runs when path A fails — see
+ * `llm.ts`: "adapter(pi-ai) failed, falling back to AI SDK invoke".
+ *
+ * Everything defensive was only ever wired into path A:
+ *
+ *   #4398/#4403  `reasoning_content: ""` on assistant messages (via pi-ai's
+ *                `onPayload` hook) — path A only
+ *   #4383        `prompt_cache_key` / `prompt_cache_retention` (via pi-ai's
+ *                `buildPiCacheOptions`) — path A only
+ *
+ * Byte-level packet capture of a production fallback proved the gap:
+ *
+ *   | path                    | assistant msgs | with reasoning_content |
+ *   |-------------------------|----------------|------------------------|
+ *   | A `adapter.stream()`    |            149 |            149 (100%)  |
+ *   | B `invoke()` (fallback) |            149 |              0 (0%)    |
+ *
+ * Same endpoint, same conversation — the only difference was path B. The
+ * request came back `400 [invalid_request_error] The reasoning_content in the
+ * thinking mode must be passed back to the API.`
+ *
+ * The capture also showed path B sending no cache keys at all, so every
+ * fallback paid full input price.
+ *
+ * ── Why a fetch middleware, and not "patch the messages array" ─────────
+ *
+ * The obvious fix is to inject the field into the `ModelMessage[]` we hand the
+ * SDK. That approach is **silently useless** here, for two independent reasons
+ * discovered while localising this task:
+ *
+ *   1. `convertToSDKMessages()` writes cache options under the `openai`
+ *      providerOptions key, but `@ai-sdk/openai-compatible` reads
+ *      `openaiCompatible` / `<providerName>` and validates them against
+ *      `openaiCompatibleLanguageModelChatOptions` — a schema with **no**
+ *      `promptCacheKey` field at all. So the existing path B cache code has
+ *      never emitted anything on the wire. (Confirmed by capture: 0 hits.)
+ *
+ *   2. The wire protocol is not always chat/completions. On
+ *      `openai-responses` the top-level conversation list is `input`, not
+ *      `messages`, so any messages-only patch is a no-op there.
+ *
+ * A `fetch` wrapper sits after all protocol conversion and after providerOptions
+ * validation, so it sees exactly the bytes that go on the wire — and it is the
+ * only option shared by all three provider factories (`createOpenAI`,
+ * `createOpenAICompatible`, `createAnthropic`); `transformRequestBody` exists
+ * on `openai-compatible` only.
+ *
+ * ── Cache-prefix safety (the constraint that shapes every decision here) ──
+ *
+ * Prompt caching is a PREFIX match: the bytes sent at turn N are the reusable
+ * prefix at turn N+1. Therefore:
+ *
+ *   - the injected value is a constant `""`, appended at a deterministic
+ *     position, on *every* assistant message of *every* turn;
+ *   - the field is only added when absent (idempotent, no double-injection);
+ *   - the guard is NARROW: non-DeepSeek providers never get the field, because
+ *     they either reject unknown fields or hash assistant messages into their
+ *     own prefix — injecting would be a pure cache regression.
+ *
+ * Both guarantees are covered by tests in `fallback-path-defense.test.ts`.
+ */
+/** Wire protocols we know how to patch. */
+export type WireProtocol = "openai-chat" | "openai-responses" | "anthropic" | "other";
+export interface OutboundDefenseTarget {
+    /** Configured provider id (may be a gateway, e.g. `opencodego`). */
+    provider?: string;
+    /** Model id actually requested — decides DeepSeek-family membership. */
+    modelId?: string;
+    /** Conversation id; becomes `prompt_cache_key` for OpenAI-family protocols. */
+    sessionId?: string;
+    /**
+     * Cache retention preference, mirroring pi-ai's `cacheRetention`:
+     *   - `"long"`  → `prompt_cache_key` + `prompt_cache_retention: "24h"`
+     *   - `"short"` → `prompt_cache_key` only
+     *   - `"none"`  → neither
+     *
+     * When omitted, OpenAI-family protocols default to `"long"` so path B
+     * matches what path A does through `buildPiCacheOptions()` (which defaults
+     * to `"long"` for `openai-completions`).
+     */
+    cacheRetention?: "none" | "short" | "long";
+    /**
+     * Restricts which patches may be applied. Omitted → auto-detect from the
+     * body shape (permissive; used by unit tests and by callers that already
+     * know the endpoint speaks OpenAI).
+     *
+     * Production passes this explicitly so an Anthropic request can never
+     * receive OpenAI-only fields (`prompt_cache_key`) or a stray
+     * `reasoning_content` that the Messages API would reject.
+     */
+    wireProtocol?: WireProtocol;
+}
+/**
+ * Apply both defences to a parsed request body, returning a NEW object.
+ *
+ * Pure and synchronous, so it can be unit-tested without any HTTP machinery.
+ * Returns the original reference when nothing changes, which keeps the
+ * "untouched for non-DeepSeek providers" guarantee cheap to assert.
+ */
+export declare function applyOutboundDefense(body: Record<string, unknown>, target: OutboundDefenseTarget): Record<string, unknown>;
+/**
+ * Wrap a `fetch` implementation with the outbound defences.
+ *
+ * The wrapper is deliberately fail-open: anything it cannot understand
+ * (non-string body, unparsable JSON, unexpected shape) is forwarded to the
+ * inner fetch **completely unchanged**. A broken defence must never turn a
+ * recoverable LLM call into a hard failure — path B only runs *because* we are
+ * already in a degraded state.
+ *
+ * @param target  provider/model/session of this call
+ * @param inner   the fetch to delegate to (defaults to globalThis.fetch)
+ */
+export declare function createOutboundDefenseFetch(target: OutboundDefenseTarget, inner?: typeof fetch): typeof fetch;
+/**
+ * Map a pi-ai `apiProtocol` (the vocabulary `resolveApiProtocol()` speaks) onto
+ * this module's wire-protocol vocabulary.
+ *
+ * Task #4465 cross-validation (C1): the initial implementation hardcoded the
+ * wire protocol per *provider id*, but path A derives it from the **endpoint**
+ * (`resolveApiProtocol(provider, baseURL)`). The two disagree for real configs —
+ * e.g. the production `minimax` provider points at
+ * `https://api.minimaxi.com/anthropic`, which path A classifies as
+ * `anthropic-messages` while a per-id table says "OpenAI chat". Injecting
+ * OpenAI-only `prompt_cache_key` onto an Anthropic-protocol endpoint would be
+ * wrong (and pointless) there.
+ *
+ * So callers should derive the protocol the same way path A does and hand the
+ * result through this mapper.
+ */
+export declare function wireProtocolFromApiProtocol(apiProtocol: string | undefined): WireProtocol;

package/dist/env/log-trace/decorator.d.ts

@@ -8,15 +8,56 @@
 export interface TracedOptions {
     name?: string;
     recordParams?: boolean;
+    /**
+     * ★ 2026-10-22：**result 是否写进 DB**（默认 **true** = 写）。
+     *
+     * 为什么默认是 true：单个返回值通常并不大，真正把 traces.db 撑到 169GB 的是
+     * **不断累积的入参**（每轮 LLM 请求都带完整 system prompt + 全量历史）。
+     * 所以默认保留 result（不改变既有调用方的数据可见性），瘦身交给
+     * `paramFilter` / `resultFilter`：需要截断的 span 显式声明摘要即可。
+     *
+     * 现在的语义：
+     * - 有 `resultFilter` → 存 filter 产出的摘要（filter 失效时退回本选项裁决）
+     * - `recordResultToDb: true` → 强制存**完整** result（优先于 resultFilter）
+     * - 否则按本选项：`true`（默认）存完整 result / `false` 显式不存
+     *
+     * 「日志里要不要打」由 `logResult` 单独控制，与本选项解耦。
+     */
     recordResult?: boolean;
+    /**
+     * ★ 2026-10-22：**强制把完整 result 写进 DB**，即使 `recordResult: false`。
+     *
+     * 背景：`recordResult` 原本只控制日志，DB 里始终存全量 result，导致
+     * traces.db 膨胀到 169GB。修复后 `recordResult: false` 意味着「不入库」，
+     * 但少数场景确实需要完整返回值（例如把 result 当业务数据读的下游）。
+     * 这些场景用本选项显式声明 —— **默认不存，需要就显式开**。
+     */
+    recordResultToDb?: boolean;
+    /**
+     * ★ 2026-10-22：**日志里是否打印 result**（与「DB 存不存」解耦）。
+     *
+     * 背景：改造前 `recordResult` 同时控制日志与 DB。DB 瘦身时把它改成 false，
+     * 会连带让 app.log 里的 LLM 响应消失 —— DB 省了体积，排障能力也一起没了。
+     *
+     * 语义：不设时跟随 `recordResult`（向后兼容）；
+     * 显式设 `true` 可实现「DB 不存完整 result，但日志照打」。
+     */
+    logResult?: boolean;
     recordError?: boolean;
     log?: boolean;
     maxLogSize?: number;
     paramFilter?: (args: any[], argNames?: string[]) => Record<string, any>;
     /**
-     * NEW: result filter - returns object whose keys are spread as top-level
-     * span attributes. Used to expose named result fields (e.g. diagnostics.length,
-     * cache.hit) for cli-e2e-test field-shape verification.
+     * result filter —— 把返回值压成一份**摘要**。
+     *
+     * 摘要的键会被摊平到 span 的顶层属性（便于 `debug trace` 直接看字段），
+     * ⚠️ **同时它就是 DB 里 `result` 列的内容** —— 也就是说这个 filter 不只是
+     * 「额外加几个属性」，它**替换**了原本要存的完整返回值。
+     *
+     * 想保留完整 result，请显式设 `recordResultToDb: true`（它优先于本 filter）。
+     *
+     * 若 filter 抛异常或没有返回可用对象，会**退回** `recordResult` 的裁决，
+     * 不会静默丢掉调用方明确要求记录的 result。
      */
     resultFilter?: (result: any) => Record<string, any>;
     /**
@@ -78,6 +119,8 @@ export declare function TracedLightweight(options?: {
 export declare function wrapFunction<T extends (...args: any[]) => any>(fn: T, name: string, options?: {
     recordParams?: boolean;
     recordResult?: boolean;
+    recordResultToDb?: boolean;
+    logResult?: boolean;
     recordError?: boolean;
     log?: boolean;
     maxLogSize?: number;

package/dist/env/log-trace/index.d.ts

@@ -12,3 +12,4 @@ export { propagation, serialize, parse, type ExtractedContext, } from "./opentel
 export { injectToEnv, injectToEnvWithContext, injectToEnvFromCarrier, getTraceparentHeader, type EnvCarrier, } from "./opentelemetry/propagation-env";
 export { createLogger, setQuietMode, isQuietMode, setConfigComponent as setLoggerConfigComponent, getLogLevel, getLogLevels, getLogDir, getLogFile, setLogDirOverride, getLogDirOverride, simplifyFilePath, getMaxOutput, } from "./logger";
 export { TracedAs, Traced, TracedLightweight, wrapFunction, type TracedOptions } from "./decorator";
+export { isTraceFullMode, resetTraceFullModeCache, llmInvokeParamFilter, llmInvokeResultFilter, messagesParamFilter, toolExecParamFilter, toolInvokeParamFilter, toolExecResultFilter, envQueryParamFilter, agentRunParamFilter, recordSessionMessagesParamFilter, embedParamFilter, embedResultFilter, } from "./trace-filters";

package/dist/env/log-trace/index.js

@@ -7,19 +7,32 @@ import {
   injectToEnv,
   injectToEnvFromCarrier,
   injectToEnvWithContext
-} from "../../shared/@ai-setting/roy-agent-core-rnwr39b0.js";
+} from "../../shared/@ai-setting/roy-agent-core-tze5596n.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-0kn3zt1t.js";
+import"../../shared/@ai-setting/roy-agent-core-ytd5eztz.js";
+import"../../shared/@ai-setting/roy-agent-core-yphwdm9x.js";
+import"../../shared/@ai-setting/roy-agent-core-m97jn2ra.js";
+import"../../shared/@ai-setting/roy-agent-core-syyw58p9.js";
 import {
   Traced,
   TracedAs,
   TracedLightweight,
+  agentRunParamFilter,
+  embedParamFilter,
+  embedResultFilter,
+  envQueryParamFilter,
+  isTraceFullMode,
+  llmInvokeParamFilter,
+  llmInvokeResultFilter,
+  messagesParamFilter,
+  recordSessionMessagesParamFilter,
+  resetTraceFullModeCache,
+  toolExecParamFilter,
+  toolExecResultFilter,
+  toolInvokeParamFilter,
   wrapFunction
-} from "../../shared/@ai-setting/roy-agent-core-dsevjbck.js";
+} from "../../shared/@ai-setting/roy-agent-core-8p63s836.js";
 import {
   OTelTracerProvider,
   SpanKind,
@@ -41,21 +54,30 @@ import {
   setLogDirOverride,
   setQuietMode,
   simplifyFilePath
-} from "../../shared/@ai-setting/roy-agent-core-8seq65bp.js";
+} from "../../shared/@ai-setting/roy-agent-core-rt115qfc.js";
 import {
   SQLiteSpanStorage
 } from "../../shared/@ai-setting/roy-agent-core-jnszp0jq.js";
 import"../../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";
 export {
   wrapFunction,
+  toolInvokeParamFilter,
+  toolExecResultFilter,
+  toolExecParamFilter,
   simplifyFilePath,
   setQuietMode,
   setConfigComponent as setLoggerConfigComponent,
   setLogDirOverride,
   serialize,
   resetTracerProvider,
+  resetTraceFullModeCache,
+  recordSessionMessagesParamFilter,
   propagation,
   parse,
+  messagesParamFilter,
+  llmInvokeResultFilter,
+  llmInvokeParamFilter,
+  isTraceFullMode,
   isQuietMode,
   injectToEnvWithContext,
   injectToEnvFromCarrier,
@@ -70,7 +92,11 @@ export {
   getLogDir,
   getDefaultSpanDbPath,
   getDefaultLogDir,
+  envQueryParamFilter,
+  embedResultFilter,
+  embedParamFilter,
   createLogger,
+  agentRunParamFilter,
   TracedLightweight,
   TracedAs,
   Traced,

package/dist/env/log-trace/opentelemetry/tracer-provider.d.ts

@@ -102,6 +102,35 @@ export declare class OTelTracerProvider {
     private storage;
     private initialized;
     private globalContext;
+    /**
+     * ★ Task #4486 Phase 3: per-run trace context 作用域（AsyncLocalStorage）。
+     *
+     * 为什么需要：`globalContext` 是进程级单槽。并发多 session 时
+     *   - run B 的 startSpan() 会继承 run A 刚设的 traceId（串 trace）
+     *   - run A 收尾 setGlobalContext(undefined) 会把 run B 的父上下文清掉
+     *
+     * `withGlobalContext(ctx, fn)` 在异步链内覆盖读值（链外仍回落进程级单槽，
+     * 完全向后兼容既有调用方）。
+     *
+     * 用 `{ value }` 包装而不是直接存 SpanContext：需要区分
+     * "链内显式设为 undefined"（屏蔽继承）与 "链内没设置"（回落进程级）。
+     */
+    private globalContextScope;
+    /**
+     * ★ Task #4515 (H1): 进程级 tracer currentContext 表（ALS 作用域外使用）。
+     *
+     * `instanceId → SpanContext`。取代原来 `OTelTracerImpl` 的私有单槽字段。
+     * 作用域外的读写在**同一个 map** 上做，所以既有的"同步链式嵌套"语义
+     * （root → child 自动继承）完全不变。
+     */
+    private tracerContexts;
+    /**
+     * ★ Task #4515 (H1): 当前 ALS 作用域内的 tracer currentContext 表。
+     *
+     * `withGlobalContext()` 为每次 run 建一张**独立的 map**，所以并发 run 的
+     * `startSpan()` / `span.end()` 各改各的槽，互不可见 —— 这是 H1 的根治点。
+     */
+    private tracerContextScope;
     readonly instanceId: string;
     constructor(storage?: SpanStorage, dbPath?: string);
     /**
@@ -115,13 +144,69 @@ export declare class OTelTracerProvider {
      */
     isInitialized(): boolean;
     /**
-     * 获取全局 context（所有 tracer 共享）
+     * 获取当前 trace context。
+     *
+     * ★ Task #4486 Phase 3: 优先读 ALS 作用域（withGlobalContext 设置），
+     * 没有作用域时回落进程级单槽（旧语义）。
      */
     getGlobalContext(): SpanContext | undefined;
     /**
      * 设置全局 context（所有 tracer 共享）
+     *
+     * ⚠️ 并发场景请优先用 `withGlobalContext()` —— 直接设置是进程级、
+     * 会被其他并发 run 观察到，且单方 set(undefined) 会连带清掉别人的父上下文。
      */
     setGlobalContext(context: SpanContext | undefined): void;
+    /**
+     * ★ Task #4486 Phase 3: 在指定 trace context 作用域内执行异步函数。
+     *
+     * - 作用域内 `getGlobalContext()` 返回 `context`（即使传 undefined 也会
+     *   屏蔽进程级单槽，即"本次 run 没有父 trace"）
+     * - 作用域外不受影响，也不影响其他并发 run
+     * - 嵌套调用以内层为准，退出后恢复外层
+     *
+     * @param context 本次 run 的 trace context（可为 undefined = 无父）
+     * @param fn 要执行的异步函数
+     */
+    withGlobalContext<T>(context: SpanContext | undefined, fn: () => Promise<T>): Promise<T>;
+    /**
+     * ★ Task #4515 (H1-c): 在指定 context 的**同步**作用域内执行 `fn`。
+     *
+     * 为什么要这个：`withGlobalContext` 只接受 async 函数，而 `span.end()` 是
+     * 同步调用。如果 end() 在作用域外执行，`handleSpanEnd()` 会把恢复出的父上下文
+     * 写进**进程级**表 —— 于是下一轮 run 的 ALS 播种快照会继承上一轮的 trace，
+     * 表现为"下一轮复用了上一轮的 traceId"。
+     *
+     * 用这个把 end() 包回本 run 的作用域，写入就落在本 run 那张（随后丢弃的）表里。
+     */
+    runInGlobalContextSync<T>(context: SpanContext | undefined, fn: () => T): T;
+    /**
+     * ★ Task #4515 (H1): 读某 tracer 实例的 currentContext。
+     *
+     * 作用域内 → 读该 run 的 map（miss 回落进程级表，兼容作用域外设的上下文）；
+     * 作用域外 → 读进程级表（旧语义）。
+     */
+    getTracerCurrentContext(instanceId: string): SpanContext | undefined;
+    /**
+     * ★ Task #4515 (H1): 写某 tracer 实例的 currentContext。
+     *
+     * 作用域内 → 只写该 run 的 map（并发 run 互不可见）；
+     * 作用域外 → 写进程级表（旧语义）。
+     */
+    setTracerCurrentContext(instanceId: string, context: SpanContext | undefined): void;
+    /**
+     * ★ Task #4519: 清空**所有** tracer 实例的 currentContext（当前作用域内）。
+     *
+     * 为什么需要它、而不是逐个 `getTracer(name).setCurrentContext(undefined)`：
+     * 按名字清只能清掉**已实例化**的那个 tracer。而 `tracerContexts` 表是
+     * `instanceId → context`，此前其它名字的 tracer 若在进程级表里留了父上下文，
+     * 它仍会被继承（交叉复核指出：只清 "roy-tracer" 清不干净）。
+     * 这里直接清整表，保证**任何** tracer 名都不在事件之间串味。
+     *
+     * 作用域内 → 只清本 run 那张 map（不动进程级，并发 run 互不影响）；
+     * 作用域外 → 清进程级表。
+     */
+    clearAllTracerCurrentContexts(): void;
     /**
      * 获取 Tracer
      */

package/dist/env/log-trace/trace-filters.d.ts

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Trace 参数瘦身过滤器（paramFilter / resultFilter 共享工具）
+ *
+ * ## 背景
+ *
+ * `traces.db` 曾膨胀到 169GB / 1800 万 span。根因不是 span 数量多，而是
+ * **单个 span 把全量 messages / tool result 写进了 attributes**：
+ *
+ * | span name                    | 平均 attributes 体积 |
+ * |------------------------------|----------------------|
+ * | `llm.component.invoke`       | 473 KB               |
+ * | `session.extractRecentMessages` | 878 KB           |
+ * | `agent.component.executeTool` | 259 KB               |
+ * | `agent.component.buildAdditionInfo` | 158 KB         |
+ *
+ * 每个 LLM 调用都把「system prompt + 全量对话历史」原样序列化进 DB，
+ * 排障价值极低（DB 里只有数字，看不出内容）而体积代价极高。
+ *
+ * ## 方案：显式白名单 filter
+ *
+ * 用 `paramFilter` / `resultFilter` 把入参/返回值替换成**摘要**：
+ * 条数、长度、模型名 —— 排障时最需要的那几个数字，体积 < 1KB。
+ *
+ * 相比 `recordParams: false`（黑盒式"全丢"），filter 是**显式白名单**：
+ * 读代码就知道存了什么、没存什么；后续要加字段只改一个函数。
+ *
+ * ## 全量模式
+ *
+ * `ROY_TRACE_FULL=1` 时，所有 filter 退化为"原样保留"，用于临时全量排查。
+ * 这样运维时只需重启进程 + 加环境变量，**不必改代码重新构建**。
+ */
+/** 强制刷新全量模式缓存（测试用） */
+export declare function resetTraceFullModeCache(): void;
+/**
+ * 是否处于全量模式（`ROY_TRACE_FULL=1`）。
+ *
+ * 只认 `"1"` / `"true"` / `"yes"`（大小写不敏感），避免 `ROY_TRACE_FULL=0`
+ * 这种"看起来像开了其实是关了"的歧义写法被误判为开启。
+ */
+export declare function isTraceFullMode(): boolean;
+/**
+ * 通用：LLM 调用入参摘要（`llm.component.invoke` / `agent.component.invokeLLM`）。
+ *
+ * 保留的字段都是**排障时最常问的问题**的答案：
+ * - 用的是哪个模型 / provider
+ * - 这次塞了多少条消息、多大（判断是不是上下文爆炸）
+ * - 带了多少个工具
+ */
+export declare function llmInvokeParamFilter(args: any[]): Record<string, any>;
+/**
+ * 通用：LLM 调用返回值摘要。
+ *
+ * 只留 `finishReason` / 输出长度 / 推理长度 / tool call 数 / usage ——
+ * 这几个是判断"这次调用是否正常、有没有被截断、烧了多少 token"的关键数字。
+ *
+ * ⚠️ 真实类型是 `LLMInvokeResult = { output: LLMOutput, ... }`，
+ * `LLMOutput = { content, reasoning?, finishReason, toolCalls?, usage? }`，
+ * **没有 `text` / `parts`**；`AgentLLMOutput` 也是 `content` 形状。
+ * 两种都兼容：`content` 优先。
+ */
+export declare function llmInvokeResultFilter(r: any): Record<string, any>;
+/**
+ * 通用：消息数组入参摘要（`session.extractRecentMessages` 等）。
+ *
+ * @param args[0] 通常是消息数组本身，也可能是 `{ messages: [...] }`
+ */
+export declare function messagesParamFilter(args: any[]): Record<string, any>;
+/**
+ * 通用：工具执行入参摘要（`agent.component.executeTool`）。
+ *
+ * 工具参数可能含大文件内容，所以只留"工具名 + 参数键名列表"，不留参数值。
+ */
+export declare function toolExecParamFilter(args: any[]): Record<string, any>;
+/**
+ * 通用：embed 入参摘要（`llm.adapter.embed` / `llm.adapter.ai_sdk.embed`）。
+ *
+ * embed 的 `texts`/`input` 是大字符串数组，**绝对不能入库**。
+ */
+export declare function embedParamFilter(args: any[]): Record<string, any>;
+/**
+ * 通用：embed 返回值摘要 —— 只留维度数，不留向量本身。
+ */
+export declare function embedResultFilter(r: any): Record<string, any>;
+/**
+ * 工具执行返回值摘要。
+ *
+ * 返回值里最大的两块是 `output`（stdout）和 `metadata.stdout/stderr` ——
+ * 一次 `cat` 一个大文件就能写进几 MB。同样只留长度 + 截断前缀。
+ */
+export declare function toolExecResultFilter(r: any): Record<string, any>;
+/**
+ * 工具执行入参摘要（`tool.bash.execute` 的 command / `tool.component.execute` 的 args）。
+ */
+export declare function toolInvokeParamFilter(args: any[]): Record<string, any>;
+/**
+ * 顶层查询入参摘要（`env.handle_query` / `env.handle_workflow_agent_query`）。
+ *
+ * 入参 `query` 是 `string | ContentPart[]` —— 多模态时是图片/文件的数组，
+ * 可能很大。只留长度与类型，不留内容。
+ */
+/**
+ * 环境入口（`env.handle_query` / `env.handle_workflow_agent_query`）入参摘要。
+ *
+ * ⚠️ **两个调用点的入参形状不同**，不能共用同一套解析：
+ * - `env.handle_query(query, context?)`            → args[0] 是 **query**
+ * - `env.handle_workflow_agent_query(agentName, query, agentComponent, context?)`
+ *                                                    → args[0] 是 **agentName**，args[1] 才是 query
+ *
+ * 早期版本把 args[0] 一律当 agentName，导致 `handle_query` 的
+ * **整条 query 被原样存进 `agentName` 字段** —— 过滤器等于没生效。
+ * 现在按「参数个数 + 形状」区分两种入口。
+ */
+export declare function envQueryParamFilter(args: any[]): Record<string, any>;
+/**
+ * `agent.component.run` 入参摘要。
+ *
+ * 入参是 `(agentName, query, context)` —— `query` 可能是多模态数组
+ * （base64 图片能到 MB 级）。只留长度与条数。
+ */
+export declare function agentRunParamFilter(args: any[]): Record<string, any>;
+/**
+ * `agent.component.recordSessionMessages` 入参摘要。
+ *
+ * ⚠️ 这是**最大的漏网之鱼**：`allMessages` 是**每一轮 ReAct 迭代的全部消息**
+ * （含工具输出），实测单 span ~200 KB / 迭代。必须只留条数与长度。
+ */
+export declare function recordSessionMessagesParamFilter(args: any[]): Record<string, any>;

package/dist/env/mcp/index.js

@@ -10,21 +10,21 @@ import {
   augmentNpmEnvForPackageRunner,
   getMcpPathPriority,
   resolvePackageRunnerCommand
-} from "../../shared/@ai-setting/roy-agent-core-dwx9hjwx.js";
+} from "../../shared/@ai-setting/roy-agent-core-84xtww7d.js";
 import {
   adaptMcpTool,
   convertInputSchemaToZod,
   createMcpToolsDescription
-} from "../../shared/@ai-setting/roy-agent-core-8t7wny6v.js";
+} from "../../shared/@ai-setting/roy-agent-core-m68z3pw1.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-8seq65bp.js";
+import"../../shared/@ai-setting/roy-agent-core-0kn3zt1t.js";
+import"../../shared/@ai-setting/roy-agent-core-ytd5eztz.js";
+import"../../shared/@ai-setting/roy-agent-core-yphwdm9x.js";
+import"../../shared/@ai-setting/roy-agent-core-m97jn2ra.js";
+import"../../shared/@ai-setting/roy-agent-core-syyw58p9.js";
+import"../../shared/@ai-setting/roy-agent-core-8p63s836.js";
+import"../../shared/@ai-setting/roy-agent-core-rt115qfc.js";
 import"../../shared/@ai-setting/roy-agent-core-jnszp0jq.js";
 import {
   ensureFallbackNpmPrefix,

package/dist/env/mcp/tool/index.js

@@ -2,8 +2,8 @@ import {
   adaptMcpTool,
   convertInputSchemaToZod,
   createMcpToolsDescription
-} from "../../../shared/@ai-setting/roy-agent-core-8t7wny6v.js";
-import"../../../shared/@ai-setting/roy-agent-core-8seq65bp.js";
+} from "../../../shared/@ai-setting/roy-agent-core-m68z3pw1.js";
+import"../../../shared/@ai-setting/roy-agent-core-rt115qfc.js";
 import"../../../shared/@ai-setting/roy-agent-core-jnszp0jq.js";
 import"../../../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";
 export {