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

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

@@ -0,0 +1,40 @@
+import type { LLMConfig, LLMProvider, ProviderConfig } from "./types";
+/**
+ * Provider 管理器
+ * 负责创建和管理 LLM Provider 实例
+ */
+export declare class ProviderManager {
+    private providers;
+    /**
+     * 从配置初始化所有 Provider
+     */
+    initialize(config: LLMConfig): Promise<void>;
+    /**
+     * 获取 Provider
+     */
+    getProvider(id: string): LLMProvider | undefined;
+    /**
+     * 列出所有 Provider
+     */
+    listProviders(): LLMProvider[];
+    /**
+     * 解析 Provider 配置中的环境变量
+     */
+    resolveProviderConfig(config: ProviderConfig): Promise<ProviderConfig>;
+    /**
+     * 解析环境变量
+     * 支持 ${VAR} 格式
+     */
+    resolveEnvVar(value: string): Promise<string>;
+    /**
+     * 创建 Provider 实例
+     * 注意：实际创建需要根据 Provider 类型调用对应的 AI SDK
+     * 这里返回占位实现，真正的 Provider 创建需要 AI SDK 依赖
+     */
+    private createProvider;
+    /**
+     * 根据类型创建实际的 Provider 实例
+     * 需要外部传入 AI SDK 的 createProvider
+     */
+    createAIProvider(id: string, config: ProviderConfig, createFn: (apiKey: string, baseURL?: string) => unknown): LLMProvider;
+}

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/tool-args-parser.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Tool call arguments parser - handles double-stringified JSON.
+ *
+ * LLMs sometimes double-stringify JSON arguments (a JSON string containing
+ * another JSON string). This module provides a safe parser that recursively
+ * attempts to parse until a real object is obtained, without leaking internal
+ * mechanisms like `_raw` into the conversation history.
+ *
+ * Features:
+ * - Recursive parsing for double/multi-stringified JSON
+ * - Debug logging when recursion is detected (alerts developers to LLM anomalies)
+ * - Maximum recursion depth protection (default: 5) to prevent infinite loops
+ */
+/**
+ * 尝试把「文本工具调用标记」形式的参数抢救成 JSON 对象
+ *
+ * 输入形如：`<arg_key>command</arg_key><arg_value>ls -la</arg_value>`
+ * 或散落在一段乱码 JSON 里的若干组标记。
+ *
+ * @returns 抢救成功返回对象；失败返回 undefined
+ */
+export declare function salvageTextualToolArgs(raw: string): Record<string, unknown> | undefined;
+/** 剥掉文本工具调用标记（用于把"值里混进 marker"的脏 JSON 尽量救回来） */
+export declare function stripTextualToolArgsMarkers(raw: string): string;
+/** 参数解析结果（严格模式） */
+export interface StrictToolArgsResult {
+    ok: boolean;
+    args: Record<string, unknown>;
+    /** 失败原因（ok=false 时给人/模型看） */
+    error?: string;
+    /** 是否经过抢救（marker 剥离 / 文本标记重建） */
+    salvaged?: boolean;
+}
+/**
+ * 严格解析 tool 参数（Task #4231）
+ *
+ * 与 `safeParseToolArgs` 的差别：
+ * - 失败时**不返回空对象**，而是 `{ok:false, error}` —— 调用方必须把错误回给模型，
+ *   不能拿 `{}` 去执行工具（否则会执行乱码命令 / 默认参数造成误操作）。
+ * - 会先尝试抢救上游退化格式（GLM 文本工具调用标记）。
+ */
+export declare function parseToolArgsStrict(args: unknown): StrictToolArgsResult;
+/**
+ * 递归清洗参数值里混入的上游文本工具调用标记（Task #4231）
+ *
+ * 只动字符串值，不改变结构；marker 被削掉后若变成空串则保留空串（不删 key，
+ * 避免工具因缺字段报"缺参数"）。
+ */
+export declare function sanitizeArgValues(args: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Safely parse tool call arguments, handling double-stringified JSON.
+ *
+ * LLMs sometimes double-stringify JSON arguments (a JSON string containing
+ * another JSON string). This function recursively attempts to parse until
+ * a real object is obtained.
+ *
+ * @param args - The arguments value (string, object, or double-stringified string)
+ * @param depth - Current recursion depth (internal use, default 0)
+ * @returns Parsed object, or empty object if parsing fails entirely
+ *
+ * @example
+ * // Normal object - returned as-is
+ * safeParseToolArgs({ key: "value" }) // => { key: "value" }
+ *
+ * @example
+ * // Normal JSON string - parsed
+ * safeParseToolArgs('{"key": "value"}') // => { key: "value" }
+ *
+ * @example
+ * // Double-stringified JSON - recursively parsed
+ * safeParseToolArgs('"{\\"key\\": \\"value\\"}"') // => { key: "value" }
+ *
+ * @example
+ * // Invalid JSON - returns empty object (no _raw leak)
+ * safeParseToolArgs("{invalid}") // => {}
+ */
+export declare function safeParseToolArgs(args: unknown, depth?: number): Record<string, unknown>;

package/dist/env/llm/tool-schema.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Tool parameters → JSON Schema（**消除悬空 $ref**）Task #4231
+ *
+ * ## 背景（真实线上故障，2026-10-15）
+ *
+ * 切到 `opencodego`（openai-compatible）provider 后，sub-agent 直接失败：
+ *
+ * ```
+ * Upstream request failed: [invalid_request_error]
+ * Invalid schema for function 'task_operation_create':
+ * Pointer '/definitions/zod/properties/milestone_type' does not exist
+ * ```
+ *
+ * 根因：`zod-to-json-schema` 用 `zodToJsonSchema(schema, "zod")` 会把 schema 包成
+ *
+ * ```json
+ * { "$ref": "#/definitions/zod", "definitions": { "zod": { ... } } }
+ * ```
+ *
+ * 而各处的"解包"逻辑只把 `definitions.zod` 提出来当顶层 schema，**丢掉了
+ * `definitions`**，但 `definitions.zod.properties` 里可能还有**指向 definitions 的
+ * `$ref`**（同一 Zod 实例被复用时，例如 `milestone_type` 与 `action_type` 共用
+ * 同一个 `z.enum(...)` 实例 → `action_type: {"$ref": "#/definitions/zod/properties/milestone_type"}`）。
+ *
+ * 解包后这些 `$ref` 就成了悬空指针：
+ * - 宽松的 provider（Anthropic / 部分网关）容忍 → 一直没暴露；
+ * - **strict 校验的 OpenAI 兼容网关（opencodego）直接 400**。
+ *
+ * ## 修法
+ *
+ * 统一走 `toolParametersToJsonSchema()`：
+ * 1. Zod → JSON Schema（带 name 也不怕）
+ * 2. **就地把所有 `$ref` 展开（dereference）**，支持
+ *    `#/definitions/<name>`、`#/definitions/<name>/properties/<p>`、
+ *    `#/$defs/...` 等指针，带环保护
+ * 3. 丢掉 `definitions` / `$defs` / `$schema`，保证顶层是
+ *    `{ type: "object", properties: {...} }`
+ *
+ * 换 provider / 换 SDK 都不会再因为 schema 指针炸掉。
+ */
+/** 判断是否是 Zod schema（zod v3/v4 都有 _def） */
+export declare function isZodSchema(obj: unknown): boolean;
+/**
+ * 深度扫描：schema 里是否还有 `$ref`（测试/自检用）
+ *
+ * @returns 找到的 ref 列表（空数组 = 干净）
+ */
+export declare function findDanglingRefs(schema: unknown): string[];
+/**
+ * 把 tool 的 `parameters` 规范化成可以直接发给 provider 的 JSON Schema
+ *
+ * @param parameters Zod schema 或已经是 JSON Schema 的对象
+ */
+export declare function toolParametersToJsonSchema(parameters: unknown): Record<string, unknown>;

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

@@ -0,0 +1,57 @@
+import type { LLMMessage, ToolInfo, ToolResult } from "./types";
+/**
+ * LLM 消息转换工具
+ */
+export declare class LLMTransform {
+    /**
+     * 标准化消息格式
+     * 根据不同 Provider 调整消息格式
+     */
+    normalizeMessages(messages: LLMMessage[], providerType: string): LLMMessage[];
+    /**
+     * 标准化为 OpenAI 格式
+     */
+    private normalizeForOpenAI;
+    /**
+     * 标准化为 Anthropic 格式
+     */
+    private normalizeForAnthropic;
+    /**
+     * 从 ToolInfo 提取 JSON Schema
+     */
+    extractToolSchema(tool: ToolInfo): {
+        name: string;
+        description?: string;
+        parameters: Record<string, unknown>;
+    };
+    /**
+     * 将 Zod Schema 转换为 JSON Schema
+     * 兼容 Zod v3 和 v4
+     */
+    zodToJsonSchema(schema: any): Record<string, unknown>;
+    /**
+     * 提取 Zod Schema 的结构
+     * 兼容 Zod v3 和 v4
+     *
+     * Zod v3: schema._def.typeName === "ZodObject"
+     * Zod v4: schema._def.type === "object"
+     */
+    private extractZodSchema;
+    /**
+     * 格式化工具结果
+     */
+    formatToolResult(result: ToolResult): {
+        role: "tool";
+        tool_call_id: string;
+        content: string;
+        isError?: boolean;
+    };
+    /**
+     * 解析工具参数
+     */
+    parseToolArguments(args: string): Record<string, unknown>;
+    /**
+     * 序列化工具参数为 JSON 字符串
+     */
+    serializeToolArguments(args: Record<string, unknown>): string;
+}