@henjicc/ai-sdk 0.2.8

package/dist/providers/modelscope.js

@@ -0,0 +1,65 @@
+import { AiRuntimeError } from '../runtime/AiRuntimeError.js';
+import { pollUntilResult } from '../protocols/polling.js';
+import { getPointer, normalizeEndpoint, pushUniqueUrl, readJsonResponse, stringAt } from './helpers.js';
+const MODELSCOPE_BASE_URL = 'https://api-inference.modelscope.cn';
+export async function execute(input) {
+    const response = await submitTask(input, normalizeEndpoint(MODELSCOPE_BASE_URL, input.route));
+    const taskId = stringAt(response, '/task_id');
+    if (!taskId) {
+        throw new AiRuntimeError('invalid_response', 'ModelScope response missing task_id');
+    }
+    return { status: 'pending', url: '', taskId, metadata: response };
+}
+export async function continuePolling(input) {
+    const finalPayload = await pollTask(input);
+    const urls = extractUrls(finalPayload);
+    if (urls.length === 0) {
+        throw new AiRuntimeError('empty_result', `ModelScope response has no output_images (task_id=${input.taskId})`);
+    }
+    return { status: 'completed', url: urls.join('|||'), taskId: input.taskId, metadata: finalPayload };
+}
+async function submitTask(input, endpoint) {
+    const response = await input.runtime.transport.fetch(endpoint, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${input.apiKey}`,
+            'Content-Type': 'application/json',
+            'X-ModelScope-Async-Mode': 'true',
+        },
+        body: JSON.stringify(input.body),
+        signal: input.signal,
+    });
+    return await readJsonResponse(response, 'ModelScope');
+}
+async function pollTask(input) {
+    return await pollUntilResult(input, async () => {
+        const response = await input.runtime.transport.fetch(`${MODELSCOPE_BASE_URL}/v1/tasks/${encodeURIComponent(input.taskId)}`, {
+            headers: {
+                Authorization: `Bearer ${input.apiKey}`,
+                'Content-Type': 'application/json',
+                'X-ModelScope-Task-Type': 'image_generation',
+            },
+            signal: input.signal,
+        });
+        const payload = await readJsonResponse(response, 'ModelScope');
+        const state = stringAt(payload, '/task_status') ?? '';
+        if (state === 'SUCCEED')
+            return payload;
+        if (state === 'FAILED')
+            throw new AiRuntimeError('provider_task_failed', 'ModelScope task failed');
+        return undefined;
+    });
+}
+function extractUrls(payload) {
+    const urls = [];
+    const items = getPointer(payload, '/output_images');
+    if (!Array.isArray(items)) {
+        return urls;
+    }
+    for (const item of items) {
+        if (typeof item === 'string') {
+            pushUniqueUrl(urls, item);
+        }
+    }
+    return urls;
+}

package/dist/providers/ppio-media.d.ts

@@ -0,0 +1,2 @@
+export type PpioMediaRewriteMode = 'data-uri' | 'raw-base64' | 'public-url';
+export declare function resolvePpioMediaRewriteMode(route: string, fieldName: string | undefined, isVideo: boolean): PpioMediaRewriteMode;

package/dist/providers/ppio-media.js

@@ -0,0 +1,20 @@
+export function resolvePpioMediaRewriteMode(route, fieldName, isVideo) {
+    const normalized = fieldName?.trim().toLowerCase() ?? '';
+    if (normalized.endsWith('_base64') || normalized.endsWith('_base64s')) {
+        return 'raw-base64';
+    }
+    if (normalized.endsWith('_url') || normalized.endsWith('_urls') || isVideo) {
+        return 'public-url';
+    }
+    if (normalized === 'reference_voice') {
+        return 'public-url';
+    }
+    if (route === '/v1/chat/completions' && normalized === 'url')
+        return 'public-url';
+    if (route === '/async/kling-v3.0-4k-i2v' && (normalized === 'image' || normalized === 'end_image')) {
+        return 'public-url';
+    }
+    if (route === '/async/kling-v3.0-motion-control' && normalized === 'image')
+        return 'public-url';
+    return 'data-uri';
+}

package/dist/providers/ppio.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderContinuePollingInput, ProviderExecutionInput, ProviderExecutionResult } from '../types/runtime.js';
+export declare function execute(input: ProviderExecutionInput): Promise<ProviderExecutionResult>;
+export declare function continuePolling(input: ProviderContinuePollingInput): Promise<ProviderExecutionResult>;

package/dist/providers/ppio.js

@@ -0,0 +1,98 @@
+import { AiRuntimeError } from '../runtime/AiRuntimeError.js';
+import { pollUntilResult } from '../protocols/polling.js';
+import { getPointer, normalizeEndpoint, pushUniqueUrl, readJsonResponse, stringAt } from './helpers.js';
+// 官网与全部文档示例现已统一使用 api.ppio.com；旧域名 api.ppinfra.com 目前仍可用
+// （两者对同一路由返回一致），但官方已无任何引用，按现行域名接入。
+const PPIO_BASE_URL = 'https://api.ppio.com/v3';
+export async function execute(input) {
+    const endpoint = normalizeEndpoint(PPIO_BASE_URL, input.route);
+    const response = await sendJson(input, endpoint);
+    const taskId = extractTaskId(response);
+    if (taskId) {
+        return { status: 'pending', url: '', taskId, metadata: response };
+    }
+    const urls = extractUrls(response);
+    if (urls.length === 0) {
+        throw new AiRuntimeError('empty_result', `PPIO response has no media URL (task_id=${taskId ?? 'unknown'})`);
+    }
+    return { status: 'completed', url: urls.join('|||'), taskId, metadata: response };
+}
+export async function continuePolling(input) {
+    const finalPayload = await pollTask(input);
+    const urls = extractUrls(finalPayload);
+    if (urls.length === 0) {
+        throw new AiRuntimeError('empty_result', `PPIO response has no media URL (task_id=${input.taskId})`);
+    }
+    return { status: 'completed', url: urls.join('|||'), taskId: input.taskId, metadata: finalPayload };
+}
+async function sendJson(input, endpoint) {
+    const response = await input.runtime.transport.fetch(endpoint, {
+        method: input.method.toUpperCase() === 'GET' ? 'GET' : 'POST',
+        headers: {
+            Authorization: `Bearer ${input.apiKey}`,
+            'Content-Type': 'application/json',
+        },
+        body: input.method.toUpperCase() === 'GET' ? undefined : JSON.stringify(input.body),
+        signal: input.signal,
+    });
+    return await readJsonResponse(response, 'PPIO');
+}
+async function pollTask(input) {
+    return await pollUntilResult(input, async () => {
+        const response = await input.runtime.transport.fetch(`${PPIO_BASE_URL}/async/task-result?task_id=${encodeURIComponent(input.taskId)}`, {
+            headers: { Authorization: `Bearer ${input.apiKey}` },
+            signal: input.signal,
+        });
+        const payload = await readJsonResponse(response, 'PPIO');
+        const state = stringAt(payload, '/task/status') ?? '';
+        if (state === 'TASK_STATUS_SUCCEED')
+            return payload;
+        if (state === 'TASK_STATUS_FAILED') {
+            throw new AiRuntimeError('provider_task_failed', extractTaskFailureReason(payload));
+        }
+        return undefined;
+    });
+}
+function extractTaskId(payload) {
+    return stringAt(payload, '/task_id') ?? stringAt(payload, '/task/task_id') ?? stringAt(payload, '/data/task_id');
+}
+function extractUrls(payload) {
+    const urls = [];
+    for (const pointer of ['/images', '/image_urls', '/videos', '/audios', '/task/output/images', '/task/output/image_urls', '/task/output/videos', '/task/output/audios', '/data/images', '/data/image_urls', '/data/videos', '/data/audios']) {
+        extractStringArray(getPointer(payload, pointer), urls);
+    }
+    if (urls.length > 0)
+        return urls;
+    for (const pointer of ['/url', '/image_url', '/video_url', '/audio_url', '/demo_audio_url', '/audio', '/output', '/task/output/url', '/task/output/image_url', '/task/output/video_url', '/task/output/audio_url', '/task/output/demo_audio_url', '/task/output/audio', '/data/url', '/data/image_url', '/data/video_url', '/data/audio_url', '/data/demo_audio_url', '/data/audio']) {
+        const url = stringAt(payload, pointer);
+        if (url)
+            pushUniqueUrl(urls, url);
+    }
+    return urls;
+}
+function extractStringArray(value, target) {
+    if (!Array.isArray(value))
+        return;
+    for (const item of value) {
+        if (typeof item === 'string') {
+            pushUniqueUrl(target, item);
+        }
+        else {
+            for (const key of ['url', 'image_url', 'video_url', 'audio_url', 'demo_audio_url']) {
+                const url = getPointer(item, `/${key}`);
+                if (typeof url === 'string') {
+                    pushUniqueUrl(target, url);
+                    break;
+                }
+            }
+        }
+    }
+}
+function extractTaskFailureReason(payload) {
+    for (const pointer of ['/task/reason', '/task/message', '/task/error', '/message', '/error', '/reason', '/task/output/message', '/task/output/error', '/task/extra/debug_info/message', '/task/extra/debug_info/error']) {
+        const value = getPointer(payload, pointer);
+        if (typeof value === 'string' && value.trim())
+            return value;
+    }
+    return 'task failed';
+}

package/dist/providers/provider-fetch.d.ts

@@ -0,0 +1,7 @@
+import type { Transport } from '../runtime/Transport.js';
+export declare function fetchProvider(provider: string, endpoint: string, init: RequestInit, options: {
+    transport: Transport;
+    retryPreconnectOnce: boolean;
+    fallbackEndpoints?: readonly string[];
+    onEndpointReached?: (endpoint: string) => void;
+}): Promise<Response>;

package/dist/providers/provider-fetch.js

@@ -0,0 +1,42 @@
+import { AiRuntimeError } from '../runtime/AiRuntimeError.js';
+import { describeNetworkFailure, shouldRetry } from '../runtime/retry.js';
+function isAbort(error, signal) {
+    return Boolean(signal?.aborted)
+        || (error instanceof Error && error.name === 'AbortError');
+}
+export async function fetchProvider(provider, endpoint, init, options) {
+    const endpoints = [endpoint, ...(options.fallbackEndpoints ?? []).filter((value) => value !== endpoint)];
+    let lastFailure;
+    for (let index = 0; index < endpoints.length; index += 1) {
+        try {
+            const response = await options.transport.fetch(endpoints[index], init);
+            options.onEndpointReached?.(endpoints[index]);
+            return response;
+        }
+        catch (error) {
+            if (isAbort(error, init.signal ?? undefined))
+                throw error;
+            const failure = describeNetworkFailure(error);
+            lastFailure = failure;
+            const isSafePreconnectFailure = shouldRetry(error, 'safe-preconnect');
+            if (isSafePreconnectFailure && index < endpoints.length - 1)
+                continue;
+            if (options.retryPreconnectOnce && isSafePreconnectFailure) {
+                await new Promise((resolve) => setTimeout(resolve, 250));
+                try {
+                    const response = await options.transport.fetch(endpoints[index], init);
+                    options.onEndpointReached?.(endpoints[index]);
+                    return response;
+                }
+                catch (retryError) {
+                    if (isAbort(retryError, init.signal ?? undefined))
+                        throw retryError;
+                    lastFailure = describeNetworkFailure(retryError);
+                }
+            }
+            break;
+        }
+    }
+    const failure = lastFailure ?? { code: 'UNKNOWN_NETWORK_ERROR', message: 'Unknown network failure' };
+    throw new AiRuntimeError('provider_network_error', `${provider} 网络连接失败（${failure.code}），请检查网络后重试`);
+}

package/dist/providers/types.d.ts

@@ -0,0 +1,6 @@
+import type { ProviderContinuePollingInput, ProviderExecutionInput, ProviderExecutionResult } from '../types/runtime.js';
+/** 单个生成供应商的执行协议；不包含目录或宿主状态。 */
+export interface ProviderAdapter {
+    execute(input: ProviderExecutionInput): Promise<ProviderExecutionResult>;
+    continuePolling(input: ProviderContinuePollingInput): Promise<ProviderExecutionResult>;
+}

package/dist/providers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/providers/volcengine.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderContinuePollingInput, ProviderExecutionInput, ProviderExecutionResult } from '../types/runtime.js';
+export declare function execute(input: ProviderExecutionInput): Promise<ProviderExecutionResult>;
+export declare function continuePolling(_input: ProviderContinuePollingInput): Promise<ProviderExecutionResult>;

package/dist/providers/volcengine.js

@@ -0,0 +1,32 @@
+import { AiRuntimeError } from '../runtime/AiRuntimeError.js';
+import { collectDeepUrls, normalizeEndpoint, readJsonResponse, stringAt } from './helpers.js';
+import { fetchProvider } from './provider-fetch.js';
+const VOLCENGINE_BASE_URL = 'https://ark.cn-beijing.volces.com';
+export async function execute(input) {
+    const response = await fetchProvider('Volcengine Ark', normalizeEndpoint(VOLCENGINE_BASE_URL, input.route), {
+        method: input.method,
+        headers: {
+            Authorization: `Bearer ${input.apiKey}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(input.body),
+        signal: input.signal,
+    }, {
+        transport: input.runtime.transport,
+        retryPreconnectOnce: true,
+    });
+    const payload = await readJsonResponse(response, 'Volcengine Ark');
+    const errorMessage = stringAt(payload, '/error/message') ?? stringAt(payload, '/message');
+    if (stringAt(payload, '/error/code') || stringAt(payload, '/code')) {
+        throw new AiRuntimeError('provider_task_failed', errorMessage ?? 'Volcengine Ark generation failed');
+    }
+    const urls = [];
+    collectDeepUrls(payload, urls);
+    if (urls.length === 0) {
+        throw new AiRuntimeError('empty_result', 'Volcengine Ark response has no image URL');
+    }
+    return { status: 'completed', url: urls.join('|||'), metadata: payload };
+}
+export async function continuePolling(_input) {
+    throw new AiRuntimeError('unsupported_provider', 'Volcengine Ark image models use synchronous generation');
+}

package/dist/runtime/AiRuntimeError.d.ts

@@ -0,0 +1,5 @@
+export declare class AiRuntimeError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function cancelledError(requestId: string): AiRuntimeError;

package/dist/runtime/AiRuntimeError.js

@@ -0,0 +1,11 @@
+export class AiRuntimeError extends Error {
+    code;
+    constructor(code, message) {
+        super(`[${code}] ${message}`);
+        this.name = 'AiRuntimeError';
+        this.code = code;
+    }
+}
+export function cancelledError(requestId) {
+    return new AiRuntimeError('cancelled', `Task cancelled: ${requestId}`);
+}

package/dist/runtime/CredentialStore.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 凭据用途（不是持久化命名空间）。SDK 用它说明当前能力为什么需要密钥；宿主可以像痕迹AI
+ * 一样把同一供应商的 generation / llm / speech-recognition 映射到同一个凭据槽，也可以按
+ * 租户、区域或插件边界拆分。SDK 不对宿主的存储结构作假设。
+ *
+ * 不写成闭合联合 `'generation' | 'llm'`，而是「内置字面量 + 可扩展」——这是
+ * docs/task/模型SDK抽离/重要记录.md 记录 005 定的可扩展类型原则：SDK 是要被多个项目消费的
+ * 独立包，闭合联合意味着任何新增的凭据空间（例如未来的语音识别模型、或消费方自定义的
+ * 私有供应商分组）都要求先改 SDK 类型定义再发版。开放字符串交叉类型保留了内置值的
+ * 字面量提示（IDE 能补全 `'generation'`/`'llm'`），同时允许传入任意字符串而不报类型错误。
+ */
+type ExtensibleString = string & Record<never, never>;
+export type CredentialScope = 'generation' | 'llm' | 'speech-recognition' | 'translation' | ExtensibleString;
+/**
+ * `CredentialStore` 是 SDK 读取供应商 API Key 的唯一入口。
+ *
+ * 为什么必须由宿主提供：凭据的存储与加密方式在三个目标运行时里完全不同——
+ * Electron 用 `safeStorage`（依赖操作系统级密钥库：macOS Keychain / Windows DPAPI）
+ * 加密后存本地文件；Tauri 计划用 `stronghold` 或系统 keyring 插件；UXP 只有
+ * `SecureStorage`，且官方文档明确其定位「更像缓存而非持久存储」（key 本身不加密，
+ * 建议把它存的数据设计成"丢失后可以重新生成"）。这些差异不可能被 SDK 抽象掉，
+ * 只能交给宿主各自实现。
+ *
+ * `get()` 的返回值刻意允许同步值（`string | undefined`）或异步值
+ * （`Promise<string | undefined>`）——多数宿主的凭据读取是同步的（Electron 的
+ * `safeStorage.decryptString` 是同步调用），强制包一层 `Promise` 只是徒增一次
+ * microtask 开销；但 UXP `SecureStorage` 的 API 是异步的，所以不能收窄成纯同步签名。
+ * 调用方应统一 `await`（`await store.get(...)` 对同步返回值同样成立）。
+ *
+ * 取不到密钥（未配置、或密钥损坏无法解密——见
+ * `electron/main/services/keystore.ts` 的 `decryptStoredKey`：旧密钥解不开时按
+ * "未配置" 处理而不是抛错）一律返回 `undefined`，不抛异常。这对应
+ * docs/task/模型SDK抽离/重要记录.md 记录 010 的运行时约束：UXP `SecureStorage`
+ * 随时可能"取不到"（缓存被清），`CredentialStore` 的调用方（SDK 内部的供应商适配器）
+ * 不能假设一次取到凭据之后它就一直可用，必须始终按"可能拿不到，需要引导用户重新配置"
+ * 的路径处理，而不是把这种情况当成需要中断整个应用的异常。
+ */
+export interface CredentialStore {
+    /**
+     * 读取指定作用域下某个供应商的 API Key。
+     * @param scope 凭据作用域，见 {@link CredentialScope}
+     * @param providerId 供应商 id（如 `'ppio'`、`'fal'`、`'openai'`）
+     * @returns 密钥明文；未配置或无法读取时返回 `undefined`（不抛异常）
+     */
+    get(scope: CredentialScope, providerId: string): Promise<string | undefined> | string | undefined;
+}
+export {};

package/dist/runtime/CredentialStore.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/Logger.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 单条日志调用附带的结构化元信息。
+ *
+ * 字段结构刻意对齐主进程现有 `electron/main/services/logging/main-logger.ts` 的
+ * `MainLoggerMeta`（`createMainLogger(domain).info(message, meta)` 的 `meta` 参数），
+ * 这样 Electron 侧的 `Logger` 实现（见 `electron/main/services/ai-runtime/sdk-runtime.ts`）
+ * 可以把调用原样转发给 `createMainLogger` 得到的实例，不需要在中间写一层字段映射/改名代码。
+ */
+export interface LogContext {
+    /** 结构化事件名，如 `'ai_runtime.generate.start'`；不传时由宿主实现自行推断。 */
+    event?: string;
+    /** 单次生成/调用的请求 id，用于按链路串联同一次任务的多条日志。 */
+    requestId?: string;
+    /** 供应商侧的任务 id（轮询场景常用）。 */
+    taskId?: string;
+    /** 触发本次日志的模型 id。 */
+    modelId?: string;
+    /** 触发本次日志的供应商 id。 */
+    providerId?: string;
+    /** 任意结构化上下文数据；宿主侧的日志实现负责脱敏（如 API Key、Authorization 头）与截断。 */
+    context?: unknown;
+    /** 错误对象或错误相关数据，通常配合 `error()` 使用。 */
+    error?: unknown;
+}
+/**
+ * `Logger` 是 SDK 内部结构化日志的唯一出口。SDK 不直接 `console.log`，
+ * 也不假设任何具体的日志落盘/上报方式——三个目标运行时的日志基础设施完全不同：
+ * Electron 主进程把日志落盘为 `henji-*.log` 文件并推送给渲染层的日志查看器；
+ * Tauri 可能用 `tauri-plugin-log` 或直接转发到前端；UXP 插件的诊断信息大多只能
+ * 输出到 Photoshop 的开发者控制台。这层差异必须留给宿主决定。
+ *
+ * 只暴露 `info`/`warn`/`error` 三个级别（不含主进程 `MainLogger` 里的 `trace`/`debug`）——
+ * SDK 侧的日志需求目前只有"正常流程记录"“可恢复的异常”“需要关注的失败”三档，
+ * 更细的级别留给宿主的日志实现内部决定要不要再细分。
+ */
+export interface Logger {
+    info(message: string, ctx?: LogContext): void;
+    warn(message: string, ctx?: LogContext): void;
+    error(message: string, ctx?: LogContext): void;
+}
+/**
+ * 缺省日志实现：什么都不做。
+ *
+ * 消费方（尤其是先写的单测、或还没接好宿主日志系统的早期集成）不应该被强制先实现一个
+ * `Logger` 才能跑起来——`RuntimeContext.logger` 缺省用这个实现即可安全运行。
+ */
+export declare const noopLogger: Logger;

package/dist/runtime/Logger.js

@@ -0,0 +1,11 @@
+/**
+ * 缺省日志实现：什么都不做。
+ *
+ * 消费方（尤其是先写的单测、或还没接好宿主日志系统的早期集成）不应该被强制先实现一个
+ * `Logger` 才能跑起来——`RuntimeContext.logger` 缺省用这个实现即可安全运行。
+ */
+export const noopLogger = {
+    info: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+};

package/dist/runtime/MediaReader.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 读取一段媒体二进制数据后的产物：字节内容 + 供上传/内联使用的元信息。
+ */
+export interface MediaBinary {
+    bytes: Uint8Array;
+    mimeType: string;
+    filename: string;
+}
+/**
+ * `MediaReader` 是 SDK 把「用户在界面上选中的媒体」转换成「可以放进供应商请求体的字节」
+ * 的唯一入口。供应商适配器上传本地图片/视频/音频前，统一先经过这一步，再决定是转成
+ * `data:` URI 内联、还是调用供应商的文件上传接口换一个公网 URL。
+ *
+ * 为什么必须由宿主提供：`ref` 指向的资源在三个目标运行时里对应完全不同的读取方式——
+ * - **Electron**：`ref` 通常是本地文件系统绝对路径（如 `/Users/x/image.png`），读取即
+ *   `fs.readFileSync`；也可能是渲染层已经生成好的 `data:` URI（用户从剪贴板粘贴、或
+ *   画布节点导出的内联图片），此时直接解析 base64 payload，不涉及文件系统。
+ * - **Tauri**：本地路径需要经 Tauri 的文件系统 API（`@tauri-apps/plugin-fs`）读取，
+ *   受 `tauri.conf.json` 的文件系统作用域（scope）限制，不能像 Electron 一样无限制访问
+ *   任意路径。
+ * - **UXP（Photoshop）**：`ref` 很可能根本不对应一个磁盘文件，而是指向当前打开的 PS 文档
+ *   或某个图层——读取过程是调用 `imaging.getPixels()`/文档导出 API 把画面栅格化导出为
+ *   PNG/JPEG 字节，是一次"渲染"而不是一次"文件读取"。这是三者中差异最大的一种实现，
+ *   `ref` 语义在 UXP 侧需要扩展为可以表达"文档/图层引用"而不仅是路径字符串
+ *   （具体扩展方式留给消费 UXP 的任务决定，本接口的 `ref: string` 是三个宿主的最小公分母）。
+ *
+ * `ref` 的语义与 SDK 迁移前的 Electron 媒体预处理契约保持一致，支持两类输入：
+ * 1. `data:` URI（`data:image/png;base64,....`）——直接解析，不触碰文件系统。
+ * 2. 本地路径（含 `file://` 等本地协议前缀，或裸的绝对/相对路径）——按宿主的文件读取能力
+ *    取出字节。
+ *
+ * 不支持的输入（远程 `http(s)://` URL、`blob:` URL）不应该传给 `MediaReader.read()`——
+ * 远程 URL 应该原样透传给供应商，`blob:` URL 在后端运行时本来就不可解析，这两类的过滤
+ * 是调用方（SDK 内部）的职责，不是 `MediaReader` 要处理的输入。
+ */
+export interface MediaReader {
+    /**
+     * 读取 `ref` 指向的媒体，返回字节与元信息。
+     * @param ref 本地路径或 `data:` URI，语义见上方接口注释
+     * @throws 当 `ref` 无法解析（既不是合法 `data:` URI 也不是宿主能读取的本地引用）
+     *         或读取失败（文件不存在、无权限、文档导出失败等）时应该 `throw`，
+     *         不要返回空字节——调用方无法安全地把"读取失败"和"空文件"区分开。
+     */
+    read(ref: string): Promise<MediaBinary>;
+}

package/dist/runtime/MediaReader.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/RealtimeTransport.d.ts

@@ -0,0 +1,22 @@
+export type RealtimePayload = string | Uint8Array;
+export interface RealtimeConnectOptions {
+    protocols?: string | readonly string[];
+    headers?: Readonly<Record<string, string>>;
+    signal?: AbortSignal;
+}
+export interface RealtimeMessage {
+    data: RealtimePayload;
+}
+/**
+ * 宿主提供的单条实时连接。SDK 只依赖消息、发送和关闭三项最小语义，
+ * 不直接依赖浏览器 WebSocket、Node ws 或 Tauri 插件的具体对象。
+ */
+export interface RealtimeConnection {
+    readonly messages: AsyncIterable<RealtimeMessage>;
+    send(data: RealtimePayload): Promise<void> | void;
+    close(code?: number, reason?: string): Promise<void> | void;
+}
+/** HTTP 之外的实时双向传输入口，由宿主按自己的网络权限实现。 */
+export interface RealtimeTransport {
+    connect(url: string, options?: RealtimeConnectOptions): Promise<RealtimeConnection>;
+}

package/dist/runtime/RealtimeTransport.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/RuntimeContext.d.ts

@@ -0,0 +1,26 @@
+import type { CredentialStore } from './CredentialStore.js';
+import { type Logger } from './Logger.js';
+import type { MediaReader } from './MediaReader.js';
+import { type Tracer } from './Tracer.js';
+import type { Transport } from './Transport.js';
+import type { RealtimeTransport } from './RealtimeTransport.js';
+/** SDK 可移植运行时需要宿主提供的能力集合。 */
+export interface RuntimeContext {
+    transport: Transport;
+    /** 仅实时能力需要；不使用实时模型的消费方无需实现。 */
+    realtime?: RealtimeTransport;
+    credentials: CredentialStore;
+    media: MediaReader;
+    logger?: Logger;
+    tracer?: Tracer;
+}
+export interface ResolvedRuntimeContext {
+    transport: Transport;
+    realtime?: RealtimeTransport;
+    credentials: CredentialStore;
+    media: MediaReader;
+    logger: Logger;
+    tracer: Tracer;
+}
+/** 补齐可选的日志与追踪能力，供供应商实现统一消费。 */
+export declare function resolveRuntimeContext(context: RuntimeContext): ResolvedRuntimeContext;

package/dist/runtime/RuntimeContext.js

@@ -0,0 +1,13 @@
+import { noopLogger } from './Logger.js';
+import { noopTracer } from './Tracer.js';
+/** 补齐可选的日志与追踪能力，供供应商实现统一消费。 */
+export function resolveRuntimeContext(context) {
+    return {
+        transport: context.transport,
+        realtime: context.realtime,
+        credentials: context.credentials,
+        media: context.media,
+        logger: context.logger ?? noopLogger,
+        tracer: context.tracer ?? noopTracer,
+    };
+}

package/dist/runtime/Tracer.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 一次追踪 span 的最小上下文：给定名称，返回一个用于结束该 span 的句柄。
+ *
+ * 这是刻意最小化的公共契约：生成、LLM 流式与 LLM 模型步只报告通用 span 生命周期，
+ * 不携带痕迹AI 助手专属的 thread/turn/context compaction 等结构。
+ */
+export interface TraceSpan {
+    /** 结束该 span。`error` 为可选的失败原因；不传表示正常结束。 */
+    end(error?: unknown): void;
+}
+/**
+ * `Tracer` 是 SDK 内部可选的调用链追踪出口。
+ *
+ * 为什么由宿主提供：追踪数据最终要汇入哪个系统是宿主决定的。痕迹AI 的助手 trace
+ * 按重要记录 014 明确保留在应用侧；其他宿主可能接入 APM，也可能完全不追踪。
+ * SDK 内部不对最终去向做任何假设。
+ */
+export interface Tracer {
+    /** 开始一个 span，返回用于结束它的句柄。 */
+    startSpan(name: string, attributes?: Record<string, unknown>): TraceSpan;
+}
+/**
+ * 缺省追踪实现：不追踪任何东西，`end()` 是空操作。
+ * 与 `noopLogger` 同理——`RuntimeContext.tracer` 缺省用这个实现即可安全运行。
+ */
+export declare const noopTracer: Tracer;

package/dist/runtime/Tracer.js

@@ -0,0 +1,7 @@
+/**
+ * 缺省追踪实现：不追踪任何东西，`end()` 是空操作。
+ * 与 `noopLogger` 同理——`RuntimeContext.tracer` 缺省用这个实现即可安全运行。
+ */
+export const noopTracer = {
+    startSpan: () => ({ end: () => undefined }),
+};

package/dist/runtime/Transport.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `Transport` 是 SDK 发起网络请求时唯一依赖的宿主能力。
+ *
+ * 为什么必须由宿主提供：三个目标运行时的“发请求”方式并不等价——
+ * Electron 主进程可以直接用全局 `fetch`（Node 18+/undici），但 Tauri 需要经
+ * `@tauri-apps/plugin-http` 才能绕开浏览器 CORS 限制访问任意供应商域名，UXP 则完全没有
+ * 全局 `fetch`，必须走其网络模块。SDK 内部因此不能直接调用全局 `fetch`，只能通过这一层
+ * 窄接口让宿主决定“怎么发出去”。
+ *
+ * 接口本身只做一件事：接一个 URL + `RequestInit`，返回标准 `Response`。刻意不在这里放
+ * 超时、重试、多端点回退这些策略——它们是“调用方希望怎么用这个能力”，不是“这个能力是什么”，
+ * 塞进接口会让每个宿主实现都被迫重新实现一遍相同的策略。
+ *
+ * ## 为什么 `retryPreconnectOnce` 语义不进接口
+ *
+ * SDK 的 `providers/provider-fetch.ts` 中有一段“仅对尚未建立连接的失败重试一次”的逻辑
+ * （`SAFE_PRECONNECT_RETRY_CODES`：
+ * DNS 解析失败、连接超时、连接被拒绝等）。这段逻辑必须留在 SDK 内部作为一个**可选的高阶包装
+ * 函数**（例如 `retryPreconnectOnce(transport, ...)`），包在 `Transport.fetch` 外层调用，
+ * 而不是塞进 `Transport` 接口定义本身，原因是：
+ *
+ * 1. 这条重试策略只在“请求还没有送达供应商服务器”时才安全——一旦 TCP/TLS 握手已完成、
+ *    请求体已经发出去，供应商可能已经收到并开始处理（部分供应商是先扣费/建任务再返回结果）。
+ *    对这类失败重放请求，等于用同一份参数再次触发一次可能被计费的生成任务，这是绝对不能接受的
+ *    副作用；因此重试的判断依据是“错误码是否只可能发生在建连阶段”，这是一条业务规则，
+ *    不是网络层的通用能力，不该固化进传输接口。
+ * 2. 不同宿主的错误码体系不同（Node undici 用 `ENOTFOUND`/`ECONNREFUSED` 这类 libuv 错误码，
+ *    Tauri/UXP 的错误形状完全不同），把这条策略放接口里意味着每个宿主实现都要重新甄别
+ *    "预连接失败" 与 "已连接后失败"，而放在 SDK 侧的包装函数里，只需要宿主实现如实抛出
+ *    原始错误（不吞、不改写），策略判断留给统一的一处代码。
+ * 3. 接口越窄，越容易在 UXP 这类能力受限的宿主上实现——`Transport` 只要求宿主能发一个请求、
+ *    返回一个 `Response`，任何网络层都能满足。
+ */
+export interface Transport {
+    /**
+     * 发起一次网络请求，语义与标准 `fetch(url, init)` 完全一致：
+     * - 网络失败（DNS、连接被拒绝、超时等）应该 `throw`，而不是返回一个“失败态”的 `Response`。
+     * - HTTP 层面的失败（4xx/5xx）应该正常 `resolve` 出一个 `ok === false` 的 `Response`，
+     *   由调用方决定如何解读响应体，`Transport` 不对业务语义做任何判断。
+     * - `init.signal`（`AbortSignal`）必须被尊重：取消时应该尽快让返回的 Promise reject。
+     */
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+}

package/dist/runtime/Transport.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/error-classify.d.ts

@@ -0,0 +1,7 @@
+import { ProviderModelStepError, type ProviderErrorContext } from './provider-error-core.js';
+export { describeNetworkFailure, shouldRetry } from './retry.js';
+export type { NetworkFailure, RetryMode } from './retry.js';
+export declare function normalizeProviderError(input: ProviderErrorContext, error: unknown): ProviderModelStepError;
+export declare function createCredentialError(input: ProviderErrorContext): ProviderModelStepError;
+export declare function createCancelledError(input: ProviderErrorContext): ProviderModelStepError;
+export declare function isAgentSemanticRetryable(error: unknown): boolean;