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

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

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview LLM Adapter 抽象接口。
+ *
+ * roy-agent 的 LLM 接入点统一通过 LLMAdapter；
+ * 当前实现：
+ *   - PiAiAdapter    — 包装 @earendil-works/pi-ai（默认路径）
+ *   - AiSdkAdapter   — 包装 Vercel AI SDK（fallback 路径）
+ *
+ * 通过 {@link createLLMAdapter} 选择，由环境变量 `ROY_LLM_PROVIDER` 控制。
+ */
+import type { LLMMessage, ToolInfo, UsageInfo } from "./types";
+/** Adapter 名称（联合类型 + 运行时数组） */
+export type AdapterName = "pi-ai" | "ai-sdk";
+/** 运行时可用的 adapter 列表 */
+export declare const ADAPTER_NAMES: readonly AdapterName[];
+/** Provider 解析结果 */
+export interface ResolvedProvider {
+    api: string;
+    provider: string;
+    modelId: string;
+    contextLimit: number;
+    maxTokensLimit: number;
+}
+/** Chat 请求 */
+export interface ChatRequest {
+    provider: string;
+    modelId: string;
+    messages: LLMMessage[];
+    tools?: ToolInfo[];
+    systemPrompt?: string;
+    temperature?: number;
+    maxTokens?: number;
+    apiKey: string;
+    baseURL?: string;
+    signal?: AbortSignal;
+    /**
+     * Conversation / session id (e.g. roy-agent session id, or the Feishu
+     * chat-keyed session id `oc_...`). Used by providers that need a stable
+     * per-conversation identifier — notably OpenCode Go, which requires a stable
+     * `x-opencode-session` header (see opencode-session.ts).
+     */
+    sessionId?: string;
+}
+/** Chat 响应（统一形状） */
+export interface ChatResponse {
+    text: string;
+    finishReason: "stop" | "length" | "toolUse" | "error" | "aborted";
+    toolCalls?: Array<{
+        id: string;
+        name: string;
+        arguments: string;
+    }>;
+    usage: UsageInfo;
+    raw?: unknown;
+}
+/** Stream handle：暴露异步事件流 + 最终结果 */
+export interface StreamHandle {
+    events: AsyncIterable<unknown>;
+    result: () => Promise<ChatResponse>;
+}
+/** LLM Adapter 接口（3 个核心方法） */
+export interface EmbedRequest {
+    provider: string;
+    modelId: string;
+    input: string | string[];
+    apiKey: string;
+    baseURL?: string;
+    signal?: AbortSignal;
+}
+export interface EmbedResponse {
+    embeddings: number[][];
+    usage: UsageInfo;
+}
+export interface LLMAdapter {
+    readonly name: AdapterName;
+    chat(req: ChatRequest): Promise<ChatResponse>;
+    stream(req: ChatRequest): Promise<StreamHandle>;
+    resolveProvider(provider: string, modelId: string): Promise<ResolvedProvider>;
+    embed(req: EmbedRequest): Promise<EmbedResponse>;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview LLM Adapter 工厂
+ *
+ * 读取 ROY_LLM_PROVIDER 环境变量选择 adapter：
+ *   - "pi-ai"   → PiAiAdapter（默认）
+ *   - "ai-sdk"  → AiSdkAdapter（fallback）
+ *
+ * 通过 setLLMProvider() 可在运行时覆盖（用于测试）。
+ */
+import type { LLMAdapter, AdapterName } from "./adapter";
+export declare function setLLMProvider(name: AdapterName | undefined): void;
+export declare function getLLMProviderOverride(): AdapterName | undefined;
+export declare const createLLMAdapter: () => LLMAdapter;

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

@@ -0,0 +1,150 @@
+import type { LLMInvokeRequest, LLMInvokeResult, StreamEvent } from "./types";
+/**
+ * LLM Hook 类型（兼容旧接口）
+ */
+export type LLMHookType = "before-invoke" | "after-invoke" | "stream";
+/**
+ * LLM Hook 上下文
+ */
+export interface LLMHookContext {
+    /** 请求 */
+    request: LLMInvokeRequest;
+    /** Provider ID */
+    providerId: string;
+    /** 模型名称 */
+    model: string;
+    /** 元数据 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Before Invoke Hook
+ * 在 LLM 调用之前执行，可以修改请求
+ */
+export type LLMBeforeInvokeHook = (context: LLMHookContext) => Promise<void>;
+/**
+ * After Invoke Hook
+ * 在 LLM 调用之后执行，可以处理结果
+ */
+export type LLMAfterInvokeHook = (context: LLMHookContext, result: LLMInvokeResult) => Promise<void>;
+/**
+ * Stream Hook
+ * 在流式调用时处理每个事件
+ */
+export type LLMStreamHook = (context: LLMHookContext, event: StreamEvent) => Promise<void>;
+/**
+ * Hook 注册项
+ */
+export interface LLMHookRegistration {
+    /** Hook 类型 */
+    type: LLMHookType;
+    /** Hook 名称（可选，用于标识） */
+    name?: string;
+    /** Before Invoke Hook */
+    beforeInvoke?: LLMBeforeInvokeHook;
+    /** After Invoke Hook */
+    afterInvoke?: LLMAfterInvokeHook;
+    /** Stream Hook */
+    stream?: LLMStreamHook;
+}
+/**
+ * LLMHookManager
+ *
+ * 代理到 globalHookManager 的 LLM Hook 管理器
+ *
+ * @deprecated 请直接使用 globalHookManager.register() 注册 hooks
+ */
+export declare class LLMHookManager {
+    private registrations;
+    /**
+     * 注册 Hook
+     */
+    register(type: LLMHookType, handler: LLMBeforeInvokeHook | LLMAfterInvokeHook | LLMStreamHook, name?: string): void;
+    /**
+     * 注册单个 registration 到 globalHookManager
+     */
+    private registerToGlobal;
+    /**
+     * 取消注册 Hook
+     */
+    unregister(hook: LLMBeforeInvokeHook | LLMAfterInvokeHook | LLMStreamHook): void;
+    /**
+     * 从 globalHookManager 取消注册
+     */
+    private unregisterFromGlobal;
+    /**
+     * 按名称取消注册 Hook
+     */
+    unregisterByName(name: string): void;
+    /**
+     * 按类型取消注册所有 Hook
+     */
+    unregisterByType(type: LLMHookType): void;
+    /**
+     * 清空所有 Hook
+     */
+    clear(): void;
+    /**
+     * 获取所有 Hook
+     */
+    getHooks(): LLMHookRegistration[];
+    /**
+     * 按类型获取 Hook
+     */
+    getHooksByType(type: LLMHookType): LLMHookRegistration[];
+}
+/**
+ * LLMHooks
+ *
+ * 兼容旧接口，内部委托给 globalHookManager
+ *
+ * @deprecated 请直接使用 globalHookManager
+ */
+export declare class LLMHooks {
+    private hookManager;
+    /**
+     * 注册 Hook
+     */
+    register(type: LLMHookType, handler: LLMBeforeInvokeHook | LLMAfterInvokeHook | LLMStreamHook, name?: string): void;
+    /**
+     * 取消注册 Hook
+     */
+    unregister(hook: LLMBeforeInvokeHook | LLMAfterInvokeHook | LLMStreamHook): void;
+    /**
+     * 按名称取消注册 Hook
+     */
+    unregisterByName(name: string): void;
+    /**
+     * 按类型取消注册所有 Hook
+     */
+    unregisterByType(type: LLMHookType): void;
+    /**
+     * 清空所有 Hook
+     */
+    clear(): void;
+    /**
+     * 获取所有 Hook
+     */
+    getHooks(): LLMHookRegistration[];
+    /**
+     * 按类型获取 Hook
+     */
+    getHooksByType(type: LLMHookType): LLMHookRegistration[];
+    /**
+     * 执行 Before Invoke Hooks
+     *
+     * @deprecated 请使用 globalHookManager.execute(LLMHookPoints.BEFORE_INVOKE, ...)
+     */
+    executeBeforeInvoke(context: LLMHookContext): Promise<void>;
+    /**
+     * 执行 After Invoke Hooks
+     *
+     * @deprecated 请使用 globalHookManager.execute(LLMHookPoints.AFTER_INVOKE, ...)
+     */
+    executeAfterInvoke(context: LLMHookContext, result: LLMInvokeResult): Promise<void>;
+    /**
+     * 执行 Stream Hooks
+     *
+     * @deprecated 请使用 globalHookManager.execute(LLMHookPoints.ON_STREAM, ...)
+     */
+    executeStream(context: LLMHookContext, event: StreamEvent): Promise<void>;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * LLM Component
+ * 提供 LLM 调用能力
+ */
+export { type LLMAdapter, type AdapterName, type ChatRequest, type ChatResponse, type StreamHandle, type ResolvedProvider, ADAPTER_NAMES, } from "./adapter";
+export { PiAiAdapter } from "./adapter-pi-ai";
+export { AiSdkAdapter } from "./adapter-ai-sdk";
+export { createLLMAdapter, setLLMProvider, getLLMProviderOverride } from "./factory";
+export { type ContentPart, type LLMMessage, type LLMOutput, type UsageInfo, type ToolCall, type ToolResult, type ToolInfo, type LLMConfig, type LLMProvider, type ProviderConfig, type ProviderType, type LLMInvokeRequest, type LLMInvokeResult, type StreamEvent, } from "./types";
+export { LLMConfigSchema, ProviderConfigSchema, ProviderCapabilitiesSchema, ModelLimitsSchema, LLMDefaultConfigSchema, } from "./types";
+export { ProviderManager } from "./provider";
+export { LLMTransform } from "./transform";
+export { invoke, invokeNonStream, parseModelString, createInvokeConfig, convertToSDKMessages, type InvokeConfig, type InvokeOptions, type LLMToolContext, type ConvertedUsageInfo, } from "./invoke";
+export { isOpencodeProvider, isOpencodeEndpoint, buildOpencodeHeaders, getOrCreateOpencodeSessionId, generateOpencodeSessionId, } from "./opencode-session";
+export { type LLMHookType, type LLMHookContext, type LLMBeforeInvokeHook, type LLMAfterInvokeHook, type LLMStreamHook, type LLMHookRegistration, LLMHooks, } from "./hooks";
+export { LLMComponent, type LLMComponentOptions } from "./llm";

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

@@ -0,0 +1,264 @@
+/**
+ * @fileoverview LLM invocation with AI SDK integration.
+ *
+ * This module provides LLM invocation using AI SDK for better provider support.
+ * Stream events are published via Environment.pushEnvEvent().
+ */
+import { type ModelMessage } from "ai";
+import type { ToolInfo, ToolResult, LLMOutput, LLMMessage } from "./types";
+import type { Environment } from "../interface";
+import { __clearOpencodeSessionIdCache } from "./opencode-session";
+/**
+ * Re-exported for backwards compatibility with existing tests
+ * (`packages/core/test/llm/opencode-go-interactive.test.ts`). The implementation
+ * now lives in `opencode-session.ts` so the default PiAiAdapter path can share it.
+ */
+export { __clearOpencodeSessionIdCache };
+/**
+ * Invoke LLM 配置
+ */
+export interface InvokeConfig {
+    /** 模型标识符（格式: providerId/modelId） */
+    model: string;
+    /** Base URL */
+    baseURL?: string;
+    /** API Key */
+    apiKey: string;
+    /** 额外选项 */
+    options?: {
+        /**
+         * 文本内嵌思考标签处理配置
+         *
+         * 对齐 `ProviderCapabilities.thinkingInText` (`packages/core/src/env/llm/types.ts`)：
+         * - `enabled`: 是否启用标签剥离
+         * - `tags`: 标签名列表（例如 `["think"]` → `""`）
+         * - `removeFromOutput`: 剥离后是否从返回值中移除（`false` 则保留原始含标签内容，
+         *   便于维持消息历史中的推理连续性，例如 MiniMax 需要看历史中的标签才会继续输出 reasoning）
+         */
+        thinkingInText?: {
+            enabled?: boolean;
+            tags?: string[];
+            removeFromOutput?: boolean;
+        };
+    };
+}
+/**
+ * LLM 选项
+ */
+export interface InvokeOptions {
+    /** 消息列表 */
+    messages: LLMMessage[];
+    /** 工具列表 */
+    tools?: ToolInfo[];
+    /** 模型标识符（可选） */
+    model?: string;
+    /** 温度参数 */
+    temperature?: number;
+    /** 最大 Token 数 */
+    maxTokens?: number;
+    /** Environment 实例（用于发布流式事件，可选） */
+    env?: Environment;
+    /** 上下文信息（用于事件元数据） */
+    context?: {
+        /** Session ID */
+        sessionId?: string;
+        /** Message ID */
+        messageId?: string;
+    };
+    /**
+     * 工具选择策略（强制 LLM 调用特定工具）
+     *
+     * - "auto"   — LLM 自主决定（默认）
+     * - "none"   — 禁止调用任何工具
+     * - "required" — 必须调用至少一个工具（Issue #1694: 确保 json-extract 必须调用 workflow_submit_output）
+     * - { type: "function", function: { name: "..." } } — 强制调用指定工具
+     */
+    toolChoice?: "auto" | "none" | "required" | {
+        type: "function";
+        function: {
+            name: string;
+        };
+    };
+}
+/**
+ * LLM Tool Context - Context for tool calls during LLM invocation
+ */
+export interface LLMToolContext {
+    /** Abort Signal */
+    abort?: AbortSignal | undefined;
+    /** 额外上下文 */
+    context?: Record<string, unknown>;
+}
+/**
+ * Usage 信息（AI SDK 格式）
+ * 参考: LanguageModelV3Usage from @ai-sdk/provider
+ */
+interface AISDKUsage {
+    inputTokens?: {
+        total?: number;
+        noCache?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+        [key: string]: unknown;
+    };
+    outputTokens?: {
+        total?: number;
+        [key: string]: unknown;
+    };
+    totalTokens?: number;
+    promptTokens?: number;
+    completionTokens?: number;
+    inputTokenDetails?: {
+        tokens?: number;
+        [key: string]: unknown;
+    };
+    outputTokenDetails?: {
+        tokens?: number;
+        [key: string]: unknown;
+    };
+    raw?: {
+        total_tokens?: number;
+        prompt_tokens?: number;
+        completion_tokens?: number;
+    };
+}
+/**
+ * Usage 信息转换
+ */
+export interface ConvertedUsageInfo {
+    /** Prompt Token 数 */
+    promptTokens: number;
+    /** Completion Token 数 */
+    completionTokens: number;
+    /** 总 Token 数 */
+    totalTokens: number;
+    /**
+     * Anthropic prompt cache read tokens (cache_read_input_tokens).
+     * `undefined` when the provider did not report a cache-read field.
+     * `0` means the cache was checked but no tokens hit (distinct from
+     * the field being absent).
+     */
+    cacheRead?: number;
+    /**
+     * Anthropic prompt cache write tokens (cache_creation_input_tokens).
+     * See {@link cacheRead} for semantics.
+     */
+    cacheWrite?: number;
+}
+/**
+ * 超时错误
+ */
+export declare class TimeoutError extends Error {
+    readonly timeout: number;
+    constructor(message: string, timeout: number);
+}
+/**
+ * 带超时的 Promise 包装器
+ *
+ * @param promise 要执行的 Promise
+ * @param timeoutMs 超时时间（毫秒）
+ * @param message 自定义错误消息
+ * @returns Promise 结果
+ * @throws TimeoutError 当超时时
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs?: number, message?: string): Promise<T>;
+/**
+ * 解析模型字符串
+ * 格式: "providerId/modelId"
+ */
+export declare function parseModelString(model?: string): {
+    providerId: string;
+    modelId: string;
+};
+/**
+ * 从 Usage 信息提取标准格式
+ *
+ * I4 (review-cache-stability.md): now exposes `cacheRead` / `cacheWrite` so
+ * callers can observe Anthropic prompt cache effectiveness.
+ *
+ * AI SDK v3 usage shape places cache tokens at two possible locations:
+ * 1. `usage.inputTokens.cacheRead` / `usage.inputTokens.cacheWrite`
+ *    (modern LanguageModelV3Usage object form)
+ * 2. `usage.inputTokenDetails.cacheReadTokens` / `cacheWriteTokens`
+ *    (legacy / MiniMax / DeepSeek form)
+ *
+ * We check the modern form first and fall back to the legacy form.
+ * A reported `0` is preserved (the cache was checked, no hit);
+ * `undefined` means the provider did not report the field at all.
+ */
+export declare function extractUsageInfo(usage: AISDKUsage | undefined): ConvertedUsageInfo | undefined;
+/**
+ * Recursively sort object keys for deterministic byte serialization.
+ *
+ * I2 (review-cache-stability.md): the LLM may emit the same tool call
+ * with keys in different orders across turns (e.g. `{a:1,b:2}` vs
+ * `{b:2,a:1}`). AI SDK internally JSON.stringifies tool-call `input`
+ * before forwarding to Anthropic — if the key order shifts, the cache
+ * prefix changes and Anthropic reports a cache miss.
+ *
+ * Sorting keys before JSON.stringify (or before handing to AI SDK)
+ * guarantees the bytes are deterministic regardless of LLM key order.
+ *
+ * Behavioral notes:
+ * - Arrays preserve their order (element order is semantically meaningful).
+ * - Uint8Array / Buffer are returned by identity (we don't try to sort
+ *   their bytes — that would be lossy and impossible for binary data).
+ * - Primitives (string, number, boolean, null, undefined) pass through.
+ *
+ * @see https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+ */
+export declare function sortObjectKeysDeep<T>(obj: T, seen?: WeakSet<object>): T;
+export { applyToolCacheControl, canonicalizeParts } from "./llm-cache";
+/**
+ * 将 LLMMessage 转换为 AI SDK 格式
+ *
+ * I1 (review-cache-stability.md): inserts Anthropic prompt-cache breakpoints
+ * on the system message and the last user message. Without these, Anthropic
+ * never caches anything and we pay full input price every turn.
+ *
+ * Task #2748 §5.3: 支持 sessionId 参数，给 OpenAI-Compatible provider
+ * 注入 prompt_cache_key=sessionId。
+ */
+export declare function convertToSDKMessages(messages: LLMMessage[], options?: {
+    sessionId?: string;
+    provider?: string;
+}): ModelMessage[];
+/**
+ * 从 AI SDK stream part 提取文本增量（兼容 text / delta 字段）
+ */
+export declare function getStreamPartText(part: Record<string, unknown>): string;
+/**
+ * 核心 LLM 调用函数
+ * 使用 AI SDK 的 streamText
+ *
+ * 流式事件通过 env.pushEnvEvent() 发布
+ *
+ * @param config - Invoke 配置
+ * @param options - LLM 选项
+ * @param ctx - Tool Context
+ * @returns ToolResult
+ */
+export declare function invoke(config: InvokeConfig, options: InvokeOptions, ctx: LLMToolContext): Promise<ToolResult>;
+/**
+ * 创建 Provider 实例
+ * 根据 providerId 创建对应的 AI SDK Provider
+ */
+declare function createProviderInstance(providerId: string, apiKey: string, baseURL?: string, conversationId?: string): any;
+/**
+ * Test-only re-export of createProviderInstance so that unit tests can verify
+ * header injection behavior without booting the full invoke() stack.
+ *
+ * This is gated by an explicit `__` prefix to make it obvious in code review
+ * that this surface is for tests only. Production code MUST NOT import this.
+ */
+export declare const __createProviderInstanceForTest: typeof createProviderInstance;
+/**
+ * 非流式 LLM 调用
+ *
+ * 使用 AI SDK 的 generateText API，返回完整响应
+ */
+export declare function invokeNonStream(config: InvokeConfig, options: InvokeOptions, ctx: LLMToolContext): Promise<LLMOutput>;
+/**
+ * 创建 LLM 配置
+ */
+export declare function createInvokeConfig(model: string, apiKey: string, baseURL?: string): InvokeConfig;

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

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview LLM Cache Options Helpers (Task #2748 §5.3-5.5)
+ *
+ * 4 项 cache 优化相关的 helper 集中在此模块：
+ * - §5.3: OpenAI-Compatible prompt_cache_key
+ * - §5.4: Tool schema cache_control (Anthropic)
+ * - §5.5: parts JSON canonicalize
+ *
+ * 集中导出便于复用、单元测试、独立演进。
+ */
+/**
+ * §5.3: OpenAI-Compatible provider 的 prompt_cache_key
+ *
+ * Anthropic 端用 cache_control; OpenAI 端用 prompt_cache_key。
+ * roy-agent 当前完全没给 OpenAI-Compatible (minimax/DeepSeek/GLM) 挂这个，
+ * 导致这些 provider 的 cache 完全靠隐式行为，命中率低。
+ *
+ * 参考 pi-agent: openai-completions.ts:680-695 (prompt_cache_key=sessionId)
+ */
+export declare function isOpenAICompatibleProvider(providerName: string): boolean;
+export declare function clampOpenAIPromptCacheKey(sessionId: string, maxLen?: number): string;
+export declare function buildOpenAICompatProviderOptions(sessionId: string | undefined, cacheRetention?: "short" | "long" | "none"): Record<string, unknown>;
+/**
+ * §5.4: 给工具 schema 的末 tool 挂 cache_control (Anthropic 3 层)
+ *
+ * pi-agent: anthropic-messages.ts:1005 (compat.supportsCacheControlOnTools ? cacheControl : undefined)
+ * 收益：工具 schema 大的 agent 多省 10-30% input cost。
+ */
+export declare function applyToolCacheControl<T extends Record<string, unknown>>(tools: T[] | undefined, providerName: string): T[] | undefined;
+/**
+ * §5.5: parts JSON canonicalize
+ *
+ * SQLite 存 parts 为 JSON 字符串，读出来时 JSON.parse 的 key 顺序不保证稳定。
+ * 在写入时对 parts 做 sortObjectKeysDeep → byte-stable 序列化。
+ *
+ * 同时也处理 tool-call arguments 字符串（如果是 string，需要 parse → sort → stringify）。
+ */
+export declare function canonicalizeParts(parts: unknown): string;