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

package/dist/env/llm/adapter-pi-ai.d.ts

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview PiAiAdapter — 包装 @earendil-works/pi-ai。
+ *
+ * 这是 roy-agent 默认的 LLM 适配层（ROY_LLM_PROVIDER=pi-ai 时启用）。
+ * 把 ChatRequest / ChatResponse / StreamHandle 翻译成 pi-ai 的
+ * complete() / stream() / getModel() 三件套。
+ *
+ * 关键映射：
+ * - provider/modelId → getModel(provider, modelId)
+ * - LLMMessage[] → pi-ai Context.messages
+ * - AssistantMessage.stopReason → ChatResponse.finishReason
+ * - usage {input, output, totalTokens} → UsageInfo
+ */
+import { type Model, type Context, type CacheRetention } from "@earendil-works/pi-ai";
+import type { LLMAdapter, ChatRequest, ChatResponse, StreamHandle, ResolvedProvider, EmbedRequest, EmbedResponse } from "./adapter";
+import type { LLMMessage, ToolInfo } from "./types";
+/**
+ * Known provider list — 驱动 resolveProvider 的硬编码能力映射
+ *
+ * `apiProtocol`（Task #4383 P1）是**显式**协议声明，优先于任何 baseURL 猜测。
+ * 历史背景：`api` 字段曾被 `resolvePiModel()` 里的字面量特判
+ * （`baseURL?.includes("anthropic")`）绕过 —— minimax 因为真实 baseURL 恰好是
+ * `https://api.minimaxi.com/anthropic` 才「误打误撞」走对 anthropic-messages，
+ * 从而成为三家 provider 里唯一挂上显式 `cache_control` 的那个（#4381 实测 99.86%）。
+ * 现在把它变成声明式的，避免「换个 baseURL 就悄悄改了协议」。
+ *
+ * `api` 保留为**向后兼容**的遗留字段（只在既无 `apiProtocol` 也无 baseURL 线索时兜底）。
+ */
+export declare const KNOWN_PROVIDER_APIS: Record<string, {
+    api: string;
+    apiProtocol?: string;
+    contextLimit: number;
+    maxTokensLimit: number;
+}>;
+/**
+ * Resolve the pi-ai API protocol for a provider (Task #4383 P1).
+ *
+ * Resolution order (first match wins):
+ *   1. `explicitProtocol` — caller/config pins it, highest priority
+ *   2. `PROVIDER_API_OVERRIDES` — deliberate id-variant pins
+ *   3. `PROVIDER_ENDPOINT_APIS[provider]` — declared per-endpoint mapping
+ *      (only for vendors that genuinely ship two protocols)
+ *   4. `KNOWN_PROVIDER_APIS[provider].apiProtocol` — declarative vendor default
+ *   5. generic `baseURL` heuristics — backward compat for user-defined proxies
+ *      (`/responses` → openai-responses, `anthropic` → anthropic-messages).
+ *      This path logs a warning so we notice configs that should be declared.
+ *   6. `KNOWN_PROVIDER_APIS[provider].api` — legacy field
+ *   7. `openai-completions` — final fallback
+ *
+ * @param provider         roy-agent provider id from config (e.g. "minimax")
+ * @param baseURL          resolved provider base URL (may be undefined)
+ * @param explicitProtocol optional explicit protocol from caller/config
+ */
+export declare function resolveApiProtocol(provider: string, baseURL?: string, explicitProtocol?: string): string;
+/**
+ * pi-ai `Model.compat` overrides that make `reasoning: true` a **byte-level
+ * no-op** for the openai-completions request body (Task #4403).
+ *
+ * Both entries are load-bearing and were derived empirically by capturing the
+ * real payload through pi-ai's public `onPayload` hook and diffing it against
+ * the `reasoning: false` baseline:
+ *
+ * - `supportsDeveloperRole: false` — without it, `openai-completions.js:591`
+ *   computes `useDeveloperRole = model.reasoning && compat.supportsDeveloperRole`
+ *   and rewrites the first message's role from `system` to `developer`.
+ *   That difference lands at **JSON offset ~40** (the very start of the body),
+ *   so prompt caching — which is a prefix match — would miss on every turn.
+ * - `thinkingFormat: "openai"` — without it, `openai-completions.js:433-475`
+ *   picks the vendor's native thinking branch and, because roy-agent never
+ *   passes `options.reasoningEffort`, emits an explicit
+ *   `thinking: {type: "disabled"}` (deepseek) / `enable_thinking: false`
+ *   (zai/qwen). That is a new top-level field the provider never saw before.
+ *
+ * With all three pins the payload is byte-identical to the `reasoning: false`
+ * baseline for every CUSTOM provider in the real config (verified for
+ * opencodego / glm / minimax / ali / volcengine / tong / opencode, plus
+ * deepseek once the Task #4398 `reasoning_content` hook is attached), so
+ * turning reasoning on can never regress the cache.
+ *
+ * Scope caveat: this guarantee covers the **fallback** (custom-provider)
+ * branch of `resolvePiModel()`. pi-ai built-ins keep their own hand-tuned
+ * `compat`/`reasoning` in the descriptor and are deliberately left alone.
+ */
+export declare const REASONING_COMPAT_PIN: {
+    readonly supportsDeveloperRole: false;
+    readonly thinkingFormat: "openai";
+    readonly supportsReasoningEffort: false;
+};
+/**
+ * Protocols where {@link REASONING_COMPAT_PIN} can actually hold the payload
+ * byte-stable.
+ *
+ * `openai-responses` is deliberately excluded: pi-ai flips the system prompt
+ * role there **unconditionally** —
+ *   `openai-responses-shared.js:66: const role = model.reasoning ? "developer" : "system"`
+ * — with no `compat` escape hatch (its `getCompat()` only exposes
+ * `sendSessionIdHeader` / `supportsLongCacheRetention`). So on that path
+ * `reasoning: true` is a guaranteed prefix break, and we keep it off.
+ */
+export declare const REASONING_SAFE_PROTOCOLS: ReadonlySet<string>;
+/**
+ * Decide the `reasoning` flag for a pi-ai model descriptor (Task #4403).
+ *
+ * This replaces the hardcoded `reasoning: false` that `resolvePiModel()` used
+ * to emit for every non-built-in (i.e. every custom) provider — the root
+ * problem flagged by Task #4398, because that literal silently disabled every
+ * `model.reasoning`-gated pi-ai capability.
+ *
+ * Resolution order:
+ *   1. protocol safety guard — see {@link REASONING_SAFE_PROTOCOLS}. Even an
+ *      explicit `capabilities.reasoning: true` cannot win here, because on
+ *      `openai-responses` the request prefix is guaranteed to change.
+ *   2. explicit config `capabilities.reasoning` (either `true` or `false`).
+ *   3. conservative default `false`.
+ *
+ * Deliberately NO model-name pattern matching. Guessing from names (e.g.
+ * "looks like a reasoner") risks emitting provider-specific thinking fields
+ * that the backend rejects (400), makes calls slower, and bills thinking
+ * tokens as output. Config is the only source of truth; absence means off.
+ *
+ * @param provider    roy-agent provider id (may be a gateway)
+ * @param modelId     model id requested from the provider
+ * @param capabilities `llm.providers.<id>.capabilities` from config
+ * @param apiProtocol resolved pi-ai API protocol for this target
+ */
+export declare function resolveModelReasoning(provider: string, modelId: string, capabilities?: {
+    reasoning?: boolean;
+}, apiProtocol?: string): boolean;
+/**
+ * Build the pi-ai cache-related request options (Task #4383 P0).
+ *
+ * Why this exists (#4381 root cause): pi-ai only emits an explicit cache
+ * marker when it is handed the right options. Two independent code paths:
+ *
+ * - **openai-completions** (`openai-completions.js:394-398`): `prompt_cache_key`
+ *   is only set when `baseUrl` contains `api.openai.com` **or**
+ *   `cacheRetention === "long" && compat.supportsLongCacheRetention`.
+ *   deepseek / glm are neither `api.openai.com` nor passed any retention, so
+ *   `prompt_cache_key` was permanently `undefined` → they fell back to implicit
+ *   caching. Passing `cacheRetention: "long"` also sets
+ *   `prompt_cache_retention: "24h"`.
+ * - **anthropic-messages** (`anthropic.js:25-36, 667-707`): `cache_control`
+ *   markers are attached whenever `cacheRetention !== "none"`, and pi-ai
+ *   already defaults to `"short"` (ephemeral, no ttl). That default is exactly
+ *   what makes minimax hit 99.86%, so we must NOT override it — passing
+ *   `"long"` would add `ttl: "1h"` and silently change current behaviour.
+ *
+ * Hence: openai-completions defaults to `"long"`, everything else keeps pi-ai's
+ * own default unless the caller explicitly asks for a retention.
+ *
+ * @returns options fragment to spread into `complete()` / `stream()` options.
+ *          Only keys that should actually be sent are present (no `undefined`
+ *          values), so `"sessionId" in opts` stays a meaningful assertion.
+ */
+export declare function buildPiCacheOptions(args: {
+    apiProtocol: string;
+    sessionId?: string;
+    cacheRetention?: CacheRetention;
+}): Record<string, unknown>;
+/**
+ * Resolve built-in models and models declared by roy-agent configuration.
+ * pi-ai's generated registry only contains its bundled provider/model pairs;
+ * custom provider ids (for example minimax-openai) need a complete Model
+ * descriptor before complete()/stream() can dispatch by API.
+ */
+export declare function resolvePiModel(provider: string, modelId: string, baseURL?: string, capabilities?: {
+    reasoning?: boolean;
+}): Model<any>;
+/**
+ * 将 LLMMessage 转换为 pi-ai 的消息结构
+ */
+export declare function toPiMessages(messages: LLMMessage[]): Context["messages"];
+export declare function extractSystemPrompt(messages: LLMMessage[]): string | undefined;
+export declare function toPiTools(tools: ToolInfo[] | undefined): Context["tools"];
+export declare class EmbeddingNotSupportedError extends Error {
+    constructor(adapter: string);
+}
+export declare class PiAiAdapter implements LLMAdapter {
+    readonly name: "pi-ai";
+    chat(req: ChatRequest): Promise<ChatResponse>;
+    stream(req: ChatRequest): Promise<StreamHandle>;
+    embed(_req: EmbedRequest): Promise<EmbedResponse>;
+    resolveProvider(provider: string, modelId: string): Promise<ResolvedProvider>;
+}

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

@@ -0,0 +1,100 @@
+/**
+ * @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, ProviderCapabilities } 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;
+    /**
+     * Prompt-cache retention preference (Task #4383 P0).
+     *
+     * Forwarded to pi-ai's `ProviderStreamOptions.cacheRetention`. When omitted,
+     * `buildPiCacheOptions()` applies a protocol-aware default:
+     * - `openai-completions` → `"long"` (needed for `prompt_cache_key`)
+     * - anything else → pi-ai's own default (`anthropic` uses `"short"` =
+     *   ephemeral `cache_control`, which is the behaviour minimax already relies on)
+     */
+    cacheRetention?: "none" | "short" | "long";
+    /**
+     * Provider capabilities from config (`llm.providers.<id>.capabilities`).
+     *
+     * Task #4403: this is the data path that was missing. `resolvePiModel()` used
+     * to hardcode `reasoning: false` for every custom provider, so
+     * `capabilities.reasoning` in config never influenced the pi-ai model
+     * descriptor at all. Threading it through here lets the descriptor reflect
+     * what the user actually configured.
+     */
+    capabilities?: ProviderCapabilities;
+}
+/** 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/index.js

@@ -14,7 +14,7 @@ import {
   createLLMAdapter,
   getLLMProviderOverride,
   setLLMProvider
-} from "../../shared/@ai-setting/roy-agent-core-p8ak03s0.js";
+} from "../../shared/@ai-setting/roy-agent-core-w527pcpe.js";
 import"../../shared/@ai-setting/roy-agent-core-adg9ghbt.js";
 import"../../shared/@ai-setting/roy-agent-core-zjdzk1gg.js";
 import {
@@ -28,7 +28,7 @@ import {
   isOpencodeEndpoint,
   isOpencodeProvider,
   parseModelString
-} from "../../shared/@ai-setting/roy-agent-core-zy3hqfwg.js";
+} from "../../shared/@ai-setting/roy-agent-core-0hq21px2.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";