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

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/llm/reasoning-defense.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Defensive `reasoning_content` injection for DeepSeek-family providers.
+ *
+ * Task #4398. Business trigger (production, 12 occurrences, all
+ * `opencodego / deepseek-v4.1-flash`):
+ *
+ *   [invalid_request_error] The `reasoning_content` in the thinking mode must
+ *   be passed back to the API.
+ *
+ * ── Why roy-agent has to do this itself ────────────────────────────────
+ *
+ * pi-ai *does* know how to patch this, at `openai-completions.js:712-716`:
+ *
+ *   if (compat.requiresReasoningContentOnAssistantMessages &&
+ *       model.reasoning &&                        // ← (B)
+ *       assistantMsg.reasoning_content === undefined) {
+ *     assistantMsg.reasoning_content = "";
+ *   }
+ *
+ * Two independent switches have to be on, and for our failing combo BOTH are
+ * off:
+ *
+ *   (A) `requiresReasoningContentOnAssistantMessages` comes from
+ *       `detectCompat()` (`openai-completions.js:884`):
+ *         const isDeepSeek = provider === "deepseek" || baseUrl.includes("deepseek.com")
+ *       opencodego is `provider: "opencodego"` with
+ *       `baseUrl: "https://opencode.ai/inference/go/v1"` → false.
+ *
+ *   (B) `model.reasoning` comes from the model descriptor. pi-ai's bundled
+ *       registry has no opencodego entries, so roy-agent builds the descriptor
+ *       itself in `resolvePiModel()`, which hardcodes `reasoning: false`.
+ *       The `capabilities.reasoning: true` in config never reaches it.
+ *
+ * So patching compat alone would still be a no-op: (B) short-circuits the AND.
+ * Hence the defence lands on roy-agent's side, via pi-ai's public `onPayload`
+ * hook (supported by all three protocol paths: openai-completions.js:78,
+ * anthropic.js:325, openai-responses.js:64).
+ *
+ * ── The cache constraint (the user's actual worry) ─────────────────────
+ *
+ * Prompt caching is a PREFIX match: the bytes we send for turn N become the
+ * reusable prefix at turn N+1. So the injected value must be perfectly stable
+ * — a constant `""`, appended at a deterministic position, present on *every*
+ * assistant message of every turn. Anything volatile (timestamp, counter,
+ * random id, or "only inject when we happen to think we need it") would change
+ * the prefix between turns and silently destroy the cache.
+ *
+ * That is also why the guard is deliberately NARROW: providers outside the
+ * DeepSeek family never get the field. They either reject unknown fields or
+ * hash assistant messages into their own prefix, so injecting for them would be
+ * a cache regression with zero benefit.
+ */
+/**
+ * Should assistant messages get a `reasoning_content` field for this target?
+ *
+ * True when either:
+ * - the configured provider is the DeepSeek API itself (`deepseek`, `deepseek-cn`, …), or
+ * - the model id names a DeepSeek model, regardless of which gateway fronts it
+ *   (this is the `opencodego + deepseek-v4.1-flash` production case).
+ */
+export declare function shouldInjectReasoningContent(provider: string | undefined, modelId: string | undefined): boolean;
+/** Minimal structural view of a chat message — avoids importing pi-ai types. */
+interface AnyMessage {
+    role?: string;
+    reasoning_content?: string;
+    [key: string]: unknown;
+}
+/**
+ * Add `reasoning_content: ""` to every assistant message that lacks the field.
+ *
+ * Contract:
+ * - only `role === "assistant"` messages are touched;
+ * - existing `reasoning_content` (including a real thinking trace) is preserved;
+ * - the input array and its objects are NOT mutated — a new array is returned;
+ * - idempotent, and the produced bytes are identical across calls.
+ */
+export declare function injectReasoningContent<T extends AnyMessage>(messages: T[]): T[];
+/**
+ * Apply the defence to a raw pi-ai request payload (shape varies by protocol,
+ * so this stays structural and conservative).
+ *
+ * Returns the SAME object reference when nothing needs to change, which makes
+ * "we did zero work for non-DeepSeek providers" observable in tests and keeps
+ * the untouched path allocation-free.
+ */
+export declare function applyReasoningDefense<P extends {
+    messages?: unknown;
+}>(payload: P, target: {
+    provider?: string;
+    modelId?: string;
+}): P;
+/**
+ * Build the `onPayload` hook for pi-ai `complete()` / `stream()`.
+ *
+ * Kept as a factory (rather than passing `applyReasoningDefense` directly) so
+ * the hook closes over the exact provider/model of this call — pi-ai invokes it
+ * with `(payload, model)`, and we deliberately do not trust `model.provider`
+ * alone because the configured provider id is what the gateway routing uses.
+ */
+export declare function createReasoningDefenseHook(target: {
+    provider?: string;
+    modelId?: string;
+}): (payload: any) => any;
+export {};

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

@@ -95,6 +95,32 @@ export interface UsageInfo {
      * See {@link cacheRead} for semantics.
      */
     cacheWrite?: number;
+    /**
+     * Tokens that were NOT served from cache.
+     *
+     * Only DeepSeek-shaped providers report this explicitly
+     * (`prompt_cache_miss_tokens`). For every other provider it stays
+     * `undefined` and callers should derive it from
+     * `promptTokens - cacheRead - cacheWrite` if needed.
+     *
+     * Task #4373: added so the field survives the `llm.ts` usage re-pack.
+     */
+    cacheMiss?: number;
+    /**
+     * Total input tokens the model actually processed, i.e.
+     * `promptTokens + cacheRead + cacheWrite`.
+     *
+     * Why this exists (Task #4373): pi-ai reports `promptTokens` as the
+     * **non-cached remainder** (`input = prompt_tokens - cacheRead - cacheWrite`,
+     * see `pi-ai/dist/providers/openai-completions.js::parseChunkUsage`).
+     * Computing a cache hit rate as `cacheRead / promptTokens` therefore
+     * explodes past 100% on real traffic. This field gives every consumer
+     * (span, REPL, cost monitor) the correct denominator without having to
+     * re-derive the provider semantics.
+     *
+     * `undefined` when the provider reported no cache fields at all.
+     */
+    promptTokensTotal?: number;
 }
 /**
  * LLM Output

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-w7hnjhvx.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-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 {
   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-b599jgyd.js";
 import {
   OTelTracerProvider,
   SpanKind,
@@ -48,14 +61,23 @@ import {
 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/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,7 +10,7 @@ import {
   augmentNpmEnvForPackageRunner,
   getMcpPathPriority,
   resolvePackageRunnerCommand
-} from "../../shared/@ai-setting/roy-agent-core-dwx9hjwx.js";
+} from "../../shared/@ai-setting/roy-agent-core-c6at31ra.js";
 import {
   adaptMcpTool,
   convertInputSchemaToZod,
@@ -18,12 +18,12 @@ import {
 } from "../../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"../../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 {

package/dist/env/memory/index.js

@@ -3,7 +3,7 @@ import {
   MemoryComponent,
   SOURCE_PRIORITY,
   getSourcePriority
-} from "../../shared/@ai-setting/roy-agent-core-ak4dc3kg.js";
+} from "../../shared/@ai-setting/roy-agent-core-gn8f4rhs.js";
 import {
   RecallMemorySchema,
   RecordMemorySchema
@@ -25,12 +25,12 @@ import {
   recallMemory
 } from "../../shared/@ai-setting/roy-agent-core-j5c3chtn.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/plugin/index.js

@@ -1,19 +1,19 @@
 import {
   EventBusNotificationChannel,
   PluginComponent
-} from "../../shared/@ai-setting/roy-agent-core-t37wbysj.js";
+} from "../../shared/@ai-setting/roy-agent-core-5gw6w424.js";
 import {
   normalizeLarkAtMentions
 } from "../../shared/@ai-setting/roy-agent-core-64f22h1g.js";
 import {
   BasePlugin
 } from "../../shared/@ai-setting/roy-agent-core-az13yzmc.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 {
   createLogger,
   init_logger