@armadra/agent 0.0.0-stage → 0.3.0

package/dist/ai/providers/registry.js

@@ -0,0 +1,458 @@
+/**
+ * ProviderRegistry（设计 §3.2–§3.5）：内置供应商 + 目录 + config.json 合并、模型查找、
+ * `provider/model` 解析、key 解析、协议实现查找。实现 B0 契约 `ProviderRegistryApi`。
+ *
+ * 合并顺序：内置（builtin.ts + catalog）← config.json `providers.<id>`（字段覆盖；`headers` /
+ * `compat` 合并；`models[]` 同 id 整条替换、新 id 追加；`modelOverrides[]` 只改元数据；两者都可带
+ * 模型级 `api`，缺省沿用供应商的协议）←
+ * auth.json 条目的 `baseUrl`。内置 openai / anthropic 的 baseUrl 还可来自 `OPENAI_BASE_URL` /
+ * `ANTHROPIC_BASE_URL`（第三波 §2.3，优先级最低，`baseUrlEnv(id)` 报告是否生效）。之后「物化」每个模型：补 baseUrl / headers / compat /
+ * authHeader / requiresApiKey，让协议实现只看 Model 就能发请求。
+ *
+ * 模型引用：`provider/model-id`（model id 自身可含斜杠，如 `openrouter/anthropic/claude-…`）；
+ * 前缀不是供应商 id 时整串当 model id。无供应商前缀时全局唯一匹配；多家同名时只留已配置 key
+ * 的；仍不唯一 → ambiguous 并列出候选。模型表为空的供应商（ollama、lmstudio、未列模型的
+ * 自定义供应商）与 baseUrl 被改到非官方主机的内置供应商（中转站）接受任意 model id，按自定义
+ * 缺省合成；后者 compat 未显式配置 `sendPromptCacheKey` 时置 false。
+ *
+ * 渠道（channels.ts）：有 `channels` 的供应商，模型按首选渠道物化；`provider/model@channel` 换渠道
+ * 重新物化（协议、地址、headers、compat 取渠道的，模型级 api / baseUrl 仍覆盖）；渠道 key 经
+ * `resolveApiKey(provider, channel)`。没有 `channels` 的供应商行为不变。
+ *
+ * models.dev（enrich.ts）：config 里缺元数据的自定义模型与合成模型，用传入的索引（只读缓存）补
+ * contextWindow / maxTokens / input / reasoning / cost，来源记在 `modelMetadata()`；内置目录不补。
+ */
+import { ApiRegistry, createDefaultApiRegistry } from "../apis/api.js";
+import { fakeProviderData } from "../fake/fake-provider.js";
+import { mergeHeaders } from "../http.js";
+import { ApiKeyResolver } from "./auth.js";
+import { BUILTIN_PROVIDERS, fallbackEnvKey, isRelayedBaseUrl } from "./builtin.js";
+import { applyModelOverride, loadBuiltinCatalog, toModel, withCustomDefaults } from "./catalog.js";
+import { channelKeyId, modelChannels, parseChannels, splitChannelRef } from "./channels.js";
+import { catalogMetadata, enrichEntry, lazyIndex, } from "./enrich.js";
+/**
+ * 物化：模型补齐供应商级字段（不可变：返回新对象）。给了 `channel` 时协议与地址取渠道的（模型级
+ * `explicit` 覆盖优先），headers / compat 按 供应商 ← 渠道 ← 模型 合并，并记下渠道名。
+ */
+export function materializeModel(model, provider, channel, explicit) {
+    const out = {
+        ...model,
+        provider: provider.id,
+        baseUrl: model.baseUrl ?? provider.baseUrl,
+    };
+    if (channel !== undefined) {
+        out.api = explicit?.api ?? channel.api;
+        out.baseUrl = explicit?.baseUrl ?? channel.baseUrl;
+        out.channel = channel.name;
+    }
+    if (provider.headers || channel?.headers || model.headers)
+        out.headers = mergeHeaders(provider.headers, channel?.headers, model.headers);
+    if (provider.compat || channel?.compat || model.compat)
+        out.compat = { ...provider.compat, ...channel?.compat, ...model.compat };
+    const authHeader = channel?.authHeader ?? provider.authHeader;
+    if (authHeader !== undefined)
+        out.authHeader = model.authHeader ?? authHeader;
+    out.requiresApiKey = provider.requiresApiKey;
+    return out;
+}
+function configKeysOf(config) {
+    const keys = {};
+    for (const [id, provider] of Object.entries(config?.providers ?? {})) {
+        keys[id] = provider.apiKey;
+        for (const [name, channel] of Object.entries(provider.channels ?? {})) {
+            if (channel?.apiKey !== undefined)
+                keys[channelKeyId(id, name)] = channel.apiKey;
+        }
+    }
+    return keys;
+}
+export class ProviderRegistry {
+    warnings = [];
+    providers = new Map();
+    sources = new Map();
+    /** baseUrl 来自环境变量的供应商 → 变量名（被 config / auth.json 覆盖后删除）。 */
+    envBaseUrls = new Map();
+    /** baseUrl 指向非官方主机的内置供应商：接受目录外的 model id。 */
+    relayed = new Set();
+    /** `provider/model` → 物化前的模型（多渠道供应商切换渠道时重新物化）。 */
+    raw = new Map();
+    /** `provider/model` → 元数据来源与 models.dev 匹配。 */
+    metadata = new Map();
+    modelsDev;
+    apis;
+    keys;
+    onWarning;
+    constructor(options = {}) {
+        this.onWarning = options.onWarning;
+        this.modelsDev = lazyIndex(options.modelsDev);
+        this.apis = options.apis ?? createDefaultApiRegistry();
+        this.keys = new ApiKeyResolver({
+            ...options.keys,
+            configKeys: options.keys?.configKeys ?? configKeysOf(options.config),
+            onWarning: (message) => this.warn(message),
+        });
+        const catalog = loadBuiltinCatalog();
+        const env = options.keys?.useEnv === false ? {} : (options.keys?.env ?? process.env);
+        for (const { baseUrlEnv, ...base } of BUILTIN_PROVIDERS) {
+            const models = (catalog.get(base.id) ?? []).map((entry) => {
+                const api = entry.api ?? base.api;
+                this.sources.set(`${base.id}/${entry.id}`, "builtin");
+                const model = toModel(entry, base.id, api);
+                this.metadata.set(`${base.id}/${entry.id}`, catalogMetadata(model));
+                if (entry.api !== undefined)
+                    this.raw.set(`${base.id}/${entry.id}`, { model, explicit: { api } });
+                return model;
+            });
+            const fromEnv = baseUrlEnv !== undefined ? env[baseUrlEnv]?.trim() : undefined;
+            if (baseUrlEnv !== undefined && fromEnv)
+                this.envBaseUrls.set(base.id, baseUrlEnv);
+            this.providers.set(base.id, {
+                ...base,
+                ...(fromEnv ? { baseUrl: fromEnv } : {}),
+                models,
+                builtin: true,
+            });
+        }
+        for (const [id, config] of Object.entries(options.config?.providers ?? {})) {
+            this.applyConfig(id, config);
+        }
+        for (const provider of this.providers.values()) {
+            const baseUrl = this.keys.authEntry(provider.id)?.entry.baseUrl;
+            if (baseUrl) {
+                provider.baseUrl = baseUrl;
+                this.envBaseUrls.delete(provider.id);
+            }
+            if (provider.builtin && isRelayedBaseUrl(provider.id, provider.baseUrl)) {
+                this.relayed.add(provider.id);
+                if (provider.compat?.sendPromptCacheKey === undefined)
+                    provider.compat = { ...provider.compat, sendPromptCacheKey: false };
+            }
+        }
+        if (options.includeFake !== false && !this.providers.has("fake")) {
+            const fake = fakeProviderData();
+            for (const model of fake.models)
+                this.sources.set(`fake/${model.id}`, "builtin");
+            this.providers.set(fake.id, fake);
+        }
+        for (const provider of this.providers.values()) {
+            provider.models = provider.models.map((model) => this.materialize(provider, model));
+        }
+    }
+    warn(message) {
+        this.warnings.push(message);
+        this.onWarning?.(message);
+    }
+    /** 物化并记下原始模型；多渠道供应商用模型的首选渠道。 */
+    materialize(provider, model, channelName) {
+        const key = `${provider.id}/${model.id}`;
+        const raw = this.raw.get(key) ?? { model, explicit: {} };
+        if (!this.raw.has(key)) {
+            if (model.baseUrl !== undefined)
+                raw.explicit.baseUrl = model.baseUrl;
+            this.raw.set(key, raw);
+        }
+        if (provider.channels === undefined || provider.channels.length === 0)
+            return materializeModel(raw.model, provider);
+        const name = channelName ?? raw.model.channels?.[0] ?? provider.defaultChannel;
+        const channel = provider.channels.find((c) => c.name === name) ?? provider.channels[0];
+        return materializeModel(raw.model, provider, channel, raw.explicit);
+    }
+    applyConfig(id, config) {
+        const existing = this.providers.get(id);
+        const parsed = config.channels !== undefined ? parseChannels(id, config) : undefined;
+        for (const warning of parsed?.warnings ?? [])
+            this.warn(warning);
+        const first = parsed?.channels.find((c) => c.name === parsed.defaultChannel);
+        if (!existing && !config.baseUrl && first === undefined) {
+            this.warn(`provider "${id}" in config.json has no baseUrl; ignored`);
+            return;
+        }
+        const provider = existing ?? {
+            id,
+            name: config.name ?? id,
+            api: config.api ?? first?.api ?? "openai-completions",
+            baseUrl: config.baseUrl ?? first?.baseUrl ?? "",
+            envKeys: [fallbackEnvKey(id)],
+            models: [],
+            requiresApiKey: true,
+            builtin: false,
+        };
+        if (config.name !== undefined)
+            provider.name = config.name;
+        if (config.api !== undefined)
+            provider.api = config.api;
+        if (config.baseUrl !== undefined) {
+            provider.baseUrl = config.baseUrl;
+            this.envBaseUrls.delete(id);
+        }
+        if (parsed !== undefined && first !== undefined) {
+            // 有渠道时供应商级 api / baseUrl 取首选渠道的（discover 等单地址的用法看它）。
+            provider.channels = parsed.channels;
+            provider.defaultChannel = first.name;
+            provider.api = first.api;
+            provider.baseUrl = first.baseUrl;
+            this.envBaseUrls.delete(id);
+        }
+        if (config.envKeys !== undefined) {
+            provider.envKeys = [
+                ...config.envKeys,
+                ...provider.envKeys.filter((k) => !config.envKeys?.includes(k)),
+            ];
+        }
+        if (config.authHeader !== undefined)
+            provider.authHeader = config.authHeader;
+        if (config.headers)
+            provider.headers = mergeHeaders(provider.headers, config.headers);
+        if (config.compat)
+            provider.compat = { ...provider.compat, ...config.compat };
+        if (config.requiresApiKey !== undefined)
+            provider.requiresApiKey = config.requiresApiKey;
+        const channelsOf = (wanted, modelId) => modelChannels(wanted, provider.channels ?? [], provider.defaultChannel ?? "", (name) => this.warn(`model "${id}/${modelId}" channel "${name}" not found; ignored`));
+        for (const entry of config.models ?? []) {
+            // 模型级 api（第三波 §2.3）：同一中转下不同模型走不同协议；缺省沿用供应商（或渠道）的。
+            const { entry: filled, metadata } = enrichEntry(entry, this.modelsDev);
+            if (typeof entry.modelsDev === "string" && metadata.looked && metadata.match === undefined)
+                this.warn(`modelsDev "${entry.modelsDev}" for "${id}/${entry.id}" not found`);
+            const model = withCustomDefaults(filled, id, entry.api ?? provider.api);
+            if (provider.channels !== undefined)
+                model.channels = channelsOf(entry.channels, entry.id);
+            const index = provider.models.findIndex((m) => m.id === entry.id);
+            if (index >= 0)
+                provider.models[index] = model;
+            else
+                provider.models.push(model);
+            const key = `${id}/${entry.id}`;
+            this.raw.set(key, {
+                model,
+                explicit: {
+                    ...(entry.api !== undefined ? { api: entry.api } : {}),
+                    ...(entry.baseUrl !== undefined ? { baseUrl: entry.baseUrl } : {}),
+                },
+            });
+            this.sources.set(key, "config");
+            this.metadata.set(key, metadata);
+        }
+        for (const override of config.modelOverrides ?? []) {
+            const index = provider.models.findIndex((m) => m.id === override.id);
+            const current = provider.models[index];
+            if (!current) {
+                this.warn(`modelOverrides: "${id}/${override.id}" not found; ignored`);
+                continue;
+            }
+            const { channels, modelsDev: _md, ...fields } = override;
+            let next = applyModelOverride(current, fields);
+            if (override.api !== undefined)
+                next = { ...next, api: override.api };
+            if (channels !== undefined && provider.channels !== undefined)
+                next.channels = channelsOf(channels, override.id);
+            provider.models[index] = next;
+            const key = `${id}/${override.id}`;
+            const raw = this.raw.get(key);
+            this.raw.set(key, {
+                model: next,
+                explicit: {
+                    ...raw?.explicit,
+                    ...(override.api !== undefined ? { api: override.api } : {}),
+                    ...(override.baseUrl !== undefined ? { baseUrl: override.baseUrl } : {}),
+                },
+            });
+            const meta = this.metadata.get(key);
+            if (meta !== undefined)
+                for (const field of Object.keys(meta.sources))
+                    if (fields[field] !== undefined)
+                        meta.sources[field] = "config";
+        }
+        if (provider.channels !== undefined) {
+            // 目录模型（给内置供应商加了渠道时）挂到首选渠道。
+            for (const model of provider.models)
+                model.channels ??= [provider.defaultChannel ?? ""];
+        }
+        this.providers.set(id, provider);
+    }
+    /** baseUrl 来自哪个环境变量（未生效返回 undefined）。 */
+    baseUrlEnv(providerId) {
+        return this.envBaseUrls.get(providerId);
+    }
+    /** 内置供应商的 baseUrl 指向非官方主机（中转站）。 */
+    isRelayed(providerId) {
+        return this.relayed.has(providerId);
+    }
+    /** 模型元数据的来源与 models.dev 匹配（`ama models list` / `config show` / providers 表格）。 */
+    modelMetadata(providerId, modelId) {
+        return this.metadata.get(`${providerId}/${modelId}`);
+    }
+    list() {
+        return [...this.providers.values()];
+    }
+    get(providerId) {
+        return this.providers.get(providerId);
+    }
+    listModels() {
+        const out = [];
+        for (const provider of this.providers.values()) {
+            for (const model of provider.models) {
+                out.push({ model, provider, source: this.modelSource(provider.id, model.id) });
+            }
+        }
+        return out;
+    }
+    modelSource(providerId, modelId) {
+        return this.sources.get(`${providerId}/${modelId}`) ?? "config";
+    }
+    /** 追加 / 替换模型（例如本地枚举得到的 ollama 模型）。 */
+    addModels(providerId, models, source = "discovered") {
+        const provider = this.providers.get(providerId);
+        if (!provider)
+            return;
+        for (const raw of models) {
+            this.raw.delete(`${providerId}/${raw.id}`);
+            const model = this.materialize(provider, { ...raw, provider: providerId });
+            const index = provider.models.findIndex((m) => m.id === model.id);
+            if (index >= 0)
+                provider.models[index] = model;
+            else
+                provider.models.push(model);
+            this.sources.set(`${providerId}/${model.id}`, source);
+        }
+    }
+    synthesize(provider, modelId, channel) {
+        const key = `${provider.id}/${modelId}`;
+        const { entry, metadata } = enrichEntry({ id: modelId }, this.modelsDev);
+        if (!this.metadata.has(key))
+            this.metadata.set(key, metadata);
+        const model = withCustomDefaults(entry, provider.id, provider.api);
+        if (provider.channels !== undefined)
+            model.channels = [provider.defaultChannel ?? ""];
+        const channelData = provider.channels?.find((c) => c.name === (channel ?? model.channels?.[0]));
+        return materializeModel(model, provider, channelData);
+    }
+    /** 按渠道取模型：渠道不在模型的 channels 里 → 列出可用渠道。 */
+    withChannel(provider, model, channel) {
+        const available = model.channels ?? [];
+        if (!available.includes(channel)) {
+            return {
+                ok: false,
+                reason: "not_found",
+                candidates: available.map((c) => `${provider.id}/${model.id}@${c}`),
+            };
+        }
+        if (channel === model.channel)
+            return { ok: true, model, provider };
+        return { ok: true, model: this.materialize(provider, model, channel), provider };
+    }
+    findModel(ref) {
+        const trimmed = ref.trim();
+        const direct = this.findPlain(trimmed);
+        if (direct.ok)
+            return direct;
+        const split = splitChannelRef(trimmed);
+        if (split === undefined)
+            return direct;
+        const base = this.findPlain(split.base, split.channel);
+        if (!base.ok)
+            return base.reason === "ambiguous" ? base : direct;
+        if (!base.provider.channels?.some((c) => c.name === split.channel))
+            return direct;
+        return this.withChannel(base.provider, base.model, split.channel);
+    }
+    findPlain(trimmed, channel) {
+        const slash = trimmed.indexOf("/");
+        if (slash > 0) {
+            const provider = this.providers.get(trimmed.slice(0, slash));
+            if (provider) {
+                const id = trimmed.slice(slash + 1);
+                const model = provider.models.find((m) => m.id === id);
+                if (model)
+                    return { ok: true, model, provider };
+                if ((provider.models.length === 0 || this.relayed.has(provider.id)) && id.length > 0) {
+                    const synthesized = this.synthesize(provider, id);
+                    if (channel !== undefined && provider.channels?.some((c) => c.name === channel))
+                        synthesized.channels = [...new Set([...(synthesized.channels ?? []), channel])];
+                    return { ok: true, model: synthesized, provider };
+                }
+                return { ok: false, reason: "not_found", candidates: this.similar(id, provider.id) };
+            }
+        }
+        const matches = this.listModels().filter((entry) => entry.model.id === trimmed);
+        if (matches.length === 1 && matches[0]) {
+            return { ok: true, model: matches[0].model, provider: matches[0].provider };
+        }
+        if (matches.length === 0) {
+            return { ok: false, reason: "not_found", candidates: this.similar(trimmed) };
+        }
+        const configured = matches.filter((entry) => this.keys.hasConfiguredKey(entry.provider));
+        if (configured.length === 1 && configured[0]) {
+            return { ok: true, model: configured[0].model, provider: configured[0].provider };
+        }
+        return {
+            ok: false,
+            reason: "ambiguous",
+            candidates: (configured.length > 0 ? configured : matches).map((entry) => `${entry.provider.id}/${entry.model.id}`),
+        };
+    }
+    similar(id, providerId) {
+        const needle = id.toLowerCase();
+        return this.listModels()
+            .filter((entry) => providerId === undefined || entry.provider.id === providerId)
+            .filter((entry) => {
+            const candidate = entry.model.id.toLowerCase();
+            return needle.length > 0 && (candidate.includes(needle) || needle.includes(candidate));
+        })
+            .slice(0, 10)
+            .map((entry) => `${entry.provider.id}/${entry.model.id}`);
+    }
+    hasConfiguredKey(providerId) {
+        const provider = this.providers.get(providerId);
+        return provider ? this.keys.hasConfiguredKey(provider) : false;
+    }
+    async resolveApiKey(providerId, channel) {
+        const provider = this.providers.get(providerId);
+        if (!provider)
+            return { apiKey: undefined, source: "none" };
+        if (channel !== undefined && provider.channels?.some((c) => c.name === channel)) {
+            const own = await this.keys.resolve({
+                id: channelKeyId(provider.id, channel),
+                envKeys: [],
+                requiresApiKey: provider.requiresApiKey,
+            });
+            if (own.apiKey !== undefined)
+                return own;
+        }
+        return this.keys.resolve(provider);
+    }
+    getApi(api) {
+        return this.apis.get(api);
+    }
+}
+/** 注册表若是 ProviderRegistry（或同形状），报告 baseUrl 来自的环境变量；否则 undefined。 */
+export function baseUrlEnvOf(registry, providerId) {
+    const r = registry;
+    return typeof r.baseUrlEnv === "function" ? r.baseUrlEnv(providerId) : undefined;
+}
+/**
+ * 模型枚举：本地服务（`ama models list --provider ollama|lmstudio`）与 `ama models discover`
+ * （第三波 §2.3）共用。ollama 走 `/api/tags`，其它走 OpenAI 兼容的 `GET {baseUrl}/models`；
+ * `url` / `headers` 由调用方给出时原样使用（远端中转要带鉴权头）。失败抛错由调用方展示。
+ */
+export async function discoverLocalModels(provider, options = {}) {
+    const signal = AbortSignal.any([
+        options.signal ?? new AbortController().signal,
+        AbortSignal.timeout(options.timeoutMs ?? 5000),
+    ]);
+    const base = provider.baseUrl.replace(/\/+$/, "");
+    const isOllama = options.url === undefined && (provider.id === "ollama" || base.includes(":11434"));
+    const url = options.url ?? (isOllama ? `${base.replace(/\/v1$/, "")}/api/tags` : `${base}/models`);
+    const response = await fetch(url, {
+        signal,
+        ...(options.headers !== undefined ? { headers: options.headers } : {}),
+    });
+    if (!response.ok)
+        throw new Error(`${response.status} listing models from ${url}`);
+    const body = (await response.json());
+    const ids = isOllama
+        ? (body.models ?? []).map((m) => m.name)
+        : (body.data ?? []).map((m) => m.id);
+    return [
+        ...new Set(ids.filter((id) => typeof id === "string" && id.length > 0)),
+    ].map((id) => withCustomDefaults({ id }, provider.id, provider.api));
+}

package/dist/ai/sse.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Server-Sent Events 解析（设计 §1.2 ai/sse.ts）：event / data / id / 多行 data / 注释行 /
+ * CRLF、CR、LF 三种行尾 / UTF-8 跨块 / 首字节 BOM。
+ *
+ * 规则取自 WHATWG「Interpreting an event stream」：空行分派事件；`:` 开头是注释；字段名后的
+ * 第一个空格去掉；多条 data 以 LF 连接。为兼容不规范服务端，流结束时未以空行收尾的最后一个
+ * 事件也会分派。
+ */
+export interface SseEvent {
+    /** `event:` 字段；缺省时为 undefined（规范上视为 "message"）。 */
+    event: string | undefined;
+    data: string;
+    id: string | undefined;
+}
+export declare class SseParser {
+    private buffer;
+    private event;
+    private data;
+    private id;
+    private hasData;
+    private bomChecked;
+    /** 上一块以 CR 结尾：下一块开头的 LF 属于同一个行尾。 */
+    private pendingCr;
+    /** 喂入一段文本，返回其中完整分派的事件。 */
+    feed(chunk: string): SseEvent[];
+    /** 流结束：处理残留行，并分派未以空行收尾的事件。 */
+    flush(): SseEvent[];
+    private processLine;
+    private dispatch;
+}
+/** 从字节流读 SSE 事件；`signal` 中止时停止读取（调用方据此产出 aborted）。 */
+export declare function readSseEvents(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<SseEvent>;

package/dist/ai/sse.js

@@ -0,0 +1,140 @@
+/**
+ * Server-Sent Events 解析（设计 §1.2 ai/sse.ts）：event / data / id / 多行 data / 注释行 /
+ * CRLF、CR、LF 三种行尾 / UTF-8 跨块 / 首字节 BOM。
+ *
+ * 规则取自 WHATWG「Interpreting an event stream」：空行分派事件；`:` 开头是注释；字段名后的
+ * 第一个空格去掉；多条 data 以 LF 连接。为兼容不规范服务端，流结束时未以空行收尾的最后一个
+ * 事件也会分派。
+ */
+export class SseParser {
+    buffer = "";
+    event;
+    data = [];
+    id;
+    hasData = false;
+    bomChecked = false;
+    /** 上一块以 CR 结尾：下一块开头的 LF 属于同一个行尾。 */
+    pendingCr = false;
+    /** 喂入一段文本，返回其中完整分派的事件。 */
+    feed(chunk) {
+        let text = chunk;
+        if (!this.bomChecked && text.length > 0) {
+            this.bomChecked = true;
+            if (text.charCodeAt(0) === 0xfeff)
+                text = text.slice(1);
+        }
+        if (this.pendingCr && text.startsWith("\n"))
+            text = text.slice(1);
+        this.pendingCr = false;
+        this.buffer += text;
+        const events = [];
+        let start = 0;
+        for (let i = 0; i < this.buffer.length; i++) {
+            const ch = this.buffer.charCodeAt(i);
+            if (ch !== 10 && ch !== 13)
+                continue;
+            const line = this.buffer.slice(start, i);
+            if (ch === 13) {
+                if (i + 1 < this.buffer.length) {
+                    if (this.buffer.charCodeAt(i + 1) === 10)
+                        i++;
+                }
+                else {
+                    this.pendingCr = true;
+                }
+            }
+            start = i + 1;
+            const event = this.processLine(line);
+            if (event)
+                events.push(event);
+        }
+        this.buffer = this.buffer.slice(start);
+        return events;
+    }
+    /** 流结束：处理残留行，并分派未以空行收尾的事件。 */
+    flush() {
+        const events = [];
+        if (this.buffer.length > 0) {
+            const event = this.processLine(this.buffer);
+            if (event)
+                events.push(event);
+            this.buffer = "";
+        }
+        const last = this.dispatch();
+        if (last)
+            events.push(last);
+        return events;
+    }
+    processLine(line) {
+        if (line === "")
+            return this.dispatch();
+        if (line.startsWith(":"))
+            return undefined;
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        switch (field) {
+            case "event":
+                this.event = value;
+                break;
+            case "data":
+                this.data.push(value);
+                this.hasData = true;
+                break;
+            case "id":
+                if (!value.includes("\0"))
+                    this.id = value;
+                break;
+            default:
+                // retry 与未知字段忽略
+                break;
+        }
+        return undefined;
+    }
+    dispatch() {
+        const hadContent = this.hasData || this.event !== undefined;
+        const event = { event: this.event, data: this.data.join("\n"), id: this.id };
+        this.event = undefined;
+        this.data = [];
+        this.hasData = false;
+        return hadContent ? event : undefined;
+    }
+}
+/** 从字节流读 SSE 事件；`signal` 中止时停止读取（调用方据此产出 aborted）。 */
+export async function* readSseEvents(body, signal) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder("utf-8");
+    const parser = new SseParser();
+    const onAbort = () => {
+        reader.cancel().catch(() => undefined);
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    let drained = false;
+    try {
+        while (true) {
+            if (signal?.aborted)
+                return;
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            if (signal?.aborted)
+                return;
+            for (const event of parser.feed(decoder.decode(value, { stream: true })))
+                yield event;
+        }
+        drained = true;
+        for (const event of parser.feed(decoder.decode()))
+            yield event;
+        for (const event of parser.flush())
+            yield event;
+    }
+    finally {
+        signal?.removeEventListener("abort", onAbort);
+        // 消费者提前退出（读到终止事件即 break）或中止：取消底层流，释放连接
+        if (!drained)
+            await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+}

package/dist/ai/thinking.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 思考级别（设计 §3.6「思考」）：用户面 off / minimal / low / medium / high / xhigh。
+ *
+ * - `getSupportedLevels(model)`：非推理模型只有 off；`thinkingLevelMap[level] === null` 的级别
+ *   不支持；`xhigh` 只有在映射表里显式给出时才支持。
+ * - `clampThinkingLevel`：不支持的级别先向上找、再向下找最近的可用级别。
+ * - 预算型缺省：minimal 1024 / low 2048 / medium 8192 / high 16384（xhigh 按 high）；
+ *   与回答共享 max_tokens 时至少给回答留 1024。
+ */
+import type { Model, ModelThinkingLevel, ThinkingLevel } from "./types.js";
+export declare const THINKING_LEVELS: readonly ModelThinkingLevel[];
+export declare const DEFAULT_THINKING_BUDGETS: Readonly<Record<ThinkingLevel, number>>;
+/** 与回答共享 max_tokens 时留给回答的最少 token。 */
+export declare const MIN_ANSWER_TOKENS = 1024;
+export declare function isThinkingLevel(value: unknown): value is ModelThinkingLevel;
+type ThinkingModel = Pick<Model, "reasoning" | "thinkingLevelMap">;
+export declare function getSupportedLevels(model: ThinkingModel): ModelThinkingLevel[];
+export declare function clampThinkingLevel(model: ThinkingModel, level: ModelThinkingLevel): ModelThinkingLevel;
+/** 级别在映射表里的供应商原生值；未映射返回 undefined（调用方按协议缺省处理）。 */
+export declare function mappedThinkingValue(model: ThinkingModel, level: ModelThinkingLevel): string | number | undefined;
+/** 预算：映射表给数字就用数字，否则按缺省表。 */
+export declare function thinkingBudget(model: ThinkingModel, level: ThinkingLevel): number;
+/** 预算不超过 `ceiling - MIN_ANSWER_TOKENS`（不足时为 0）。 */
+export declare function clampBudgetToAnswerRoom(budget: number, ceiling: number): number;
+/**
+ * 预算型思考（Anthropic 老模型）：budget 计入 max_tokens。`requested` 是调用方要的回答上限
+ * （缺省 = 模型上限）；返回值 maxTokens ≤ model.maxTokens，budget < maxTokens；budget < 1024 时调用方应关闭思考（Anthropic 下限）。
+ */
+export declare function budgetedMaxTokens(modelMaxTokens: number, requested: number | undefined, budget: number): {
+    maxTokens: number;
+    budget: number;
+};
+/** 离散思考级别（Google Gemini 3 的 `thinkingLevel`）。 */
+export type DiscreteThinkingLevel = "minimal" | "low" | "medium" | "high";
+/**
+ * 用户面级别 → 离散级别：映射表给字串就用字串（大小写不敏感），否则用级别本身；`xhigh` 落到
+ * `high`。映射值不是四个离散级别之一（例如写成了数字预算）返回 undefined，调用方改走预算。
+ */
+export declare function discreteThinkingLevel(model: ThinkingModel, level: ThinkingLevel): DiscreteThinkingLevel | undefined;
+/** 解析请求级别：缺省 off；钳位到模型支持的级别。 */
+export declare function resolveThinkingLevel(model: ThinkingModel, level: ModelThinkingLevel | undefined): ModelThinkingLevel;
+export {};