@armadra/agent 0.0.0-stage → 0.2.1

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 {};

package/dist/ai/thinking.js

@@ -0,0 +1,101 @@
+/**
+ * 思考级别（设计 §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。
+ */
+export const THINKING_LEVELS = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+];
+export const DEFAULT_THINKING_BUDGETS = {
+    minimal: 1024,
+    low: 2048,
+    medium: 8192,
+    high: 16384,
+    xhigh: 16384,
+};
+/** 与回答共享 max_tokens 时留给回答的最少 token。 */
+export const MIN_ANSWER_TOKENS = 1024;
+export function isThinkingLevel(value) {
+    return typeof value === "string" && THINKING_LEVELS.includes(value);
+}
+export function getSupportedLevels(model) {
+    if (!model.reasoning)
+        return ["off"];
+    return THINKING_LEVELS.filter((level) => {
+        const mapped = model.thinkingLevelMap?.[level];
+        if (mapped === null)
+            return false;
+        if (level === "xhigh")
+            return mapped !== undefined;
+        return true;
+    });
+}
+export function clampThinkingLevel(model, level) {
+    const supported = getSupportedLevels(model);
+    if (supported.includes(level))
+        return level;
+    const index = THINKING_LEVELS.indexOf(level);
+    for (let i = index + 1; i < THINKING_LEVELS.length; i++) {
+        const candidate = THINKING_LEVELS[i];
+        if (candidate !== undefined && supported.includes(candidate))
+            return candidate;
+    }
+    for (let i = index - 1; i >= 0; i--) {
+        const candidate = THINKING_LEVELS[i];
+        if (candidate !== undefined && supported.includes(candidate))
+            return candidate;
+    }
+    return supported[0] ?? "off";
+}
+/** 级别在映射表里的供应商原生值；未映射返回 undefined（调用方按协议缺省处理）。 */
+export function mappedThinkingValue(model, level) {
+    const mapped = model.thinkingLevelMap?.[level];
+    return mapped === null ? undefined : mapped;
+}
+/** 预算：映射表给数字就用数字，否则按缺省表。 */
+export function thinkingBudget(model, level) {
+    const mapped = model.thinkingLevelMap?.[level];
+    return typeof mapped === "number" ? mapped : DEFAULT_THINKING_BUDGETS[level];
+}
+/** 预算不超过 `ceiling - MIN_ANSWER_TOKENS`（不足时为 0）。 */
+export function clampBudgetToAnswerRoom(budget, ceiling) {
+    return Math.min(budget, Math.max(0, ceiling - MIN_ANSWER_TOKENS));
+}
+/**
+ * 预算型思考（Anthropic 老模型）：budget 计入 max_tokens。`requested` 是调用方要的回答上限
+ * （缺省 = 模型上限）；返回值 maxTokens ≤ model.maxTokens，budget < maxTokens；budget < 1024 时调用方应关闭思考（Anthropic 下限）。
+ */
+export function budgetedMaxTokens(modelMaxTokens, requested, budget) {
+    const maxTokens = requested === undefined ? modelMaxTokens : Math.min(requested + budget, modelMaxTokens);
+    let adjusted = budget;
+    if (maxTokens <= adjusted)
+        adjusted = clampBudgetToAnswerRoom(adjusted, maxTokens);
+    return { maxTokens, budget: Math.max(0, Math.min(adjusted, maxTokens - 1)) };
+}
+const DISCRETE_LEVELS = ["minimal", "low", "medium", "high"];
+/**
+ * 用户面级别 → 离散级别：映射表给字串就用字串（大小写不敏感），否则用级别本身；`xhigh` 落到
+ * `high`。映射值不是四个离散级别之一（例如写成了数字预算）返回 undefined，调用方改走预算。
+ */
+export function discreteThinkingLevel(model, level) {
+    const mapped = model.thinkingLevelMap?.[level];
+    if (typeof mapped === "number")
+        return undefined;
+    const value = typeof mapped === "string" ? mapped.toLowerCase() : level;
+    if (value === "xhigh")
+        return "high";
+    return DISCRETE_LEVELS.includes(value) ? value : undefined;
+}
+/** 解析请求级别：缺省 off；钳位到模型支持的级别。 */
+export function resolveThinkingLevel(model, level) {
+    return clampThinkingLevel(model, level ?? "off");
+}