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

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

@@ -0,0 +1,238 @@
+import { BaseComponent, type ComponentConfig } from "../component";
+import { type LLMConfig, type LLMInvokeRequest, type LLMInvokeResult, type ModelLimits } from "./types";
+import type { ConfigComponent } from "../../config/config-component";
+import { ContextError } from "../errors";
+/**
+ * Resolve fallback provider config by reading `~/.roy-agent/auth.json` and
+ * `~/.roy-agent/config.jsonc` directly (Task #2888 follow-up).
+ *
+ * Why this exists:
+ *   When PiAiAdapter.stream() fails (e.g. finishReason=error, MIME 400, etc.),
+ *   LLMComponent.invoke() falls back to AI SDK invoke(). The fallback must
+ *   NOT reuse ctx.invokeConfig blindly — for some custom providers (e.g.
+ *   minimax) that combination produces the wrong URL and HTTP 404. Reading
+ *   config-driven per-provider baseURL/apiKey from auth.json is the
+ *   user-controlled source of truth.
+ *
+ * Returned shape is just enough for the fallback path:
+ *   - baseURL: from auth.json.providers.{name}.baseURL
+ *   - apiKey:  from auth.json.providers.{name}.apiKey
+ *   - providerType: from config.jsonc.llm.providers.{name}.provider
+ *                   (defaults to "openai-compatible" if missing)
+ *
+ * @throws  Error when auth.json has no entry for `providerId`
+ */
+export interface FallbackProviderConfig {
+    baseURL: string;
+    apiKey: string;
+    providerType: string;
+}
+export declare function resolveFallbackProviderConfig(providerId: string): Promise<FallbackProviderConfig>;
+/**
+ * LLMComponent 配置（通过 options.config 传递）
+ *
+ * 配置加载顺序（优先级从低到高）：
+ * 1. File - 配置文件（通过 configPath 指定）
+ * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+ * 3. Object - 直接传入的 config 对象（最高优先级）
+ *
+ * 环境变量转换规则：
+ * - 驼峰命名会被转换为下划线分隔的大写形式
+ * - 例如: "llm.defaultModel" + prefix "LLM" -> "LLM_LLM_DEFAULT_MODEL"
+ */
+export interface LLMComponentOptions {
+    /** ConfigComponent 实例（必填） */
+    configComponent: ConfigComponent;
+    /** 配置文件相对路径（可选，基于 XDG_DATA_HOME） */
+    configPath?: string;
+    /** 环境变量前缀（可选，默认 "LLM"） */
+    envPrefix?: string;
+    /** 直接传入的配置对象（可选，优先级最高） */
+    config?: Partial<LLMConfig>;
+}
+/**
+ * LLMComponent
+ * 管理 LLM 调用，使用 AI SDK 进行实际调用
+ *
+ * 配置通过 ConfigComponent 实时获取，支持配置热更新
+ *
+ * @example
+ * // 通过 ConfigComponent 加载配置
+ * const configComponent = new ConfigComponent();
+ * configComponent.setXdgDataHome(__dirname);
+ *
+ * const llmComponent = new LLMComponent();
+ * await llmComponent.init({
+ *   env,  // Environment 实例（必填）
+ *   options: {
+ *     configComponent,  // ConfigComponent 实例
+ *     configPath: "config.jsonc"  // 配置文件路径
+ *   }
+ * });
+ *
+ * // 配置更新后，下次调用会自动获取最新配置
+ * configComponent.set("llm.temperature", 0.5);
+ */
+export declare class LLMComponent extends BaseComponent {
+    readonly name = "llm";
+    readonly version = "2.0.0";
+    private configComponent?;
+    /** 配置变更 watcher 清理函数 */
+    private configWatcher?;
+    /**
+     * P1-3: Cached LLM adapter instance.
+     *
+     * Instead of calling createLLMAdapter() on every invoke(), we cache the
+     * adapter here. The adapter is created lazily on first use and rebuilt
+     * only when the provider environment variable changes (via
+     * invalidateAdapterCache()).
+     */
+    private cachedAdapter?;
+    /** The provider name that was used to create the cached adapter */
+    private cachedAdapterProvider?;
+    constructor();
+    /**
+     * 初始化组件
+     *
+     * 配置加载优先级（从高到低）：
+     * 1. Object - 直接传入的 config 对象
+     * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+     * 3. File - 配置文件（通过 configPath 指定）
+     */
+    init(config: ComponentConfig): Promise<void>;
+    /**
+     * 注册配置到 ConfigComponent
+     *
+     * 配置加载顺序（优先级从低到高）：
+     * 1. FileSource - 从配置文件加载（最低）
+     * 2. EnvSource - 从环境变量加载（中等）
+     * 3. MemorySource - 直接配置对象（最高）
+     */
+    private registerConfig;
+    /**
+     * 将配置对象展平为点号路径
+     *
+     * @example
+     * flattenConfig({ providers: { openai: { apiKey: "xxx" } } })
+     * -> { "llm.providers.openai.apiKey": "xxx" }
+     */
+    private flattenConfig;
+    /**
+     * 注册配置热更新监听
+     */
+    private registerConfigWatcher;
+    /**
+     * 处理配置变更（支持热更新）
+     */
+    protected onConfigChange(event: {
+        key: string;
+        oldValue?: unknown;
+        newValue?: unknown;
+    }): void;
+    /**
+     * 启动组件
+     */
+    onStart(): Promise<void>;
+    /**
+     * 停止组件
+     */
+    onStop(): Promise<void>;
+    /**
+     * 从配置源获取配置值
+     * 优先从 ConfigComponent 获取（支持热更新），否则返回默认值
+     */
+    private getLLMConfig;
+    /**
+     * 解析请求，构建调用上下文（invoke 和 invokeStream 共享）
+     */
+    private resolveRequest;
+    /**
+     * 调用 LLM
+     *
+     * 路由策略（Task 6 实现）：
+     * - 读取 ROY_LLM_PROVIDER 环境变量（默认 pi-ai）
+     * - 通过 createLLMAdapter().chat() 统一接入
+     * - 若 PiAiAdapter 失败（如 model 不支持），保留 fallback 路径
+     *
+     * 流式事件通过 env.pushEnvEvent() 发布
+     */
+    /**
+     * P1-3: Get or create the cached LLM adapter.
+     *
+     * The adapter is created once and cached. If the ROY_LLM_PROVIDER
+     * environment variable changes, call invalidateAdapterCache() to force
+     * a rebuild on the next invoke().
+     */
+    private getAdapter;
+    /**
+     * P1-3: Invalidate the cached adapter.
+     *
+     * Call this when the LLM provider environment variable changes to force
+     * the adapter to be recreated on the next invoke().
+     */
+    invalidateAdapterCache(): void;
+    invoke(request: LLMInvokeRequest): Promise<LLMInvokeResult>;
+    /**
+     * Task #2719: 消费 adapter.stream() 返回的事件流，把 pi-ai AssistantMessageEvent
+     * 转成 llm.text / llm.reasoning env 事件（这样 Ink interactive 可以逐字渲染），
+     * 然后调用 streamHandle.result() 拿到最终 ChatResponse。
+     *
+     * 处理的事件类型（pi-ai AssistantMessageEvent）：
+     * - text_delta → llm.text (delta + 累计 content)
+     * - thinking_delta → llm.reasoning (delta + 累计 content)
+     * - 其他事件（start/text_start/text_end/thinking_start/thinking_end/toolcall_xxx/done/error）跳过
+     *
+     * AiSdkAdapter.stream() 会 yield 单个完整 output 对象（不包含 type 字段），
+     * 不属于以上任意类型，所以不会被错误识别为流式事件。
+     */
+    private consumeStreamAndGetResult;
+    /**
+     * 公共收尾逻辑：threshold check + return LLMInvokeResult
+     */
+    private finalizeOutput;
+    /**
+     * 获取 Provider API Key
+     */
+    private getApiKey;
+    /**
+     * 获取 Provider
+     */
+    getProvider(id: string): import("./types").ProviderConfig;
+    /**
+     * 列出所有 Provider
+     */
+    listProviders(): string[];
+    /**
+     * 获取模型的限制配置
+     *
+     * @param providerId - Provider ID
+     * @param modelId - 模型 ID（可选，默认使用 provider 的 defaultModel）
+     * @returns 模型限制配置，如果没有配置则返回 undefined
+     */
+    getModelLimits(providerId: string, modelId?: string): ModelLimits | undefined;
+    /**
+     * 获取上下文窗口阈值配置
+     *
+     * @param providerId - Provider ID
+     * @param modelId - 模型 ID
+     * @returns 包含 contextWindow 和 thresholdRatio 的对象
+     */
+    getContextThresholdConfig(providerId: string, modelId?: string): {
+        contextWindow: number;
+        thresholdRatio: number;
+    };
+    /**
+     * 检测上下文阈值是否超过
+     *
+     * @param usage - LLM 使用量信息
+     * @param providerId - Provider ID
+     * @param modelId - 模型 ID
+     * @param sessionId - Session ID（用于错误信息）
+     * @returns 如果超过阈值，返回 ContextError；否则返回 undefined
+     */
+    checkContextThreshold(usage: {
+        totalTokens: number;
+        promptTokens?: number;
+        completionTokens?: number;
+    } | undefined, providerId: string, modelId: string | undefined, sessionId?: string): ContextError | undefined;
+}

package/dist/env/llm/opencode-session.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview OpenCode Go provider helpers.
+ *
+ * The OpenCode Go inference endpoint (`https://opencode.ai/inference/go/v1`)
+ * requires a stable `x-opencode-session` header per conversation; without it the
+ * server responds `400 MissingSessionID` and the request cannot be routed:
+ *   https://opencode.ai/docs/go/#how-it-works
+ *
+ * This module is the single source of truth for:
+ *   1. detecting the OpenCode Go provider id, and
+ *   2. generating / memoizing a stable session id per conversation.
+ *
+ * Why it lives here instead of inside `invoke.ts`:
+ *   roy-agent has TWO LLM transports that both hit the same endpoint —
+ *     - `PiAiAdapter`  (default path, `ROY_LLM_PROVIDER=pi-ai`)
+ *     - `invoke()` in `invoke.ts` (AI SDK fallback, `ROY_LLM_PROVIDER=ai-sdk`)
+ *   The header injection must be shared so neither path silently regresses.
+ *   Historically only the AI SDK path injected it, so the default pi-ai path
+ *   always failed with `MissingSessionID` and relied on the fallback.
+ *
+ * Provider id normalization:
+ *   Users have registered the provider under several spellings across time
+ *   (`opencode`, `opencode-go`, `opencodego`; see Task #4168 / #4170 / #4173).
+ *   We normalize case and strip `-`/`_` so all of them match. The Feishu
+ *   channel's chat-keyed session ids (`oc_...`) are irrelevant here: the header
+ *   value is always a freshly generated `ses_...` id, so any conversation id
+ *   (including `oc_...`) works as the cache key.
+ */
+/**
+ * Generate an OpenCode-compatible `x-opencode-session` id.
+ *
+ * Official client format (sst/opencode source analysis, Task #4165):
+ *   `ses_<12 hex timestamp><14 base62 random>` = 30 chars
+ *
+ * We do not enforce the exact 30-char length (the server only validates the
+ * `ses_` prefix and a minimum length), but we keep the same shape so the output
+ * is easy to recognize alongside the official client.
+ *
+ * @param nowMs - injectable clock (for tests)
+ */
+export declare function generateOpencodeSessionId(nowMs?: number): string;
+/**
+ * True when `providerId` refers to the OpenCode Go provider.
+ *
+ * Recognizes `opencode`, `opencode-go`, `opencode_go` and `opencodego`
+ * (case-insensitive). Unrelated providers (e.g. `deepseek`, `openai`) return
+ * false so we never send the header to endpoints that don't understand it.
+ */
+export declare function isOpencodeProvider(providerId: string | undefined | null): boolean;
+/**
+ * True when `baseURL` points at the OpenCode Go inference endpoint.
+ *
+ * Id-based detection misses the case where a user points some other provider
+ * name at the OpenCode endpoint; endpoint detection closes that gap. Only the
+ * official host is matched so unrelated gateways are unaffected.
+ */
+export declare function isOpencodeEndpoint(baseURL: string | undefined | null): boolean;
+/**
+ * Get (or create) the stable OpenCode session id for a conversation.
+ *
+ * `x-opencode-session` must be STABLE for the lifetime of a conversation
+ * (the server uses it for routing/caching, see #4168). The header is injected
+ * once per LLM turn, so we memoize the generated id per conversation key.
+ *
+ * - `conversationId` undefined → return an ephemeral id (no stable key to
+ *   cache under, better than poisoning a shared entry).
+ * - The cache is a bounded FIFO so long-lived processes cannot grow it forever.
+ */
+export declare function getOrCreateOpencodeSessionId(conversationId: string | undefined, nowMs?: number): string;
+/**
+ * Build the request headers for a provider.
+ *
+ * Returns `{ "x-opencode-session": "ses_..." }` for OpenCode Go providers and
+ * an empty object for everyone else. Match is by provider id OR endpoint, so it
+ * keeps working if the provider is registered under a different name.
+ */
+export declare function buildOpencodeHeaders(providerId: string | undefined | null, conversationId?: string, baseURL?: string): Record<string, string>;
+/** Test-only: reset the conversation → session id cache between cases. */
+export declare function __clearOpencodeSessionIdCache(): void;

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/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;
+}