@armadra/agent 0.0.0-stage → 0.2.1

package/dist/ai/apis/openai-compat.js

@@ -0,0 +1,142 @@
+/**
+ * OpenAI 兼容线的 compat 推断（设计 §3.3）。
+ *
+ * 顺序：保守缺省 ← 推断表（先按 provider id，再按 baseUrl 子串）← `provider.compat` ←
+ * `model.compat`（字段级覆盖，undefined 不覆盖）。显式配置永远胜过推断。
+ *
+ * 缺省是「最保守的 OpenAI 兼容服务」：`max_tokens`、`system` 角色、不发 `store` /
+ * `reasoning_effort` / `strict`。只有 OpenAI 官方端点打开 OpenAI 专有开关。
+ * 表里每一项都应对应一个已验证的差异（文档或真实样本）；没验证过的不要加。
+ */
+export const OPENAI_COMPAT_KEYS = [
+    "maxTokensField",
+    "supportsDeveloperRole",
+    "supportsUsageInStreaming",
+    "supportsFinishReason",
+    "supportsReasoningEffort",
+    "thinkingFormat",
+    "thinkingTokenBudgetField",
+    "requiresReasoningContentOnAssistantMessages",
+    "requiresToolResultName",
+    "requiresAssistantAfterToolResult",
+    "supportsMidConvoSystemMessages",
+    "cacheControlFormat",
+    "supportsStrictTools",
+    "supportsStore",
+];
+export const CONSERVATIVE_COMPAT = {
+    maxTokensField: "max_tokens",
+    supportsDeveloperRole: false,
+    supportsUsageInStreaming: true,
+    supportsFinishReason: true,
+    supportsReasoningEffort: false,
+    thinkingFormat: "openai",
+    requiresReasoningContentOnAssistantMessages: false,
+    requiresToolResultName: false,
+    requiresAssistantAfterToolResult: false,
+    supportsMidConvoSystemMessages: false,
+    cacheControlFormat: "none",
+    supportsStrictTools: false,
+    supportsStore: false,
+};
+/** 推断表：13 家内置里走 OpenAI 兼容线的 11 家（anthropic / google 不走本协议）。 */
+export const INFERENCE_RULES = [
+    {
+        provider: "openai",
+        baseUrl: "api.openai.com",
+        patch: () => ({
+            maxTokensField: "max_completion_tokens",
+            supportsDeveloperRole: true,
+            supportsReasoningEffort: true,
+            supportsStrictTools: true,
+            supportsStore: true,
+        }),
+    },
+    {
+        provider: "deepseek",
+        baseUrl: "deepseek.com",
+        patch: () => ({
+            supportsReasoningEffort: true,
+            thinkingFormat: "deepseek",
+            requiresReasoningContentOnAssistantMessages: true,
+        }),
+    },
+    {
+        provider: "moonshot",
+        baseUrl: "moonshot.",
+        patch: () => ({ thinkingFormat: "deepseek", supportsMidConvoSystemMessages: true }),
+    },
+    { provider: "zhipu", baseUrl: "bigmodel.cn", patch: () => ({ thinkingFormat: "zai" }) },
+    {
+        provider: "dashscope",
+        baseUrl: "dashscope",
+        patch: () => ({ thinkingFormat: "qwen", thinkingTokenBudgetField: "thinking_budget" }),
+    },
+    {
+        provider: "openrouter",
+        baseUrl: "openrouter.ai",
+        patch: (modelId) => ({
+            maxTokensField: "max_completion_tokens",
+            supportsReasoningEffort: true,
+            thinkingFormat: "openrouter",
+            supportsDeveloperRole: modelId.startsWith("openai/") || modelId.startsWith("anthropic/"),
+            cacheControlFormat: modelId.startsWith("anthropic/") ? "anthropic" : "none",
+        }),
+    },
+    {
+        provider: "groq",
+        baseUrl: "groq.com",
+        patch: () => ({
+            maxTokensField: "max_completion_tokens",
+            supportsDeveloperRole: true,
+            supportsReasoningEffort: true,
+        }),
+    },
+    {
+        provider: "xai",
+        baseUrl: "api.x.ai",
+        patch: () => ({ maxTokensField: "max_completion_tokens", supportsReasoningEffort: true }),
+    },
+    {
+        provider: "mistral",
+        baseUrl: "mistral.ai",
+        patch: () => ({ thinkingFormat: "none", requiresToolResultName: true }),
+    },
+    { provider: "ollama", baseUrl: ":11434", patch: () => ({}) },
+    { provider: "lmstudio", baseUrl: ":1234", patch: () => ({}) },
+];
+/** 命中的推断规则（先 provider id，后 baseUrl 子串）。 */
+export function findInferenceRule(providerId, baseUrl) {
+    return (INFERENCE_RULES.find((rule) => rule.provider === providerId) ??
+        INFERENCE_RULES.find((rule) => baseUrl.toLowerCase().includes(rule.baseUrl)));
+}
+/** 从 ProviderCompat 里挑出本协议的字段（undefined 跳过）。 */
+export function pickOpenAICompat(compat) {
+    const out = {};
+    if (!compat)
+        return out;
+    for (const key of OPENAI_COMPAT_KEYS) {
+        const value = compat[key];
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+/** 推断（不含显式配置）。 */
+export function inferOpenAICompat(providerId, baseUrl, modelId) {
+    const rule = findInferenceRule(providerId, baseUrl);
+    return { ...CONSERVATIVE_COMPAT, ...(rule ? rule.patch(modelId) : {}) };
+}
+/**
+ * 完整 compat：推断 ← provider.compat ← model.compat。`provider` 缺省时只用 model
+ * 自带信息（registry 物化后的模型已把 provider.compat 合进 model.compat）。
+ */
+export function detectCompat(model, provider) {
+    const providerId = provider?.id ?? model.provider;
+    const baseUrl = model.baseUrl ?? provider?.baseUrl ?? "";
+    return {
+        ...inferOpenAICompat(providerId, baseUrl, model.id),
+        ...pickOpenAICompat(provider?.compat),
+        ...pickOpenAICompat(model.compat),
+    };
+}

package/dist/ai/apis/openai-completions.d.ts

@@ -0,0 +1,28 @@
+/**
+ * openai-completions 协议（设计 §3.1、§3.3）：POST `{baseUrl}/chat/completions`（stream），
+ * `data:` 块 → 事件，`data: [DONE]` 结束。
+ *
+ * - 文本：`delta.content`；思考：`delta.reasoning_content` / `reasoning` / `reasoning_text`
+ *   取第一个非空字段，字段名记进 `thinkingSignature`（回放时放回同名字段）；
+ * - 工具调用增量按 `index` 拼接；缺 index 按 `id`；两者都缺则续到最近一个工具调用；
+ * - usage 三个位置：`chunk.usage`（标准）、`chunk.x_groq.usage`（Groq）、`choices[0].usage`
+ *   （Moonshot）；缓存命中三种字段：`prompt_tokens_details.cached_tokens`（OpenAI /
+ *   OpenRouter）、`prompt_cache_hit_tokens`（DeepSeek）、顶层 `cached_tokens`（Moonshot）；任一缓存
+ *   字段出现（含 0）即 `cacheReported: true`，都没有为 false（第三波 §1.6）；
+ * - 结束证据是 finish_reason 或 `[DONE]`；两者都没有 → 断流错误。finish_reason 为 stop 但
+ *   有工具调用时按 toolUse（部分本地服务如此返回）；`supportsFinishReason: false` 时完全按
+ *   内容推断。
+ */
+import type { ApiImplementation, OpenAICompletionsCompat, Usage } from "../types.js";
+type Json = Record<string, unknown>;
+/** OpenAI 兼容 usage → Usage（input 去掉缓存部分）。 */
+export declare function parseOpenAIUsage(raw: Json): Usage;
+type MappedFinish = {
+    reason: "stop" | "length" | "toolUse";
+} | {
+    reason: "error";
+    message: string;
+};
+export declare function mapFinishReason(raw: string): MappedFinish;
+export declare const openAICompletionsApi: ApiImplementation<OpenAICompletionsCompat>;
+export {};

package/dist/ai/apis/openai-completions.js

@@ -0,0 +1,246 @@
+/**
+ * openai-completions 协议（设计 §3.1、§3.3）：POST `{baseUrl}/chat/completions`（stream），
+ * `data:` 块 → 事件，`data: [DONE]` 结束。
+ *
+ * - 文本：`delta.content`；思考：`delta.reasoning_content` / `reasoning` / `reasoning_text`
+ *   取第一个非空字段，字段名记进 `thinkingSignature`（回放时放回同名字段）；
+ * - 工具调用增量按 `index` 拼接；缺 index 按 `id`；两者都缺则续到最近一个工具调用；
+ * - usage 三个位置：`chunk.usage`（标准）、`chunk.x_groq.usage`（Groq）、`choices[0].usage`
+ *   （Moonshot）；缓存命中三种字段：`prompt_tokens_details.cached_tokens`（OpenAI /
+ *   OpenRouter）、`prompt_cache_hit_tokens`（DeepSeek）、顶层 `cached_tokens`（Moonshot）；任一缓存
+ *   字段出现（含 0）即 `cacheReported: true`，都没有为 false（第三波 §1.6）；
+ * - 结束证据是 finish_reason 或 `[DONE]`；两者都没有 → 断流错误。finish_reason 为 stop 但
+ *   有工具调用时按 toolUse（部分本地服务如此返回）；`supportsFinishReason: false` 时完全按
+ *   内容推断。
+ */
+import { AssistantEventStreamImpl } from "../event-stream.js";
+import { USER_AGENT, authHeaders, describeErrorJson, joinUrl, mergeHeaders } from "../http.js";
+import { readSseEvents } from "../sse.js";
+import { affinityHeaders, postWithCacheFallback, resolveCacheRetention } from "./cache-params.js";
+import { detectCompat } from "./openai-compat.js";
+import { REASONING_FIELDS, buildOpenAIRequest } from "./openai-request.js";
+import { BlockTracker, STREAM_ENDED_MESSAGE, ProviderStopError, createOutput, finishDone, finishError, requireApiKey, } from "./shared.js";
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function obj(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function str(value) {
+    return typeof value === "string" ? value : undefined;
+}
+/** OpenAI 兼容 usage → Usage（input 去掉缓存部分）。 */
+export function parseOpenAIUsage(raw) {
+    const prompt = num(raw["prompt_tokens"]) ?? 0;
+    const details = obj(raw["prompt_tokens_details"]);
+    const cacheRead = num(details?.["cached_tokens"]) ??
+        num(raw["prompt_cache_hit_tokens"]) ??
+        num(raw["cached_tokens"]) ??
+        0;
+    const cacheWrite = num(details?.["cache_write_tokens"]) ?? 0;
+    const output = num(raw["completion_tokens"]) ?? 0;
+    const cacheFields = [
+        details?.["cached_tokens"],
+        details?.["cache_write_tokens"],
+        raw["prompt_cache_hit_tokens"],
+        raw["prompt_cache_miss_tokens"],
+        raw["cached_tokens"],
+    ];
+    const usage = {
+        input: Math.max(0, prompt - cacheRead - cacheWrite),
+        output,
+        cacheRead,
+        cacheWrite,
+        totalTokens: 0,
+        cacheReported: cacheFields.some((value) => num(value) !== undefined),
+    };
+    const reasoning = num(obj(raw["completion_tokens_details"])?.["reasoning_tokens"]);
+    if (reasoning !== undefined)
+        usage.reasoning = reasoning;
+    return usage;
+}
+const ERROR_FINISH = new Set([
+    "content_filter",
+    "network_error",
+    "sensitive",
+    "model_context_window_exceeded",
+]);
+export function mapFinishReason(raw) {
+    if (raw === "length")
+        return { reason: "length" };
+    if (raw === "tool_calls" || raw === "function_call")
+        return { reason: "toolUse" };
+    if (ERROR_FINISH.has(raw))
+        return { reason: "error", message: `Provider finish_reason: ${raw}` };
+    return { reason: "stop" };
+}
+function closeProse(state, tracker) {
+    if (state.text !== undefined)
+        tracker.end(state.text);
+    if (state.thinking !== undefined)
+        tracker.end(state.thinking);
+    state.text = undefined;
+    state.thinking = undefined;
+}
+function handleToolCalls(calls, state, tracker) {
+    closeProse(state, tracker);
+    for (const raw of calls) {
+        const call = obj(raw);
+        if (!call)
+            continue;
+        const streamIndex = num(call["index"]);
+        const id = str(call["id"]) || undefined;
+        const fn = obj(call["function"]);
+        const name = str(fn?.["name"]) || undefined;
+        let target = streamIndex !== undefined ? state.toolsByIndex.get(streamIndex) : undefined;
+        if (target === undefined && id)
+            target = state.toolsById.get(id);
+        if (target === undefined && streamIndex === undefined && !id)
+            target = state.lastTool;
+        if (target === undefined || !tracker.isOpen(target)) {
+            const generated = `call_${tracker.output.content.length}_${Date.now().toString(36)}`;
+            target = tracker.startToolCall(id ?? generated, name ?? "");
+        }
+        const block = tracker.toolCallBlock(target);
+        if (block && id && block.id !== id && !state.toolsById.has(block.id))
+            block.id = id;
+        if (block && name && !block.name)
+            block.name = name;
+        if (streamIndex !== undefined)
+            state.toolsByIndex.set(streamIndex, target);
+        if (id)
+            state.toolsById.set(id, target);
+        state.lastTool = target;
+        const args = str(fn?.["arguments"]);
+        if (args)
+            tracker.appendToolArgs(target, args);
+    }
+}
+function handleChunk(chunk, state, tracker) {
+    if (chunk["error"] !== undefined) {
+        throw new Error(describeErrorJson(chunk) ?? JSON.stringify(chunk["error"]));
+    }
+    const output = tracker.output;
+    const id = str(chunk["id"]);
+    if (id && !output.responseId)
+        output.responseId = id;
+    const choices = Array.isArray(chunk["choices"]) ? chunk["choices"] : [];
+    const choice = obj(choices[0]);
+    const rawUsage = obj(chunk["usage"]) ?? obj(obj(chunk["x_groq"])?.["usage"]) ?? obj(choice?.["usage"]);
+    if (rawUsage)
+        output.usage = parseOpenAIUsage(rawUsage);
+    if (!choice)
+        return;
+    const delta = obj(choice["delta"]);
+    if (delta) {
+        const field = REASONING_FIELDS.find((name) => {
+            const value = delta[name];
+            return typeof value === "string" && value.length > 0;
+        });
+        if (field) {
+            if (state.text !== undefined) {
+                tracker.end(state.text);
+                state.text = undefined;
+            }
+            state.thinking ??= tracker.startThinking("", field);
+            tracker.appendThinking(state.thinking, delta[field]);
+        }
+        const content = str(delta["content"]);
+        if (content) {
+            if (state.thinking !== undefined) {
+                tracker.end(state.thinking);
+                state.thinking = undefined;
+            }
+            state.text ??= tracker.startText();
+            tracker.appendText(state.text, content);
+        }
+        if (Array.isArray(delta["tool_calls"]))
+            handleToolCalls(delta["tool_calls"], state, tracker);
+    }
+    const finish = str(choice["finish_reason"]);
+    if (finish) {
+        state.finish = finish;
+        output.rawStopReason = finish;
+    }
+}
+function resolveStop(state, compat, hasToolCalls) {
+    const inferred = { reason: hasToolCalls ? "toolUse" : "stop" };
+    if (!compat.supportsFinishReason || state.finish === undefined)
+        return inferred;
+    const mapped = mapFinishReason(state.finish);
+    return mapped.reason === "stop" && hasToolCalls ? inferred : mapped;
+}
+function buildHeaders(model, options) {
+    return mergeHeaders({ "content-type": "application/json", accept: "text/event-stream", "user-agent": USER_AGENT }, authHeaders(options.apiKey, model.authHeader, "authorization-bearer"), affinityHeaders(model, "openai-completions", options.sessionId, resolveCacheRetention(options.cacheRetention)), model.headers, options.headers);
+}
+async function run(stream, model, context, options) {
+    const tracker = new BlockTracker(stream, createOutput(model));
+    try {
+        const request = buildOpenAIRequest(model, context, options);
+        tracker.output.thinkingLevel = request.thinkingLevel;
+        if (request.providerThinkingLevel !== undefined) {
+            tracker.output.providerThinkingLevel = request.providerThinkingLevel;
+        }
+        const replaced = options.onPayload?.(request.body);
+        const baseUrl = model.baseUrl ?? "https://api.openai.com/v1";
+        const response = await postWithCacheFallback(model, joinUrl(baseUrl, "/chat/completions"), {
+            headers: buildHeaders(model, options),
+            body: replaced === undefined ? request.body : replaced,
+            signal: options.signal,
+            timeoutMs: options.timeoutMs,
+            onResponse: options.onResponse,
+        });
+        stream.push({ type: "start", partial: tracker.output });
+        const state = {
+            text: undefined,
+            thinking: undefined,
+            lastTool: undefined,
+            toolsByIndex: new Map(),
+            toolsById: new Map(),
+            finish: undefined,
+            sawDone: false,
+        };
+        const body = response.body;
+        for await (const sse of readSseEvents(body, options.signal)) {
+            const data = sse.data.trim();
+            if (data === "")
+                continue;
+            if (data === "[DONE]") {
+                state.sawDone = true;
+                break;
+            }
+            let chunk;
+            try {
+                chunk = obj(JSON.parse(data)) ?? {};
+            }
+            catch {
+                throw new Error(`Malformed SSE data: ${data.slice(0, 200)}`);
+            }
+            handleChunk(chunk, state, tracker);
+        }
+        if (options.signal.aborted)
+            throw new Error("aborted");
+        if (state.finish === undefined && !state.sawDone)
+            throw new Error(STREAM_ENDED_MESSAGE);
+        const stop = resolveStop(state, request.compat, tracker.hasToolCalls);
+        if (stop.reason === "error")
+            throw new ProviderStopError(stop.message);
+        finishDone(stream, tracker, model, stop.reason);
+    }
+    catch (error) {
+        finishError(stream, tracker, model, error, options.signal);
+    }
+}
+function stream(model, context, options) {
+    requireApiKey(model, options);
+    const events = new AssistantEventStreamImpl();
+    void run(events, model, context, options).finally(() => events.end());
+    return events;
+}
+export const openAICompletionsApi = {
+    id: "openai-completions",
+    stream,
+    detectCompat,
+};

package/dist/ai/apis/openai-request.d.ts

@@ -0,0 +1,35 @@
+/**
+ * openai-completions 请求体（设计 §3.1、§3.3）：消息转换、compat 开关、思考字段、缓存。
+ *
+ * compat 开关在这里生效的位置：
+ * - maxTokensField / supportsDeveloperRole / supportsUsageInStreaming（stream_options）/
+ *   supportsStore（store:false）/ supportsStrictTools（strict:true，仅对严格兼容的 schema）；
+ * - thinkingFormat：openai → reasoning_effort；openrouter → reasoning.effort；deepseek →
+ *   thinking.type（+ reasoning_effort）；zai → thinking.type（+ reasoning_effort）；qwen →
+ *   enable_thinking（+ thinkingTokenBudgetField 预算）；none → 不发；
+ * - requiresReasoningContentOnAssistantMessages：推理模型的助手消息一律带 reasoning_content；
+ * - requiresToolResultName / requiresAssistantAfterToolResult / supportsMidConvoSystemMessages；
+ * - cacheControlFormat "anthropic"：system 末、最后一个工具、最后一条 user / tool 消息打
+ *   cache_control（OpenRouter 上的 anthropic/* 模型）。
+ * 缓存（第三波 §1.3）：`prompt_cache_key = sessionId` 只在 `sendPromptCacheKey`（官方端点缺省开）时发；
+ * `long` 在 `supportsLongCacheRetention` 时发 `prompt_cache_retention: "24h"`，否则降为 short；
+ * 保留层级未指定时读 `AMA_CACHE_RETENTION`。`toolChoice: "none"`（有工具时）→ `tool_choice: "none"`。
+ */
+import { type InlineSystemUpdate } from "../context.js";
+import type { AssistantMessage, JsonSchema, Model, ModelThinkingLevel, OpenAICompletionsCompat, StreamOptions, ToolResultMessage, TranscriptContext, UserMessage } from "../types.js";
+type Json = Record<string, unknown>;
+type Conversation = UserMessage | AssistantMessage | ToolResultMessage;
+/** 思考文本回放用的字段名；thinkingSignature 记录来源字段，回放时原样放回。 */
+export declare const REASONING_FIELDS: readonly ["reasoning_content", "reasoning", "reasoning_text"];
+export declare const ASSISTANT_BRIDGE_TEXT = "Tool results received.";
+export interface OpenAIRequest {
+    body: Json;
+    compat: OpenAICompletionsCompat;
+    thinkingLevel: ModelThinkingLevel;
+    providerThinkingLevel: string | undefined;
+}
+export declare function convertMessages(model: Model, messages: readonly Conversation[], compat: OpenAICompletionsCompat, instructionRole: "system" | "developer", updates?: readonly InlineSystemUpdate[]): Json[];
+/** strict 模式要求：object 关闭 additionalProperties 且全部属性必填（递归）。 */
+export declare function isStrictCompatible(schema: JsonSchema): boolean;
+export declare function buildOpenAIRequest(model: Model, context: TranscriptContext, options: StreamOptions): OpenAIRequest;
+export {};