@armadra/agent 0.0.0-stage → 0.3.0

package/dist/agent/types.d.ts

@@ -0,0 +1,378 @@
+/**
+ * 循环与会话对象契约（设计 §4.1、§4.3、§13.1、§13.2 事件）。[B0] 契约文件，实现归 B2。
+ *
+ * 补全与偏差：
+ * - `ContentBlock / Usage / StopReason` 等定义在 ai/types.ts，`AgentMessage` 定义在
+ *   session/types.ts（依赖方向），此处再导出，设计里「agent/types.ts 提供」的名字都能从这里拿到。
+ * - `LoopHooks.beforeToolCall` 的 `ctx` 补全为 `ToolCallGateContext`；`prepareRequest` 的
+ *   `req` 补全为 `PreparedRequest`。
+ * - `SessionEvent` 是 AgentSession.subscribe 的进程内事件；RPC / stream-json 线上形状见
+ *   src/rpc.ts（`message_update` 线上为纯增量）。
+ * - `AgentSession` 是接口；B2 的实现类不要再叫 `AgentSession`（建议 `AgentSessionImpl`），
+ *   否则与本接口在 index.ts 的再导出冲突。
+ * - 补全 `SessionState`、`SessionStats`、`CompactionResult`、`CompactionSettings`、
+ *   `RetrySettings`、`QueueMode`。
+ * - （B2 追加）`PromptOptions.origin` 与 `steer / followUp` 的可选 `EnqueueOptions`：宿主
+ *   `sendUser(text, origin)` 注入的消息要以 `origin` 落盘（§4.3）；`"user"` 等同不填。
+ * - （W3-C0）缓存可观测性（第三波 §1.10）：`SessionEvent` 加 `cache_miss` / `cache_warm` /
+ *   `context_pressure`，`SessionStats.cache`（可选，C1b 填）；`CacheSettings` 是
+ *   `SessionCacheController` 的解析后设置（来自 config `cache` 段与环境变量）。
+ */
+import type { AssistantEvent, AssistantMessage, CacheRetention, ImageBlock, Message, MessageOrigin, Model, ModelRef, ModelThinkingLevel, ToolCallBlock, ToolResultMessage, TranscriptContext, Usage } from "../ai/types.js";
+import type { CacheMiss, CacheMissReason, CacheReporting, WarmerStatus, WarmingMode } from "../ai/cache/types.js";
+import type { HookEvent } from "../hooks/types.js";
+import type { ActionPreview, ApprovalDecision, ApprovalReason, PermissionMode } from "../permissions/types.js";
+import type { AgentMessage, SessionEntry } from "../session/types.js";
+import type { ToolDefinition, ToolResult } from "../tools/types.js";
+export type { AssistantContentBlock, AssistantMessage, ContentBlock, ImageBlock, Message, StopReason, SystemMessage, TextBlock, ThinkingBlock, ToolCallBlock, ToolResultMessage, Usage, UserMessage, } from "../ai/types.js";
+export type { AgentMessage, BranchSummaryMessage, CompactionSummaryMessage, CustomMessage, } from "../session/types.js";
+export type ToolCall = ToolCallBlock;
+export interface TurnResult {
+    assistant: AssistantMessage;
+    toolResults: ToolResultMessage[];
+}
+export interface PreparedRequest {
+    context: TranscriptContext;
+    model: Model;
+    thinkingLevel: ModelThinkingLevel;
+}
+export interface ToolCallGateContext {
+    readonly signal: AbortSignal;
+    /** 产出该调用的助手消息。 */
+    readonly assistant: AssistantMessage;
+    /** 找不到工具时为 undefined（tool-runner 已先行报错，通常不会走到钩子）。 */
+    readonly tool: ToolDefinition | undefined;
+    /** 嵌套调用（工具里经 `ToolContext.tools.executeTool` 发起，例如 codemode 脚本）时的外层调用。 */
+    readonly parent?: NestedCallInfo;
+}
+/** 嵌套调用的外层：Hook 输入据此带 `parentToolCallId` 与 `viaCodemode`（设计 §5.5）。 */
+export interface NestedCallInfo {
+    readonly toolCallId: string;
+    /** 外层是 codemode 工具。 */
+    readonly viaCodemode: boolean;
+}
+export interface ToolCallGate {
+    block?: boolean;
+    reason?: string;
+    /** Hook 的 updatedInput 替换后的输入。 */
+    input?: unknown;
+}
+export interface LoopHooks {
+    /** 档一裁剪、Hook 的 additionalContext 注入。 */
+    transformContext?(messages: AgentMessage[], signal: AbortSignal): Promise<AgentMessage[]>;
+    /** 不得抛错。 */
+    convertToLlm(messages: AgentMessage[]): Message[];
+    prepareRequest?(req: PreparedRequest): Promise<PreparedRequest>;
+    /** 阈值压缩在此。 */
+    prepareNextTurn?(prev: TurnResult): Promise<void>;
+    /** 命令式 Hook PreToolUse → 权限管线 → broker。 */
+    beforeToolCall(call: ToolCall, ctx: ToolCallGateContext): Promise<ToolCallGate>;
+    /** PostToolUse 可追加上下文 / 改为错误。 */
+    afterToolCall?(call: ToolCall, result: ToolResult): Promise<ToolResult>;
+    finishTurn?(turn: TurnResult): Promise<"continue" | "end">;
+    getSteeringMessages(): AgentMessage[];
+    getFollowUpMessages(): AgentMessage[];
+}
+export type QueueMode = "one-at-a-time" | "all";
+export interface CompactionSettings {
+    enabled: boolean;
+    /** 缺省 16 384。 */
+    reserveTokens: number;
+    /** 缺省 20 000。 */
+    keepRecentTokens: number;
+}
+export interface RetrySettings {
+    enabled: boolean;
+    /** 缺省 3。 */
+    maxRetries: number;
+    /** 缺省 2 000。 */
+    baseDelayMs: number;
+    /** 缺省 60 000。 */
+    maxDelayMs: number;
+}
+/**
+ * [W3-C0] 会话层缓存设置（第三波 §1.12），解析后的完整形状；缺省 streaming / short /
+ * 0.05 / true / false。
+ */
+export interface CacheSettings {
+    /** 子会话（depth > 0）在 `warmSubagents` 为 false 时按 off。 */
+    warming: WarmingMode;
+    retention: CacheRetention;
+    /** 保温的最低期望节省（美元），缺省 0.05。 */
+    minSavingsUsd: number;
+    /** 转录 / 消息区的未命中与上下文余量提示（统计不受影响）。 */
+    missNotices: boolean;
+    warmSubagents: boolean;
+}
+export interface CompactionResult {
+    summary: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    tokensAfter?: number;
+    usage?: Usage;
+}
+export type CompactionTrigger = "threshold" | "overflow" | "manual";
+export type SessionEvent = {
+    type: "session_start";
+    sessionId: string;
+    sessionFile?: string;
+    cwd: string;
+    reason: "startup" | "resume" | "new" | "fork";
+}
+/** 用户提示经 UserPromptSubmit Hook 与模板展开之后、本次运行开始之前（设计 §11.1 第 16 步）。 */
+ | {
+    type: "before_agent_start";
+    prompt: string;
+} | {
+    type: "agent_start";
+} | {
+    type: "agent_end";
+    stopReason: string;
+    willRetry: boolean;
+} | {
+    type: "agent_before_settle";
+} | {
+    type: "agent_settled";
+    warning?: string;
+} | {
+    type: "turn_start";
+} | {
+    type: "turn_end";
+    message: AssistantMessage;
+    toolResults: ToolResultMessage[];
+} | {
+    type: "message_start";
+    message: AgentMessage;
+} | {
+    type: "message_update";
+    /** 当前累计的部分消息。 */
+    message: AssistantMessage;
+    assistantMessageEvent: AssistantEvent;
+} | {
+    type: "message_end";
+    message: AgentMessage;
+}
+/**
+ * `parentToolCallId`：codemode 脚本里经 `tools.*` 发起的内层调用带上外层 `codemode` 调用的
+ * id（设计 §5.5），TUI 据此折叠显示；模型直接发起的调用不带。
+ */
+ | {
+    type: "tool_execution_start";
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    parentToolCallId?: string;
+} | {
+    type: "tool_execution_update";
+    toolCallId: string;
+    toolName: string;
+    partial: string;
+    parentToolCallId?: string;
+} | {
+    type: "tool_execution_end";
+    toolCallId: string;
+    toolName: string;
+    result: ToolResult;
+    isError: boolean;
+    parentToolCallId?: string;
+} | {
+    type: "queue_update";
+    steering: string[];
+    followUp: string[];
+} | {
+    type: "compaction_start";
+    trigger: CompactionTrigger;
+} | {
+    type: "compaction_end";
+    trigger: CompactionTrigger;
+    result?: CompactionResult;
+    aborted: boolean;
+    willRetry: boolean;
+    error?: string;
+} | {
+    type: "auto_retry_start";
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    errorMessage: string;
+} | {
+    type: "auto_retry_end";
+    success: boolean;
+    attempt: number;
+    finalError?: string;
+} | {
+    type: "permission_request";
+    requestId: string;
+    toolName: string;
+    input: unknown;
+    reason: ApprovalReason;
+    hookReason?: string;
+    timeoutMs: number;
+    /** [W3-C0] 执行前预览（同 `ApprovalRequest.preview`）。 */
+    preview?: ActionPreview;
+} | {
+    type: "permission_resolved";
+    requestId: string;
+    decision: ApprovalDecision;
+} | {
+    type: "permission_mode_changed";
+    mode: PermissionMode;
+} | {
+    type: "entry_appended";
+    entry: SessionEntry;
+} | {
+    type: "hook_executed";
+    event: HookEvent;
+    command: string;
+    exitCode: number | null;
+    durationMs: number;
+} | {
+    type: "session_changed";
+    sessionId: string;
+    sessionFile?: string;
+} | {
+    type: "model_changed";
+    model: ModelRef;
+} | {
+    type: "thinking_level_changed";
+    level: ModelThinkingLevel;
+}
+/** [W3-C0] 一次缓存未命中（第三波 §1.5）；统计计入全部，界面只提示超过门槛的那次。 */
+ | ({
+    type: "cache_miss";
+} & CacheMiss)
+/** [W3-C0] 保温状态变化（第三波 §1.7）：排期、发出（带用量与花费）、停止（带原因）。 */
+ | {
+    type: "cache_warm";
+    phase: "scheduled" | "sent" | "stopped";
+    nextWarmAt?: number;
+    usage?: Usage;
+    /** 美元。 */
+    cost?: number;
+    reason?: string;
+}
+/** [W3-C0] 上下文占用跨越 70% / 90%（每个阈值每次跨越提示一次）。 */
+ | {
+    type: "context_pressure";
+    percent: number;
+    threshold: 70 | 90;
+    remainingTokens?: number;
+    /** 按最近 5 回合均值估算。 */
+    estimatedTurnsLeft?: number;
+};
+export type SessionEventType = SessionEvent["type"];
+export type PromptDisposition = "started" | "queued" | "handled";
+export interface PromptOptions {
+    images?: ImageBlock[];
+    streamingBehavior?: "steer" | "followUp";
+    /** 落盘到 user 消息的 origin（宿主注入为 "host"）；缺省：空闲时不填，入队时为 streamingBehavior。 */
+    origin?: MessageOrigin;
+}
+/** steer / followUp 的可选项。 */
+export interface EnqueueOptions {
+    /** 缺省为 "steer" / "followUp"；`"user"` 表示普通用户输入（不写 origin）。 */
+    origin?: MessageOrigin;
+}
+export interface SessionState {
+    isStreaming: boolean;
+    isCompacting: boolean;
+    isRetrying: boolean;
+    model: ModelRef | undefined;
+    thinkingLevel: ModelThinkingLevel;
+    permissionMode: PermissionMode;
+    sessionId: string;
+    sessionFile: string | undefined;
+    cwd: string;
+    sessionName: string | undefined;
+    messageCount: number;
+    pendingMessageCount: number;
+    steeringMode: QueueMode;
+    followUpMode: QueueMode;
+    autoCompaction: boolean;
+    autoRetry: boolean;
+}
+export interface SessionStats {
+    sessionId: string;
+    sessionFile: string | undefined;
+    userMessages: number;
+    assistantMessages: number;
+    toolCalls: number;
+    toolResults: number;
+    tokens: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+    /** 美元；任一条消息缺成本时 undefined（显示 `$?`）。 */
+    cost: number | undefined;
+    /** 估算的当前上下文 token（§9 估算）。 */
+    contextTokens: number | undefined;
+    contextWindow: number | undefined;
+    /** 0–100；无窗口时 undefined（显示 `ctx ?`）。 */
+    contextPercent: number | undefined;
+    /**
+     * 缓存命中率 0–1 = cacheRead /（input + cacheRead + cacheWrite）（设计 §9.1）；
+     * 还没有任何输入用量时不给。
+     */
+    cacheHitRate?: number;
+    /** [W3-C0] 缓存可观测性（第三波 §1.10）；会话层缓存控制器（C1b）未接线时缺省。 */
+    cache?: SessionCacheStats;
+}
+/** [W3-C0] `SessionStats.cache`（`get_session_stats` / `/session` / `-p --output-format json`）。 */
+export interface SessionCacheStats {
+    /** 当前端点的三态。 */
+    reporting: CacheReporting;
+    /** 最近一次请求的命中率 0–1；`unknown` / `silent` 时不给。 */
+    lastHitRate?: number;
+    /** 会话累计命中率 0–1；不报缓存的请求不进分母。 */
+    hitRate?: number;
+    /** 未命中重计费的 token 合计。 */
+    reBilledTokens: number;
+    /** 重计费金额（美元）；有无价模型参与时 undefined。 */
+    reBilledUsd?: number;
+    misses: {
+        count: number;
+        byReason: Partial<Record<CacheMissReason, number>>;
+    };
+    warming: WarmerStatus;
+    contextRemainingTokens?: number;
+    estimatedTurnsLeft?: number;
+    /** task 子会话的汇总（各自独立统计）。 */
+    subagents?: {
+        count: number;
+        hitRate?: number;
+        reBilledTokens: number;
+    };
+    /** 当前端点推断的缓存读分块粒度（token）；未推断出时不给。 */
+    granularity?: number;
+}
+export interface AgentSession {
+    /** 运行中且无 streamingBehavior → reject AmaError{code:"busy"}；run 结束（含重试与 followUp）后 resolve。 */
+    prompt(text: string, options?: PromptOptions): Promise<PromptDisposition>;
+    steer(text: string, options?: EnqueueOptions): Promise<"queued" | "handled">;
+    followUp(text: string, options?: EnqueueOptions): Promise<"queued" | "handled">;
+    /** 回到 idle 后 resolve；不清队列。 */
+    abort(): Promise<void>;
+    waitForIdle(): Promise<void>;
+    clearQueue(): {
+        steering: string[];
+        followUp: string[];
+    };
+    subscribe(listener: (event: SessionEvent) => void): () => void;
+    compact(instructions?: string): Promise<CompactionResult>;
+    fork(entryId: string): Promise<AgentSession>;
+    /** `provider/model-id`。 */
+    setModel(ref: string): Promise<void>;
+    setThinkingLevel(level: ModelThinkingLevel): void;
+    setPermissionMode(mode: PermissionMode): void;
+    setActiveTools(names: string[]): void;
+    getTools(): readonly ToolDefinition[];
+    readonly state: SessionState;
+    readonly messages: readonly AgentMessage[];
+    readonly entries: readonly SessionEntry[];
+    getLastAssistantText(): string | null;
+    getStats(): SessionStats;
+    dispose(): Promise<void>;
+}

package/dist/agent/types.js

@@ -0,0 +1,21 @@
+/**
+ * 循环与会话对象契约（设计 §4.1、§4.3、§13.1、§13.2 事件）。[B0] 契约文件，实现归 B2。
+ *
+ * 补全与偏差：
+ * - `ContentBlock / Usage / StopReason` 等定义在 ai/types.ts，`AgentMessage` 定义在
+ *   session/types.ts（依赖方向），此处再导出，设计里「agent/types.ts 提供」的名字都能从这里拿到。
+ * - `LoopHooks.beforeToolCall` 的 `ctx` 补全为 `ToolCallGateContext`；`prepareRequest` 的
+ *   `req` 补全为 `PreparedRequest`。
+ * - `SessionEvent` 是 AgentSession.subscribe 的进程内事件；RPC / stream-json 线上形状见
+ *   src/rpc.ts（`message_update` 线上为纯增量）。
+ * - `AgentSession` 是接口；B2 的实现类不要再叫 `AgentSession`（建议 `AgentSessionImpl`），
+ *   否则与本接口在 index.ts 的再导出冲突。
+ * - 补全 `SessionState`、`SessionStats`、`CompactionResult`、`CompactionSettings`、
+ *   `RetrySettings`、`QueueMode`。
+ * - （B2 追加）`PromptOptions.origin` 与 `steer / followUp` 的可选 `EnqueueOptions`：宿主
+ *   `sendUser(text, origin)` 注入的消息要以 `origin` 落盘（§4.3）；`"user"` 等同不填。
+ * - （W3-C0）缓存可观测性（第三波 §1.10）：`SessionEvent` 加 `cache_miss` / `cache_warm` /
+ *   `context_pressure`，`SessionStats.cache`（可选，C1b 填）；`CacheSettings` 是
+ *   `SessionCacheController` 的解析后设置（来自 config `cache` 段与环境变量）。
+ */
+export {};

package/dist/ai/apis/anthropic-messages.d.ts

@@ -0,0 +1,26 @@
+/**
+ * anthropic-messages 协议（设计 §3.1）：POST `{baseUrl}/v1/messages`（stream；baseUrl 已以 `/v1`
+ * 结尾时不重复），SSE → 事件。
+ *
+ * SSE 事件：message_start（id、初始 usage）→ content_block_start / delta / stop（text、
+ * thinking + signature_delta、redacted_thinking、tool_use + input_json_delta）→ message_delta
+ * （stop_reason、累计 usage）→ message_stop。`event: error` 或缺 message_stop 都编码为 error。
+ *
+ * usage：`input_tokens` 本就不含缓存；`cache_read_input_tokens` → cacheRead，
+ * `cache_creation_input_tokens` → cacheWrite，`cache_creation.ephemeral_1h_input_tokens` →
+ * cacheWrite1h。message_delta 只覆盖非 null 字段（部分代理在 delta 里省略 input）。两个缓存字段
+ * 任一出现过（含 0）即 `cacheReported: true`，之后的事件不会把它改回 false。
+ */
+import type { AnthropicMessagesCompat, ApiImplementation, Usage } from "../types.js";
+type Json = Record<string, unknown>;
+/** 把 Anthropic usage 字段写进 Usage（只覆盖出现且非 null 的字段）。 */
+export declare function applyAnthropicUsage(usage: Usage, raw: Json | undefined): void;
+type MappedStop = {
+    reason: "stop" | "length" | "toolUse";
+} | {
+    reason: "error";
+    message: string;
+};
+export declare function mapAnthropicStop(raw: string, details?: Json): MappedStop;
+export declare const anthropicMessagesApi: ApiImplementation<AnthropicMessagesCompat>;
+export {};

package/dist/ai/apis/anthropic-messages.js

@@ -0,0 +1,214 @@
+/**
+ * anthropic-messages 协议（设计 §3.1）：POST `{baseUrl}/v1/messages`（stream；baseUrl 已以 `/v1`
+ * 结尾时不重复），SSE → 事件。
+ *
+ * SSE 事件：message_start（id、初始 usage）→ content_block_start / delta / stop（text、
+ * thinking + signature_delta、redacted_thinking、tool_use + input_json_delta）→ message_delta
+ * （stop_reason、累计 usage）→ message_stop。`event: error` 或缺 message_stop 都编码为 error。
+ *
+ * usage：`input_tokens` 本就不含缓存；`cache_read_input_tokens` → cacheRead，
+ * `cache_creation_input_tokens` → cacheWrite，`cache_creation.ephemeral_1h_input_tokens` →
+ * cacheWrite1h。message_delta 只覆盖非 null 字段（部分代理在 delta 里省略 input）。两个缓存字段
+ * 任一出现过（含 0）即 `cacheReported: true`，之后的事件不会把它改回 false。
+ */
+import { AssistantEventStreamImpl } from "../event-stream.js";
+import { USER_AGENT, authHeaders, describeErrorJson, mergeHeaders } from "../http.js";
+import { readSseEvents } from "../sse.js";
+import { postWithCacheFallback } from "./cache-params.js";
+import { ANTHROPIC_VERSION, anthropicMessagesUrl, buildAnthropicRequest, detectAnthropicCompat, } from "./anthropic-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;
+}
+/** 把 Anthropic usage 字段写进 Usage（只覆盖出现且非 null 的字段）。 */
+export function applyAnthropicUsage(usage, raw) {
+    if (!raw)
+        return;
+    const input = num(raw["input_tokens"]);
+    const output = num(raw["output_tokens"]);
+    const cacheRead = num(raw["cache_read_input_tokens"]);
+    const cacheWrite = num(raw["cache_creation_input_tokens"]);
+    const longWrite = num(obj(raw["cache_creation"])?.["ephemeral_1h_input_tokens"]);
+    const reasoning = num(obj(raw["output_tokens_details"])?.["thinking_tokens"]);
+    if (input !== undefined)
+        usage.input = input;
+    if (output !== undefined)
+        usage.output = output;
+    if (cacheRead !== undefined)
+        usage.cacheRead = cacheRead;
+    if (cacheWrite !== undefined)
+        usage.cacheWrite = cacheWrite;
+    if (cacheRead !== undefined || cacheWrite !== undefined)
+        usage.cacheReported = true;
+    else
+        usage.cacheReported ??= false;
+    if (longWrite !== undefined)
+        usage.cacheWrite1h = longWrite;
+    if (reasoning !== undefined)
+        usage.reasoning = reasoning;
+}
+export function mapAnthropicStop(raw, details) {
+    switch (raw) {
+        case "end_turn":
+        case "stop_sequence":
+        case "pause_turn":
+            return { reason: "stop" };
+        case "max_tokens":
+            return { reason: "length" };
+        case "tool_use":
+            return { reason: "toolUse" };
+        case "refusal":
+            return {
+                reason: "error",
+                message: str(details?.["explanation"]) ?? "The model refused to respond (refusal)",
+            };
+        case "model_context_window_exceeded":
+            return { reason: "error", message: "model_context_window_exceeded: prompt is too long" };
+        default:
+            return { reason: "stop" };
+    }
+}
+function buildHeaders(model, options, betas) {
+    return mergeHeaders({
+        "content-type": "application/json",
+        accept: "text/event-stream",
+        "anthropic-version": ANTHROPIC_VERSION,
+        "user-agent": USER_AGENT,
+        ...(betas.length > 0 ? { "anthropic-beta": betas.join(",") } : {}),
+    }, authHeaders(options.apiKey, model.authHeader, "x-api-key"), model.headers, options.headers);
+}
+function handleEvent(data, state, tracker) {
+    const output = tracker.output;
+    const type = str(data["type"]);
+    if (type === "message_start") {
+        const message = obj(data["message"]);
+        const id = str(message?.["id"]);
+        if (id)
+            output.responseId = id;
+        applyAnthropicUsage(output.usage, obj(message?.["usage"]));
+    }
+    else if (type === "content_block_start") {
+        const index = num(data["index"]) ?? state.blocks.size;
+        const block = obj(data["content_block"]);
+        const kind = str(block?.["type"]);
+        if (kind === "text") {
+            state.blocks.set(index, tracker.startText(str(block?.["text"]) ?? ""));
+        }
+        else if (kind === "thinking") {
+            const signature = str(block?.["signature"]);
+            state.blocks.set(index, tracker.startThinking(str(block?.["thinking"]) ?? "", signature));
+        }
+        else if (kind === "redacted_thinking") {
+            const data = str(block?.["data"]) ?? "";
+            state.blocks.set(index, tracker.startThinking("[redacted]", data, true));
+        }
+        else if (kind === "tool_use") {
+            const input = obj(block?.["input"]) ?? {};
+            const id = str(block?.["id"]) ?? `toolu_${index}`;
+            state.blocks.set(index, tracker.startToolCall(id, str(block?.["name"]) ?? "", input));
+        }
+    }
+    else if (type === "content_block_delta") {
+        const target = state.blocks.get(num(data["index"]) ?? -1);
+        const delta = obj(data["delta"]);
+        if (target === undefined || !delta)
+            return;
+        const kind = str(delta["type"]);
+        if (kind === "text_delta")
+            tracker.appendText(target, str(delta["text"]) ?? "");
+        else if (kind === "thinking_delta")
+            tracker.appendThinking(target, str(delta["thinking"]) ?? "");
+        else if (kind === "signature_delta")
+            tracker.appendSignature(target, str(delta["signature"]) ?? "");
+        else if (kind === "input_json_delta")
+            tracker.appendToolArgs(target, str(delta["partial_json"]) ?? "");
+    }
+    else if (type === "content_block_stop") {
+        const target = state.blocks.get(num(data["index"]) ?? -1);
+        if (target !== undefined)
+            tracker.end(target);
+    }
+    else if (type === "message_delta") {
+        const delta = obj(data["delta"]);
+        const raw = str(delta?.["stop_reason"]);
+        if (raw) {
+            output.rawStopReason = raw;
+            state.stop = mapAnthropicStop(raw, obj(delta?.["stop_details"]));
+        }
+        applyAnthropicUsage(output.usage, obj(data["usage"]));
+    }
+    else if (type === "message_stop") {
+        state.sawMessageStop = true;
+    }
+    else if (type === "error") {
+        throw new Error(describeErrorJson(data) ?? JSON.stringify(data));
+    }
+}
+async function run(stream, model, context, options) {
+    const tracker = new BlockTracker(stream, createOutput(model));
+    try {
+        const request = buildAnthropicRequest(model, context, options);
+        tracker.output.thinkingLevel = request.thinkingLevel;
+        if (request.providerThinkingLevel !== undefined) {
+            tracker.output.providerThinkingLevel = request.providerThinkingLevel;
+        }
+        const replaced = options.onPayload?.(request.body);
+        const body = replaced === undefined ? request.body : replaced;
+        const baseUrl = model.baseUrl ?? "https://api.anthropic.com";
+        const response = await postWithCacheFallback(model, anthropicMessagesUrl(baseUrl), {
+            headers: buildHeaders(model, options, request.betas),
+            body,
+            signal: options.signal,
+            timeoutMs: options.timeoutMs,
+            onResponse: options.onResponse,
+        });
+        stream.push({ type: "start", partial: tracker.output });
+        const state = { blocks: new Map(), stop: undefined, sawMessageStop: false };
+        for await (const sse of readSseEvents(response.body, options.signal)) {
+            if (sse.event === "ping" || sse.data === "")
+                continue;
+            let data;
+            try {
+                data = obj(JSON.parse(sse.data)) ?? {};
+            }
+            catch {
+                throw new Error(`Malformed SSE data (${sse.event ?? "message"}): ${sse.data.slice(0, 200)}`);
+            }
+            if (sse.event === "error" && data["type"] !== "error")
+                data = { type: "error", error: data };
+            handleEvent(data, state, tracker);
+            if (state.sawMessageStop)
+                break;
+        }
+        if (options.signal.aborted)
+            throw new Error("aborted");
+        if (!state.sawMessageStop)
+            throw new Error(STREAM_ENDED_MESSAGE);
+        const stop = state.stop ?? { reason: tracker.hasToolCalls ? "toolUse" : "stop" };
+        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 anthropicMessagesApi = {
+    id: "anthropic-messages",
+    stream,
+    detectCompat: detectAnthropicCompat,
+};

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

@@ -0,0 +1,42 @@
+/**
+ * anthropic-messages 请求体（设计 §3.1、§3.3、§3.6）：消息转换、三断点缓存、thinking、工具。
+ *
+ * 缓存断点（cacheRetention 缺省 short，未指定时读 `AMA_CACHE_RETENTION`；none 不打；long 加
+ * `ttl: "1h"`，仅 `supportsLongCacheRetention`——官方端点缺省开，中转缺省关、降为 short；最后做 TTL
+ * 顺序校验，5m 之后出现 1h 则全部降为 5m）按优先级取前
+ * `maxCacheBreakpoints` 个：① 最后一条 user 消息（含工具结果）的最后一个块 ② system 末块
+ * ③ 最后一个工具定义（`supportsCacheControlOnTools`）。
+ *
+ * thinking：`adaptiveThinking` 模型发 `{type:"adaptive"}` + `output_config.effort`；
+ * 其余推理模型按预算发 `{type:"enabled", budget_tokens}`，预算计入 max_tokens；off 发
+ * `{type:"disabled"}`（映射表 off 为 null 的模型不发）。思考开启时不发 temperature，
+ * 除非 `supportsTemperatureWithThinking`。`toolChoice: "none"`（有工具时）→ `tool_choice:{type:"none"}`。
+ */
+import type { AnthropicMessagesCompat, AssistantMessage, Model, ModelThinkingLevel, ProviderData, StreamOptions, ToolResultMessage, TranscriptContext, UserMessage } from "../types.js";
+export declare const ANTHROPIC_VERSION = "2023-06-01";
+export declare const INTERLEAVED_THINKING_BETA = "interleaved-thinking-2025-05-14";
+export declare const DEFAULT_ANTHROPIC_COMPAT: Readonly<AnthropicMessagesCompat>;
+export declare function detectAnthropicCompat(model: Model, provider?: ProviderData): AnthropicMessagesCompat;
+type Json = Record<string, unknown>;
+export interface AnthropicRequest {
+    body: Json;
+    betas: string[];
+    thinkingLevel: ModelThinkingLevel;
+    providerThinkingLevel: string | undefined;
+}
+export declare function cacheControlFor(retention: StreamOptions["cacheRetention"]): {
+    type: "ephemeral";
+    ttl?: "1h";
+} | undefined;
+/**
+ * TTL 顺序校验：Anthropic 按 tools → system → messages 的顺序处理断点，要求 1h 条目都在 5m 之前。
+ * 出现「5m 之后的 1h」→ 全部降为 5m（去掉 ttl）。返回是否做了降级。
+ */
+export declare function enforceCacheTtlOrder(body: Json): boolean;
+/** `{baseUrl}/v1/messages`；baseUrl 已以 `/v1` 结尾（中转常见写法）时不再重复。 */
+export declare function anthropicMessagesUrl(baseUrl: string): string;
+/** Anthropic 要求 tool_use id 匹配 `^[a-zA-Z0-9_-]+$` 且 ≤ 64。 */
+export declare function normalizeToolId(id: string): string;
+export declare function convertMessages(messages: readonly (UserMessage | AssistantMessage | ToolResultMessage)[]): Json[];
+export declare function buildAnthropicRequest(model: Model, context: TranscriptContext, options: StreamOptions): AnthropicRequest;
+export {};