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

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

@@ -0,0 +1,304 @@
+/**
+ * @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, ProviderCapabilities } 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;
+    /**
+     * Provider capabilities from config (`llm.providers.<id>.capabilities`).
+     *
+     * Task #4403: declared here so `LLMComponent.invoke()` can forward it to
+     * `ChatRequest.capabilities` without an `as any` cast. Typed as the full
+     * `ProviderCapabilities` shape (not just `{ reasoning?: boolean }`) because
+     * the runtime value is the whole object from config.
+     */
+    capabilities?: ProviderCapabilities;
+    /** 额外选项 */
+    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;
+/**
+ * 计算 prompt cache 命中率（0..1）。
+ *
+ * Task #4373：这是把「roy-agent 自己的缓存命中」变成可观测量的关键 helper。
+ *
+ * ⚠️ 语义陷阱（上一轮 #4369 已经踩过一次）：
+ *
+ *   pi-ai 上报的 `promptTokens` 是 **已扣除缓存后的新增量**：
+ *     `input = max(0, prompt_tokens - cacheRead - cacheWrite)`
+ *     `totalTokens = input + output + cacheRead + cacheWrite`
+ *   （见 `pi-ai/dist/providers/openai-completions.js::parseChunkUsage`、
+ *     以及 `anthropic.js` 的 message_start 分支——同样把 cacheRead /
+ *     cacheWrite 单独累加进 totalTokens）
+ *
+ *   所以 `cacheRead / promptTokens` 在真实暖流数据下会算出 20,960%
+ *   这种荒谬值。正确的分母是「模型实际处理过的全部 input token」：
+ *
+ *     promptTokensTotal = promptTokens + cacheRead + cacheWrite
+ *     hitRate = cacheRead / promptTokensTotal
+ *
+ * @param usage - 至少包含 promptTokens；cache 字段可选
+ * @returns 0..1 之间的命中率。无缓存信息 / 无 input token 时返回 0（不是 NaN）
+ */
+export declare function computeCacheHitRate(usage: {
+    promptTokens: number;
+    /** Cache-aware denominator; when present it wins over the derivation below. */
+    promptTokensTotal?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    cacheMiss?: number;
+}): number;
+/**
+ * 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;

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

@@ -0,0 +1,263 @@
+import { BaseComponent, type ComponentConfig } from "../component";
+import { type LLMConfig, type LLMInvokeRequest, type LLMInvokeResult, type ModelLimits } from "./types";
+import type { LLMAdapter } from "./adapter";
+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?;
+    /**
+     * Test-only adapter override (see `__setAdapterForTest`).
+     *
+     * Kept as an instance field rather than a module mock so the override is
+     * scoped to a single LLMComponent instance and cannot leak into other test
+     * files sharing the same Bun process.
+     */
+    private adapterOverride?;
+    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;
+    /**
+     * Test-only: inject a fake adapter for this component instance.
+     *
+     * Preferred over `mock.module("./factory")` because it does not leak across
+     * test files in the same Bun process. Call `__setAdapterForTest(undefined)`
+     * to restore normal factory behaviour.
+     */
+    __setAdapterForTest(adapter: LLMAdapter | undefined): void;
+    /**
+     * 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;
+    /**
+     * Task #4396: publish the `llm.completed` env event.
+     *
+     * Payload shape must match what `StreamOutputService.handleCompleted()`
+     * reads (`payload.metadata.usage` + `payload.metadata.model`), otherwise the
+     * TUI footer silently degrades to nothing.
+     */
+    private emitCompletedEvent;
+    /**
+     * 获取 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;