@henjicc/ai-sdk 0.2.8

package/dist/llm/sdk/providerAdapter.d.ts

@@ -0,0 +1,53 @@
+import type { LanguageModel } from 'ai';
+import type { Transport } from '../../runtime/index.js';
+import type { LlmApiProtocol } from '../providerProtocol.js';
+import { type ModelInputModality, type ModelStepInput } from '../modelStep.js';
+/**
+ * 任务 4.2 从应用侧 LLM 执行层迁入 SDK。
+ *
+ * 唯一的实质改动：`ModelStepHttpTrace.request`/`.response` 原来直接复用痕迹AI 助手侧
+ * `src/core/assistant/trace.ts` 的 `AgentTraceHttpRequest`/`AgentTraceHttpResponse` 类型。
+ * SDK 不能反向依赖应用侧模块（`check:sdk` 会拒绝任何 `@/` 引用），这里改成结构完全等价的
+ * 本地类型 {@link ModelStepHttpCaptureRequest}/{@link ModelStepHttpCaptureResponse}——
+ * 字段名与可选性逐一对齐，TypeScript 结构化类型系统保证调用方（痕迹AI
+ * `electron/main/agent-utility.ts` 与 `electron/main/services/llm/sdk/trace.ts`）拿到的
+ * 捕获对象可以直接赋值给它们自己那份 `AgentTraceHttpRequest`/`AgentTraceHttpResponse`
+ * 类型的参数，不需要任何转换代码。
+ *
+ * 追踪归属的完整决策记录见 docs/task/模型SDK抽离/重要记录.md 记录 014。
+ */
+export interface ModelStepHttpCaptureRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body: unknown;
+}
+export interface ModelStepHttpCaptureResponse {
+    status?: number;
+    statusText?: string;
+    headers?: Record<string, string>;
+    errorBody?: unknown;
+}
+export interface ModelStepHttpTrace {
+    captureHttp?: boolean;
+    request?: ModelStepHttpCaptureRequest;
+    response?: ModelStepHttpCaptureResponse;
+    deepSeekUsage?: {
+        prompt_cache_hit_tokens?: unknown;
+        prompt_cache_miss_tokens?: unknown;
+        prompt_tokens?: unknown;
+    };
+    usageCapture?: Promise<void>;
+}
+export interface ModelStepProviderAdapter {
+    protocol: LlmApiProtocol;
+    supportedInputModalities: readonly ModelInputModality[];
+    createLanguageModel: (input: ModelStepInput, apiKey: string, httpTrace?: ModelStepHttpTrace, transport?: Transport) => LanguageModel;
+}
+export declare class ModelStepProviderAdapterRegistry {
+    private readonly adapters;
+    register(adapter: ModelStepProviderAdapter): void;
+    resolve(protocol: LlmApiProtocol): ModelStepProviderAdapter;
+    assertInputModalities(protocol: LlmApiProtocol, input: Pick<ModelStepInput, 'messages'>): void;
+}
+export declare const modelStepProviderAdapters: ModelStepProviderAdapterRegistry;

package/dist/llm/sdk/providerAdapter.js

@@ -0,0 +1,26 @@
+import { detectModelStepInputModalities, } from '../modelStep.js';
+export class ModelStepProviderAdapterRegistry {
+    adapters = new Map();
+    register(adapter) {
+        if (this.adapters.has(adapter.protocol)) {
+            throw new Error(`[MODEL_PROTOCOL_DUPLICATE] 模型协议已注册：${adapter.protocol}`);
+        }
+        this.adapters.set(adapter.protocol, adapter);
+    }
+    resolve(protocol) {
+        const adapter = this.adapters.get(protocol);
+        if (!adapter)
+            throw new Error(`[MODEL_PROTOCOL_UNSUPPORTED] 不支持的模型协议：${protocol}`);
+        return adapter;
+    }
+    assertInputModalities(protocol, input) {
+        const adapter = this.resolve(protocol);
+        const supported = new Set(adapter.supportedInputModalities);
+        for (const modality of detectModelStepInputModalities(input.messages)) {
+            if (!supported.has(modality)) {
+                throw new Error(`[unsupported_provider_modality] ${protocol} 协议当前无法安全表达 ${modality} 输入`);
+            }
+        }
+    }
+}
+export const modelStepProviderAdapters = new ModelStepProviderAdapterRegistry();

package/dist/llm/sdk/retryPolicy.d.ts

@@ -0,0 +1,13 @@
+import type { ModelStepEvent, ModelStepInput, ModelStepResult } from '../modelStep.js';
+/** 任务 4.2 从应用侧 LLM 执行层迁入 SDK，逻辑不变。 */
+interface ModelStepRetryOptions {
+    input: ModelStepInput;
+    signal: AbortSignal;
+    emit: (event: ModelStepEvent) => void;
+    operation: (emit: (event: ModelStepEvent) => void) => Promise<ModelStepResult>;
+    sleep?: (delayMs: number, signal: AbortSignal) => Promise<void>;
+    random?: () => number;
+    now?: () => number;
+}
+export declare function executeModelStepWithRetry(options: ModelStepRetryOptions): Promise<ModelStepResult>;
+export {};

package/dist/llm/sdk/retryPolicy.js

@@ -0,0 +1,67 @@
+import { normalizeProviderError, shouldRetry, } from '../../runtime/index.js';
+function abortableSleep(delayMs, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, delayMs);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function retryDelay(error, attempt, random) {
+    if (error.details.retryAfterMs !== null)
+        return Math.min(60_000, error.details.retryAfterMs);
+    void random;
+    return Math.min(8_000, 2_000 * (2 ** (attempt - 1)));
+}
+export async function executeModelStepWithRetry(options) {
+    const maxRetries = options.input.settings?.maxRetries ?? 0;
+    const sleep = options.sleep ?? abortableSleep;
+    const random = options.random ?? Math.random;
+    const now = options.now ?? Date.now;
+    for (let attempt = 1; attempt <= maxRetries + 1; attempt += 1) {
+        const attemptStartedAt = now();
+        try {
+            return await options.operation((event) => {
+                options.emit(event);
+            });
+        }
+        catch (error) {
+            const timeoutMs = options.input.settings?.timeoutMs;
+            const reachedRequestDeadline = timeoutMs !== undefined
+                && now() - attemptStartedAt >= Math.max(0, timeoutMs - 100);
+            const failure = reachedRequestDeadline
+                ? Object.assign(new Error(`Model request timed out after ${timeoutMs}ms`, { cause: error }), {
+                    name: 'TimeoutError',
+                    code: 'MODEL_REQUEST_TIMEOUT',
+                    isRetryable: true,
+                })
+                : error;
+            const structured = normalizeProviderError(options.input, failure);
+            // A rejected model step has not produced a ModelStepResult, so the runner has not
+            // executed any tool call or committed assistant output. Partial stream deltas are
+            // presentation-only and do not make replaying this request unsafe.
+            if (!shouldRetry(structured, 'request') || attempt > maxRetries)
+                throw structured;
+            const delayMs = retryDelay(structured, attempt, random);
+            options.emit({
+                type: 'Retrying',
+                layer: 'request',
+                attempt,
+                delayMs,
+                category: structured.details.category,
+                code: structured.details.code,
+            });
+            await sleep(delayMs, options.signal);
+        }
+    }
+    throw new Error('[MODEL_RETRY_EXHAUSTED] 模型请求重试次数已耗尽');
+}

package/dist/llm/sdk/runtime.d.ts

@@ -0,0 +1,13 @@
+import { type RuntimeContext } from '../../runtime/index.js';
+import { type ModelStepEvent, type ModelStepInput, type ModelStepResult } from '../modelStep.js';
+/**
+ * 任务 4.2 从 `electron/main/services/llm/sdk/runtime.ts` 迁入。
+ *
+ * 唯一的实质改动：密钥读取从 `dynamicModelCredentialResolver`（内部包一层
+ * `getLlmProviderApiKey`，Electron keystore）改为 `RuntimeContext.credentials.get('llm', ...)`；
+ * 结构化日志从 `createMainLogger('main.llm_model_step')` 改为 `RuntimeContext.logger`
+ * （缺省 `noopLogger`），事件名/字段与迁移前逐字段一致。
+ */
+export declare function cancelModelStepTask(taskId: string): void;
+export declare function classifyModelStepError(taskId: string, error: unknown, input?: ModelStepInput): Error;
+export declare function runModelStep(rawInput: ModelStepInput, emit: (event: ModelStepEvent) => void, runtime: RuntimeContext): Promise<ModelStepResult>;

package/dist/llm/sdk/runtime.js

@@ -0,0 +1,127 @@
+import { noopLogger } from '../../runtime/index.js';
+import { cancelTask, clearCancelFlag, isCancelled, registerAbortController } from '../../runtime/index.js';
+import { modelStepInputSchema, } from '../modelStep.js';
+import { executeModelStepWithModel } from './modelStep.js';
+import { createModelStepLanguageModel } from './provider.js';
+import { createCancelledError, createCredentialError, normalizeProviderError, ProviderModelStepError, } from '../../runtime/index.js';
+import { executeModelStepWithRetry } from './retryPolicy.js';
+import { resolveLlmEndpointIdentity } from '../endpointProfiles.js';
+/**
+ * 任务 4.2 从 `electron/main/services/llm/sdk/runtime.ts` 迁入。
+ *
+ * 唯一的实质改动：密钥读取从 `dynamicModelCredentialResolver`（内部包一层
+ * `getLlmProviderApiKey`，Electron keystore）改为 `RuntimeContext.credentials.get('llm', ...)`；
+ * 结构化日志从 `createMainLogger('main.llm_model_step')` 改为 `RuntimeContext.logger`
+ * （缺省 `noopLogger`），事件名/字段与迁移前逐字段一致。
+ */
+export function cancelModelStepTask(taskId) {
+    cancelTask('llm', taskId);
+}
+function toLogError(error) {
+    return error instanceof Error
+        ? { name: error.name, message: error.message, stack: error.stack }
+        : error;
+}
+function isAbortError(error) {
+    return error instanceof Error && (error.name === 'AbortError' || error.message.includes('[task_cancelled]'));
+}
+export function classifyModelStepError(taskId, error, input) {
+    if (isCancelled('llm', taskId) || isAbortError(error)) {
+        if (input)
+            return createCancelledError(input);
+        return new Error(`[task_cancelled] LLM model step cancelled: ${taskId}`);
+    }
+    if (error instanceof ProviderModelStepError)
+        return error;
+    if (input)
+        return normalizeProviderError(input, error);
+    if (error instanceof Error && error.message.startsWith('['))
+        return error;
+    const message = error instanceof Error ? error.message : String(error);
+    return new Error(`[model_step_failed] ${message}`);
+}
+export async function runModelStep(rawInput, emit, runtime) {
+    const input = modelStepInputSchema.parse(rawInput);
+    const logger = runtime.logger ?? noopLogger;
+    const controller = new AbortController();
+    const startedAt = Date.now();
+    const span = runtime.tracer?.startSpan('llm.model-step', {
+        requestId: input.requestId,
+        runId: input.runId,
+        providerId: input.providerId,
+        modelId: input.modelId,
+    });
+    registerAbortController('llm', input.requestId, controller);
+    logger.info('模型单步调用开始', {
+        event: 'llm_model_step.run.start',
+        requestId: input.runId,
+        taskId: input.stepId,
+        modelId: input.modelId,
+        providerId: input.providerId,
+        context: {
+            toolCount: input.capabilities.toolCall ? (input.tools?.length ?? 0) : 0,
+            outputMode: input.output.mode,
+            reasoningEnabled: input.reasoning?.enabled === true,
+        },
+    });
+    try {
+        const identity = resolveLlmEndpointIdentity(input);
+        const resolvedInput = modelStepInputSchema.parse({
+            ...input,
+            providerFamilyId: identity.providerFamilyId,
+            endpointProfile: identity.endpointProfile,
+            credentialId: identity.credentialId,
+            baseUrl: identity.baseUrl,
+        });
+        const apiKey = await runtime.credentials.get('llm', identity.credentialId);
+        if (!apiKey) {
+            throw createCredentialError(input);
+        }
+        const result = await executeModelStepWithRetry({
+            input: resolvedInput,
+            signal: controller.signal,
+            emit,
+            operation: (attemptEmit) => executeModelStepWithModel(resolvedInput, createModelStepLanguageModel(resolvedInput, apiKey, undefined, runtime.transport), attemptEmit, controller.signal),
+        });
+        logger.info('模型单步调用完成', {
+            event: 'llm_model_step.run.completed',
+            requestId: input.runId,
+            taskId: input.stepId,
+            modelId: input.modelId,
+            providerId: input.providerId,
+            context: {
+                finishReason: result.finishReason,
+                elapsedMs: result.elapsedMs,
+                usage: result.usage,
+                toolCallCount: result.toolCalls.length,
+            },
+        });
+        span?.end();
+        return result;
+    }
+    catch (error) {
+        const classified = classifyModelStepError(input.requestId, error, input);
+        span?.end(classified);
+        logger.error('模型单步调用失败', {
+            event: 'llm_model_step.run.failed',
+            requestId: input.runId,
+            taskId: input.stepId,
+            modelId: input.modelId,
+            providerId: input.providerId,
+            context: {
+                elapsedMs: Date.now() - startedAt,
+                code: classified instanceof ProviderModelStepError
+                    ? classified.details.code
+                    : classified.message.match(/^\[([^\]]+)]/)?.[1],
+                category: classified instanceof ProviderModelStepError
+                    ? classified.details.category
+                    : undefined,
+            },
+            error: toLogError(classified),
+        });
+        throw classified;
+    }
+    finally {
+        clearCancelFlag('llm', input.requestId);
+    }
+}

package/dist/llm/sdk/toolSchema.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 工具 JSON Schema 的供应商规范化。
+ *
+ * 以 DeepSeek 文档为基准（strict 模式只支持 object/string/number/integer/boolean/array/enum/anyOf，
+ * 明确不支持 minLength/maxLength/minItems/maxItems，且要求每个 object 都 additionalProperties:false
+ * 并把全部属性列进 required），但规则本身不绑定供应商——OpenAI 的 structured outputs 是同一套
+ * 约束，其他供应商要么同样接受，要么忽略。
+ *
+ * 之前 `toModelTool` 对每个工具都硬写 `strict: true`，而我们的 schema 里到处是可选属性和
+ * min/max 约束，三条要求全违反。这类不一致不会在本地报错，只会在供应商侧变成一次难以归因的
+ * 请求失败或参数被静默忽略。
+ *
+ * 处理方式是"如实声明"而不是"强行改造"：能满足 strict 的照常声明 strict 并剔除不支持的关键字；
+ * 不满足的就老实降级成非 strict，把 min/max 之类的提示原样留给模型参考。绝不为了凑 strict 去
+ * 篡改语义（例如把可选属性硬写成必填）。
+ *
+ * 任务 4.2 从 `electron/main/services/llm/sdk/tool-schema.ts` 迁入，逻辑不变。
+ */
+export interface NormalizedToolSchema {
+    schema: unknown;
+    strict: boolean;
+}
+/**
+ * 按 schema 的真实形状决定是否声明 strict，并在声明时剔除不被支持的关键字。
+ *
+ * @param requestedStrict 调用方期望的 strict；为 false 时直接原样透传，不做任何改写。
+ */
+export declare function normalizeProviderToolSchema(schema: unknown, requestedStrict: boolean | undefined): NormalizedToolSchema;

package/dist/llm/sdk/toolSchema.js

@@ -0,0 +1,59 @@
+/**
+ * 工具 JSON Schema 的供应商规范化。
+ *
+ * 以 DeepSeek 文档为基准（strict 模式只支持 object/string/number/integer/boolean/array/enum/anyOf，
+ * 明确不支持 minLength/maxLength/minItems/maxItems，且要求每个 object 都 additionalProperties:false
+ * 并把全部属性列进 required），但规则本身不绑定供应商——OpenAI 的 structured outputs 是同一套
+ * 约束，其他供应商要么同样接受，要么忽略。
+ *
+ * 之前 `toModelTool` 对每个工具都硬写 `strict: true`，而我们的 schema 里到处是可选属性和
+ * min/max 约束，三条要求全违反。这类不一致不会在本地报错，只会在供应商侧变成一次难以归因的
+ * 请求失败或参数被静默忽略。
+ *
+ * 处理方式是"如实声明"而不是"强行改造"：能满足 strict 的照常声明 strict 并剔除不支持的关键字；
+ * 不满足的就老实降级成非 strict，把 min/max 之类的提示原样留给模型参考。绝不为了凑 strict 去
+ * 篡改语义（例如把可选属性硬写成必填）。
+ *
+ * 任务 4.2 从 `electron/main/services/llm/sdk/tool-schema.ts` 迁入，逻辑不变。
+ */
+/** strict 模式下不被支持的校验关键字；仅在真正声明 strict 时才剔除。 */
+const STRICT_UNSUPPORTED_KEYWORDS = ['minLength', 'maxLength', 'minItems', 'maxItems'];
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+/** 每个 object 节点都必须显式 additionalProperties:false，且把全部属性列进 required。 */
+function satisfiesStrictSubset(node) {
+    if (Array.isArray(node))
+        return node.every(satisfiesStrictSubset);
+    if (!isRecord(node))
+        return true;
+    if (isRecord(node.properties)) {
+        if (node.additionalProperties !== false)
+            return false;
+        const required = new Set(Array.isArray(node.required) ? node.required.map(String) : []);
+        if (Object.keys(node.properties).some((key) => !required.has(key)))
+            return false;
+    }
+    return Object.values(node).every(satisfiesStrictSubset);
+}
+function stripStrictUnsupportedKeywords(node) {
+    if (Array.isArray(node))
+        return node.map(stripStrictUnsupportedKeywords);
+    if (!isRecord(node))
+        return node;
+    return Object.fromEntries(Object.entries(node)
+        .filter(([key]) => !STRICT_UNSUPPORTED_KEYWORDS.includes(key))
+        .map(([key, value]) => [key, stripStrictUnsupportedKeywords(value)]));
+}
+/**
+ * 按 schema 的真实形状决定是否声明 strict，并在声明时剔除不被支持的关键字。
+ *
+ * @param requestedStrict 调用方期望的 strict；为 false 时直接原样透传，不做任何改写。
+ */
+export function normalizeProviderToolSchema(schema, requestedStrict) {
+    if (requestedStrict !== true)
+        return { schema, strict: false };
+    if (!satisfiesStrictSubset(schema))
+        return { schema, strict: false };
+    return { schema: stripStrictUnsupportedKeywords(schema), strict: true };
+}

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

@@ -0,0 +1,18 @@
+/**
+ * UXP 与其他受限宿主的原生 OpenAI-compatible SSE 入口。
+ *
+ * 此入口刻意不导出模型目录、modelStep、Zod 或 Vercel AI SDK。旧的 `./llm` 与包根仍会
+ * 通过同一 `chat.ts` / `streaming.ts` 实现重导出这些 API，不存在第二份流式执行逻辑。
+ */
+export { cancelLlmChatTask, normalizeLlmChatError, resolveLlmTaskId, runLlmChatStream, } from '../chat.js';
+export type { LlmChatCompletedInfo, LlmChatRequestBuiltInfo, LlmChatStreamHooks, LlmChatStreamOutcome, } from '../chat.js';
+export type { JsonObject, JsonValue, LlmChatMessageDto, LlmChatRequestDto, LlmContentPart, LlmRole, LlmStreamEmitter, LlmStreamEventDto, LlmStreamOutput, LlmTraceDto, LlmUsageDto, } from '../chatTypes.js';
+export type { LlmReasoningConfig, LlmReasoningEffort } from '../reasoning.js';
+export { parseModelProviderError, ProviderModelStepError, serializeModelProviderError, } from '../../runtime/provider-error-core.js';
+export type { ModelProviderError, ModelProviderErrorCategory, } from '../../runtime/provider-error-core.js';
+export type { RuntimeContext } from '../../runtime/RuntimeContext.js';
+export type { Transport } from '../../runtime/Transport.js';
+export type { CredentialScope, CredentialStore } from '../../runtime/CredentialStore.js';
+export type { MediaBinary, MediaReader } from '../../runtime/MediaReader.js';
+export type { LogContext, Logger } from '../../runtime/Logger.js';
+export type { TraceSpan, Tracer } from '../../runtime/Tracer.js';

package/dist/llm/streaming/index.js

@@ -0,0 +1,8 @@
+/**
+ * UXP 与其他受限宿主的原生 OpenAI-compatible SSE 入口。
+ *
+ * 此入口刻意不导出模型目录、modelStep、Zod 或 Vercel AI SDK。旧的 `./llm` 与包根仍会
+ * 通过同一 `chat.ts` / `streaming.ts` 实现重导出这些 API，不存在第二份流式执行逻辑。
+ */
+export { cancelLlmChatTask, normalizeLlmChatError, resolveLlmTaskId, runLlmChatStream, } from '../chat.js';
+export { parseModelProviderError, ProviderModelStepError, serializeModelProviderError, } from '../../runtime/provider-error-core.js';

package/dist/llm/streaming.d.ts

@@ -0,0 +1,25 @@
+import type { Transport } from '../runtime/Transport.js';
+import type { JsonObject, LlmChatMessageDto, LlmChatRequestDto, LlmStreamEmitter, LlmStreamOutput } from './chatTypes.js';
+/**
+ * 原生 SSE 流式聊天路径的端点解析、请求体构建与流式读取。
+ *
+ * 任务 4.2 从 `electron/main/services/llm/streaming.ts` 迁入。唯一的实质改动：
+ * `streamOpenAiCompatibleChat` 不再直接调用全局 `fetch`，改为接收调用方注入的
+ * `Transport`（宿主网络能力，见 `../runtime/Transport.ts`）——`Transport.fetch()`
+ * 返回标准 `Response`，`response.body` 本身就是标准 `ReadableStream<Uint8Array>`，
+ * SSE 逐块读取（`readSseStream`）不需要 `Transport` 接口做任何扩展。
+ */
+interface StreamChatOptions {
+    endpoint: string;
+    apiKey: string;
+    request: LlmChatRequestDto;
+    signal: AbortSignal;
+    emit: LlmStreamEmitter;
+    transport: Transport;
+}
+export declare function resolvePpioChatEndpoint(baseUrl?: string): string;
+export declare function resolveOpenAiCompatibleEndpoint(request: LlmChatRequestDto): string;
+export declare function buildOpenAiCompatiblePayload(request: LlmChatRequestDto): JsonObject;
+export declare function streamOpenAiCompatibleChat(options: StreamChatOptions): Promise<LlmStreamOutput>;
+export declare function serializeMessage(message: LlmChatMessageDto): JsonObject;
+export {};