@armadra/agent 0.2.1 → 0.4.0

package/dist/agent/session-core.d.ts

@@ -7,6 +7,7 @@
 import type { WarmingDecisionHandler } from "../ai/cache/types.js";
 import type { Model, ModelThinkingLevel, ProviderRegistryApi } from "../ai/types.js";
 import type { HookDispatcherApi, HookEvent, HookEventPayload, HookOutcome } from "../hooks/types.js";
+import type { PermissionClassifier } from "../permissions/classifier.js";
 import type { ApprovalBroker, PermissionPipelineApi } from "../permissions/types.js";
 import type { SessionManager } from "../session/manager.js";
 import type { SessionEntry, SessionEntryInput } from "../session/types.js";
@@ -37,6 +38,14 @@ export interface AgentSessionOptions {
     brokers?: readonly ApprovalBroker[];
     /** 无人值守：权限管线把 ask 变 deny。 */
     unattended?: boolean;
+    /**
+     * auto 权限模式的模型分类器（§7.4）：`model` 为 `provider/model`（config `permission.autoModel`），
+     * 缺省用当前会话模型；`timeoutMs` 缺省 10 000。
+     */
+    permissionClassifier?: {
+        model?: string;
+        timeoutMs?: number;
+    };
     /** 审批超时，缺省 10 分钟（超时 deny）。 */
     approvalTimeoutMs?: number;
     /** 命令式 Hook（B5）；缺省无 Hook。 */
@@ -59,6 +68,8 @@ export interface AgentSessionOptions {
     outputDir?: string;
     /** task 深度：主会话 0。 */
     depth?: number;
+    /** 模型请求的空闲超时（毫秒，0 关闭）；缺省由协议层取 300 000。 */
+    idleTimeoutMs?: number;
     /** 子 Agent 的回合上限（maxTurns）。 */
     maxTurns?: number;
     /** 子 Agent 并发上限，缺省 4；`false` 关闭 spawnSubagent。 */
@@ -99,5 +110,7 @@ export interface SessionCore {
     /** Hook 返回 continue:false 时记下，finishTurn 据此结束 run。 */
     requestStop(reason: string | undefined): void;
     spawnSubagent(request: SubagentRequest): Promise<SubagentResult>;
+    /** auto 权限模式的分类器（懒建，会话内缓存判定）。 */
+    autoClassifier(): PermissionClassifier;
     log(level: "debug" | "info" | "warn" | "error", message: string): void;
 }

package/dist/agent/session-state.js

@@ -5,13 +5,14 @@
  * 压缩与分支摘要请求的 usage 也计入；`usage` 条目（缓存保温等不进上下文的请求，第三波 §1.7）
  * 计入 token 与费用但不算消息。上下文 % 用投影感知估算（§9）。
  */
+import { modelRefOf } from "../ai/providers/channels.js";
 export function buildSessionState(input) {
     const { agent, manager, model } = input;
     return {
         isStreaming: agent.isRunning,
         isCompacting: input.isCompacting,
         isRetrying: input.isRetrying,
-        model: { provider: model.provider, id: model.id },
+        model: modelRefOf(model),
         thinkingLevel: input.thinkingLevel,
         permissionMode: input.permissionMode,
         sessionId: manager.id,

package/dist/agent/session-sync.js

@@ -28,17 +28,24 @@ export function persistMessage(core, message) {
 export function recordModelState(core, model, thinkingLevel) {
     let provider;
     let modelId;
+    let channel;
     let thinking;
     for (const entry of core.manager.branch()) {
         if (entry.type === "model_change") {
             provider = entry.provider;
             modelId = entry.modelId;
+            channel = entry.channel;
         }
         else if (entry.type === "thinking_level_change")
             thinking = entry.thinkingLevel;
     }
-    if (provider !== model.provider || modelId !== model.id) {
-        core.appendEntry({ type: "model_change", provider: model.provider, modelId: model.id });
+    if (provider !== model.provider || modelId !== model.id || channel !== model.channel) {
+        core.appendEntry({
+            type: "model_change",
+            provider: model.provider,
+            modelId: model.id,
+            ...(model.channel !== undefined ? { channel: model.channel } : {}),
+        });
     }
     if (thinking !== thinkingLevel) {
         core.appendEntry({ type: "thinking_level_change", thinkingLevel });

package/dist/agent/session-tools.js

@@ -13,6 +13,7 @@
 import { randomUUID } from "node:crypto";
 import { DEFAULT_APPROVAL_TIMEOUT_MS } from "../permissions/broker.js";
 import { previewAction } from "../permissions/preview.js";
+import { classifierRequest } from "./session-classifier.js";
 import { runSingleToolCall } from "./tool-runner.js";
 /** 外层是这个工具时，嵌套调用的 Hook 输入带 `viaCodemode: true`。 */
 const CODEMODE_TOOL_NAME = "codemode";
@@ -36,6 +37,8 @@ export async function requestApproval(core, request, signal) {
         event.hookReason = request.hookReason;
     if (request.preview !== undefined)
         event.preview = request.preview;
+    if (request.autoDecision !== undefined)
+        event.autoDecision = request.autoDecision;
     core.emit(event);
     void core.runHook("Notification", {
         notification: { kind: "approval", message: `approval requested for ${request.toolName}` },
@@ -117,6 +120,7 @@ export async function gateToolCall(core, call, ctx) {
     let decision = hookDecision === "ask" ? "ask" : "allow";
     let approvalReason = "hook";
     let denyMessage;
+    let autoDecision;
     if (permission !== undefined) {
         const checkInput = {
             toolName: call.name,
@@ -132,12 +136,27 @@ export async function gateToolCall(core, call, ctx) {
         decision = verdict.decision;
         approvalReason = verdict.approvalReason ?? "mode";
         denyMessage = verdict.message;
+        autoDecision = verdict.auto;
+        if (verdict.classify === true) {
+            // auto 第 3 层：规则层与静态判定都没决定，问一次独立的模型分类器（只能变 allow）
+            const judged = await core
+                .autoClassifier()
+                .classify(classifierRequest(core, call.name, input, permission.projectRoot), ctx.signal);
+            autoDecision = { layer: "classifier", decision: judged.decision, reason: judged.reason };
+            if (judged.cached)
+                autoDecision.cached = true;
+            if (judged.decision === "allow")
+                decision = "allow";
+        }
+        if (autoDecision !== undefined)
+            permission.recordAutoDecision?.(call.name, input, autoDecision);
     }
     else if (decision === "ask" && core.options.unattended === true) {
         decision = "deny";
     }
+    const withAuto = (gate) => autoDecision === undefined ? gate : { ...gate, autoDecision };
     if (decision === "deny") {
-        return { block: true, reason: denyMessage ?? `Permission denied for ${call.name}` };
+        return withAuto({ block: true, reason: denyMessage ?? `Permission denied for ${call.name}` });
     }
     if (decision === "ask") {
         const request = {
@@ -149,16 +168,18 @@ export async function gateToolCall(core, call, ctx) {
         };
         if (hookReason !== undefined)
             request.hookReason = hookReason;
+        if (autoDecision !== undefined)
+            request.autoDecision = autoDecision;
         const preview = safePreview(core, request);
         if (preview !== undefined)
             request.preview = preview;
         const answer = await requestApproval(core, request, ctx.signal);
         if (answer === "deny")
-            return { block: true, reason: `The user denied ${call.name}` };
+            return withAuto({ block: true, reason: `The user denied ${call.name}` });
         if (answer === "allow_session")
             permission?.rememberForSession(call.name, input);
     }
-    return replaced ? { input } : {};
+    return withAuto(replaced ? { input } : {});
 }
 export async function afterToolCall(core, call, result, parent) {
     if (core.options.hooks?.has("PostToolUse", call.name) !== true)

package/dist/agent/session.d.ts

@@ -12,6 +12,7 @@
  */
 import type { Model, ModelThinkingLevel } from "../ai/types.js";
 import type { HookEvent, HookEventPayload, HookOutcome } from "../hooks/types.js";
+import type { PermissionClassifier } from "../permissions/classifier.js";
 import type { PermissionMode } from "../permissions/types.js";
 import type { SessionManager } from "../session/manager.js";
 import type { AgentMessage, BranchSummaryEntry, SessionEntry, SessionEntryInput } from "../session/types.js";
@@ -47,6 +48,7 @@ export declare class AgentSessionImpl implements AgentSession, SessionCore {
     private systemInput;
     private readonly subagentPool;
     private disposed;
+    private classifier;
     /** 已入队、尚未投递的消息（投递时发 queue_update）。 */
     private readonly queuedMessages;
     constructor(options: AgentSessionOptions);
@@ -113,5 +115,6 @@ export declare class AgentSessionImpl implements AgentSession, SessionCore {
     getStats(): SessionStats;
     dispose(): Promise<void>;
     childBase(): Pick<AgentSessionOptions, "model" | "thinkingLevel" | "activeTools" | "system">;
+    autoClassifier(): PermissionClassifier;
     spawnSubagent(request: SubagentRequest): Promise<SubagentResult>;
 }

package/dist/agent/session.js

@@ -10,8 +10,10 @@
  * - `steer()` / `followUp()`：运行中入队（返回 "queued"）；空闲时直接以该消息开始一个周期（"handled"）。
  * - `abort()`：中断供应商流、工具、重试等待与压缩；回到 idle 后 resolve；不清队列。
  */
+import { modelRefOf } from "../ai/providers/channels.js";
 import { join } from "node:path";
 import { AmaError } from "../errors.js";
+import { createSessionClassifier } from "./session-classifier.js";
 import { buildProjection } from "../session/projection.js";
 import { Agent } from "./agent.js";
 import { queuedText } from "./queue.js";
@@ -52,6 +54,7 @@ export class AgentSessionImpl {
     systemInput;
     subagentPool;
     disposed = false;
+    classifier;
     /** 已入队、尚未投递的消息（投递时发 queue_update）。 */
     queuedMessages = new WeakSet();
     constructor(options) {
@@ -102,9 +105,12 @@ export class AgentSessionImpl {
             getThinkingLevel: () => this.currentThinking,
             streamOptions: async () => {
                 const apiKey = await this.resolveApiKey();
-                return apiKey === undefined
-                    ? { sessionId: this.manager.id }
-                    : { apiKey, sessionId: this.manager.id };
+                const idle = options.idleTimeoutMs;
+                return {
+                    sessionId: this.manager.id,
+                    ...(apiKey === undefined ? {} : { apiKey }),
+                    ...(idle === undefined ? {} : { idleTimeoutMs: idle }),
+                };
             },
             beforeRequest: async () => {
                 this.syncSystem();
@@ -141,7 +147,8 @@ export class AgentSessionImpl {
     }
     async resolveApiKey() {
         try {
-            return (await this.options.providers.resolveApiKey(this.currentModel.provider)).apiKey;
+            const { provider, channel } = this.currentModel;
+            return (await this.options.providers.resolveApiKey(provider, channel)).apiKey;
         }
         catch {
             return undefined;
@@ -358,15 +365,14 @@ export class AgentSessionImpl {
         }
         this.currentModel = lookup.model;
         this.compaction.refresh();
+        const next = modelRefOf(lookup.model);
         this.appendEntry({
             type: "model_change",
-            provider: lookup.model.provider,
-            modelId: lookup.model.id,
-        });
-        this.emit({
-            type: "model_changed",
-            model: { provider: lookup.model.provider, id: lookup.model.id },
+            provider: next.provider,
+            modelId: next.id,
+            ...(next.channel !== undefined ? { channel: next.channel } : {}),
         });
+        this.emit({ type: "model_changed", model: next });
     }
     setThinkingLevel(level) {
         this.currentThinking = level;
@@ -478,6 +484,10 @@ export class AgentSessionImpl {
             system: this.systemInput,
         };
     }
+    autoClassifier() {
+        this.classifier ??= createSessionClassifier(this);
+        return this.classifier;
+    }
     spawnSubagent(request) {
         return runSubagent(this, request, this.subagentPool, (options) => new AgentSessionImpl(options));
     }

package/dist/agent/tool-runner.js

@@ -25,6 +25,10 @@ export const DEFAULT_MAX_TOOL_RESULT_CHARS = 30_000;
 export const DEFAULT_ABORT_GRACE_MS = 3000;
 /** 嵌套调用结果的截断上限（给脚本，不进上下文）。 */
 export const NESTED_MAX_RESULT_CHARS = 1024 * 1024;
+/** 门禁给出的 auto 判定，随 tool_execution_end 发出（按调用对象记，调用结束后随之回收）。 */
+const autoDecisions = new WeakMap();
+/** 门禁拒绝（gate.block）而没有执行的调用：tool_execution_end 带 `denied`。 */
+const deniedCalls = new WeakSet();
 export function errorResult(text) {
     return { content: text, isError: true };
 }
@@ -80,9 +84,12 @@ async function prepare(call, assistant, options, signal, parent) {
     try {
         const gateContext = parent === undefined ? { signal, assistant, tool } : { signal, assistant, tool, parent };
         const gate = await options.beforeToolCall(call, gateContext);
+        if (gate.autoDecision !== undefined)
+            autoDecisions.set(call, gate.autoDecision);
         if (signal.aborted)
             return { kind: "immediate", call, result: errorResult(ABORTED_TOOL_TEXT) };
         if (gate.block === true) {
+            deniedCalls.add(call);
             return {
                 kind: "immediate",
                 call,
@@ -193,13 +200,19 @@ async function execute(prepared, options, signal, emit, parent) {
     return truncateResult(call, result, options, parent !== undefined);
 }
 async function emitEnd(call, result, emit) {
-    await emit({
+    const event = {
         type: "tool_execution_end",
         toolCallId: call.id,
         toolName: call.name,
         result,
         isError: result.isError === true,
-    });
+    };
+    const auto = autoDecisions.get(call);
+    if (auto !== undefined)
+        event.autoDecision = auto;
+    if (deniedCalls.has(call))
+        event.denied = true;
+    await emit(event);
 }
 async function emitResultMessages(finalized, emit) {
     const messages = [];

package/dist/agent/types.d.ts

@@ -21,7 +21,7 @@
 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 { ActionPreview, ApprovalDecision, ApprovalReason, AutoDecision, 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";
@@ -56,6 +56,8 @@ export interface ToolCallGate {
     reason?: string;
     /** Hook 的 updatedInput 替换后的输入。 */
     input?: unknown;
+    /** auto 权限模式的判定（随 tool_execution_end 发出）。 */
+    autoDecision?: AutoDecision;
 }
 export interface LoopHooks {
     /** 档一裁剪、Hook 的 additionalContext 注入。 */
@@ -175,6 +177,10 @@ export type SessionEvent = {
     result: ToolResult;
     isError: boolean;
     parentToolCallId?: string;
+    /** auto 权限模式下这次调用的判定（层、结论、原因）；其它模式缺省。 */
+    autoDecision?: AutoDecision;
+    /** 被拒（权限管线、PreToolUse Hook、审批或无人值守）而没有执行；原因是 `result` 的文本。 */
+    denied?: true;
 } | {
     type: "queue_update";
     steering: string[];
@@ -210,6 +216,8 @@ export type SessionEvent = {
     timeoutMs: number;
     /** [W3-C0] 执行前预览（同 `ApprovalRequest.preview`）。 */
     preview?: ActionPreview;
+    /** auto 权限模式下为什么询问（同 `ApprovalRequest.autoDecision`）。 */
+    autoDecision?: AutoDecision;
 } | {
     type: "permission_resolved";
     requestId: string;

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

@@ -12,7 +12,7 @@
  * 任一出现过（含 0）即 `cacheReported: true`，之后的事件不会把它改回 false。
  */
 import { AssistantEventStreamImpl } from "../event-stream.js";
-import { USER_AGENT, authHeaders, describeErrorJson, mergeHeaders } from "../http.js";
+import { authHeaders, describeErrorJson, idleTimeoutOf, mergeHeaders, USER_AGENT, } from "../http.js";
 import { readSseEvents } from "../sse.js";
 import { postWithCacheFallback } from "./cache-params.js";
 import { ANTHROPIC_VERSION, anthropicMessagesUrl, buildAnthropicRequest, detectAnthropicCompat, } from "./anthropic-request.js";
@@ -168,11 +168,12 @@ async function run(stream, model, context, options) {
             body,
             signal: options.signal,
             timeoutMs: options.timeoutMs,
+            idleTimeoutMs: idleTimeoutOf(options),
             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)) {
+        for await (const sse of readSseEvents(response.body, options.signal, idleTimeoutOf(options))) {
             if (sse.event === "ping" || sse.data === "")
                 continue;
             let data;

package/dist/ai/apis/google-generative-ai.js

@@ -16,7 +16,7 @@
  * - 错误体 `{error:{code,status,message}}` 重排为 `429 RESOURCE_EXHAUSTED: …`。
  */
 import { AssistantEventStreamImpl } from "../event-stream.js";
-import { HttpError, USER_AGENT, authHeaders, joinUrl, mergeHeaders, postJson } from "../http.js";
+import { authHeaders, HttpError, idleTimeoutOf, joinUrl, mergeHeaders, postJson, USER_AGENT, } from "../http.js";
 import { readSseEvents } from "../sse.js";
 import { GOOGLE_BASE_URL, buildGoogleRequest, detectGoogleCompat } from "./google-request.js";
 import { BlockTracker, ProviderStopError, STREAM_ENDED_MESSAGE, createOutput, finishDone, finishError, requireApiKey, } from "./shared.js";
@@ -196,6 +196,7 @@ async function run(stream, model, context, options) {
                 body: replaced === undefined ? request.body : replaced,
                 signal: options.signal,
                 timeoutMs: options.timeoutMs,
+                idleTimeoutMs: idleTimeoutOf(options),
                 onResponse: options.onResponse,
             });
         }
@@ -209,7 +210,7 @@ async function run(stream, model, context, options) {
             idSeed: Date.now().toString(36),
         };
         const body = response.body;
-        for await (const sse of readSseEvents(body, options.signal)) {
+        for await (const sse of readSseEvents(body, options.signal, idleTimeoutOf(options))) {
             const data = sse.data.trim();
             if (data === "" || data === "[DONE]")
                 continue;

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

@@ -14,7 +14,7 @@
  *   内容推断。
  */
 import { AssistantEventStreamImpl } from "../event-stream.js";
-import { USER_AGENT, authHeaders, describeErrorJson, joinUrl, mergeHeaders } from "../http.js";
+import { authHeaders, describeErrorJson, idleTimeoutOf, joinUrl, mergeHeaders, USER_AGENT, } from "../http.js";
 import { readSseEvents } from "../sse.js";
 import { affinityHeaders, postWithCacheFallback, resolveCacheRetention } from "./cache-params.js";
 import { detectCompat } from "./openai-compat.js";
@@ -190,6 +190,7 @@ async function run(stream, model, context, options) {
             body: replaced === undefined ? request.body : replaced,
             signal: options.signal,
             timeoutMs: options.timeoutMs,
+            idleTimeoutMs: idleTimeoutOf(options),
             onResponse: options.onResponse,
         });
         stream.push({ type: "start", partial: tracker.output });
@@ -203,7 +204,7 @@ async function run(stream, model, context, options) {
             sawDone: false,
         };
         const body = response.body;
-        for await (const sse of readSseEvents(body, options.signal)) {
+        for await (const sse of readSseEvents(body, options.signal, idleTimeoutOf(options))) {
             const data = sse.data.trim();
             if (data === "")
                 continue;

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

@@ -15,7 +15,7 @@
  *   `cacheReported: true`。
  */
 import { AssistantEventStreamImpl } from "../event-stream.js";
-import { USER_AGENT, authHeaders, describeErrorJson, joinUrl, mergeHeaders } from "../http.js";
+import { authHeaders, describeErrorJson, idleTimeoutOf, joinUrl, mergeHeaders, USER_AGENT, } from "../http.js";
 import { readSseEvents } from "../sse.js";
 import { affinityHeaders, postWithCacheFallback, resolveCacheRetention } from "./cache-params.js";
 import { buildResponsesRequest, detectResponsesCompat, encodeMessageSignature, } from "./openai-responses-request.js";
@@ -50,7 +50,8 @@ export function parseResponsesUsage(raw) {
 }
 export function mapResponsesStatus(status, incomplete) {
     if (status === "incomplete") {
-        if (incomplete === "max_output_tokens")
+        // 中转转发的 DeepSeek 等上游写 `length`（实测 2026-10-02），与 `max_output_tokens` 同义。
+        if (incomplete === "max_output_tokens" || incomplete === "length")
             return { reason: "length" };
         return {
             reason: "error",
@@ -248,6 +249,7 @@ async function run(stream, model, context, options) {
             body: replaced === undefined ? request.body : replaced,
             signal: options.signal,
             timeoutMs: options.timeoutMs,
+            idleTimeoutMs: idleTimeoutOf(options),
             onResponse: options.onResponse,
         });
         stream.push({ type: "start", partial: tracker.output });
@@ -259,7 +261,7 @@ async function run(stream, model, context, options) {
         };
         let finished = false;
         const body = response.body;
-        for await (const sse of readSseEvents(body, options.signal)) {
+        for await (const sse of readSseEvents(body, options.signal, idleTimeoutOf(options))) {
             const raw = sse.data.trim();
             if (raw === "" || raw === "[DONE]")
                 continue;

package/dist/ai/cache/fingerprint.d.ts

@@ -11,7 +11,7 @@ import type { Model, ModelRef, TranscriptContext } from "../types.js";
 import type { PrefixFingerprint } from "./types.js";
 /** sha256 的前 16 位 hex（64 bit）。 */
 export declare function hash16(text: string): string;
-export declare function modelKey(model: Pick<Model, "provider" | "id"> | ModelRef): string;
+export declare function modelKey(model: Pick<Model, "provider" | "id" | "channel"> | ModelRef): string;
 export declare function fingerprintContext(context: TranscriptContext, model: Pick<Model, "provider" | "id">): PrefixFingerprint;
 /** 两个指纹的差异（按归因顺序：system → tools → model）；相同返回 undefined。 */
 export declare function fingerprintChange(prev: PrefixFingerprint, cur: PrefixFingerprint): "system" | "tools" | "model" | undefined;

package/dist/ai/cache/fingerprint.js

@@ -14,7 +14,7 @@ export function hash16(text) {
     return createHash("sha256").update(text).digest("hex").slice(0, 16);
 }
 export function modelKey(model) {
-    return `${model.provider}/${model.id}`;
+    return `${model.provider}/${model.id}${model.channel !== undefined ? `@${model.channel}` : ""}`;
 }
 function sortedTools(tools) {
     return [...tools].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));

package/dist/ai/cache/reporting.js

@@ -41,7 +41,8 @@ function hostOf(baseUrl) {
     }
 }
 export function endpointKey(record) {
-    return `${record.model.provider}|${hostOf(record.baseUrl)}|${record.model.id}`;
+    const channel = record.model.channel !== undefined ? `@${record.model.channel}` : "";
+    return `${record.model.provider}|${hostOf(record.baseUrl)}|${record.model.id}${channel}`;
 }
 function sameFingerprint(a, b) {
     return a.system === b.system && a.tools === b.tools && a.model === b.model;

package/dist/ai/http.d.ts

@@ -1,9 +1,13 @@
 /**
  * fetch 包装（设计 §1.2 ai/http.ts）：超时、头合并（值为 null 删除）、错误体读取。
  *
- * 代理：Node 的全局 fetch 缺省不读 HTTP(S)_PROXY。Node ≥ 24 设 `NODE_USE_ENV_PROXY=1`
- * 即可让 fetch 走环境变量代理；Node 22 需在启动参数里加 `--use-env-proxy`（22.21+）。
- * 本模块不自行实现代理，env 原样透传给运行时处理。
+ * 代理：Node 的全局 fetch 缺省不读 HTTP(S)_PROXY。CLI 启动时由 cli/proxy.ts 调 Node 内置的
+ * `http.setGlobalProxyFromEnv()`（等价于 `NODE_USE_ENV_PROXY=1`）；SDK 嵌入方自行决定。
+ * 本模块不自行实现代理。
+ *
+ * 超时：`timeoutMs` 只管到拿到响应头为止；`idleTimeoutMs`（缺省 300 s，0 关闭）既管等响应头，
+ * 也管流式读取期间两次收到数据之间的间隔（每收到一块字节即重新计时，见 sse.ts）。空闲超时抛
+ * `IdleTimeoutError`，文案含 `idle timeout`，会话层按可重试错误处理。
  *
  * 协议层自身**不重试**（重试在会话层，§3.6）。
  */
@@ -29,6 +33,21 @@ export declare class HttpError extends Error {
 export declare class RequestTimeoutError extends Error {
     constructor(timeoutMs: number);
 }
+/** 流空闲超时缺省值：与 `request.idleTimeoutMs` / `AMA_IDLE_TIMEOUT_MS` 的缺省一致。 */
+export declare const DEFAULT_IDLE_TIMEOUT_MS = 300000;
+/** 请求选项里的空闲超时；未给出用缺省值，0 或负数表示关闭（返回 undefined）。 */
+export declare function idleTimeoutOf(options: {
+    idleTimeoutMs?: number | undefined;
+}): number | undefined;
+/**
+ * 服务端在 `idleTimeoutMs` 内没有任何字节：`response` = 发出请求后迟迟没有响应头，
+ * `stream` = 流读到一半停住。文案含 `idle timeout`（重试分类据此判为可重试）。
+ */
+export declare class IdleTimeoutError extends Error {
+    readonly idleTimeoutMs: number;
+    readonly phase: "response" | "stream";
+    constructor(idleTimeoutMs: number, phase: "response" | "stream");
+}
 /**
  * 从错误体提取文本：识别 `{error:{type,message,code}}`、`{error:"..."}`、`{message}`、
  * `{detail}` 等常见形状；不是 JSON 则截断原文。结果形如 `429 rate_limit_error: ...`。
@@ -41,12 +60,15 @@ export interface PostOptions {
     body: unknown;
     signal: AbortSignal;
     timeoutMs?: number | undefined;
+    /** 等响应头的空闲上限（`timeoutMs` 未给时生效）；undefined 不限。 */
+    idleTimeoutMs?: number | undefined;
     onResponse?: ((status: number, headers: Headers) => void) | undefined;
 }
 /**
- * POST JSON 并返回 2xx 响应（body 是 SSE 字节流）。非 2xx → HttpError；超时 → RequestTimeoutError；
- * 调用方的 signal 中止 → 原样抛 AbortError（调用方据 signal.aborted 判 aborted）。
- * 超时只覆盖到拿到响应头为止，流式读取期间由调用方的 signal 控制。
+ * POST JSON 并返回 2xx 响应（body 是 SSE 字节流）。非 2xx → HttpError；超时 → RequestTimeoutError
+ * （`timeoutMs`）或 IdleTimeoutError（`idleTimeoutMs`）；调用方的 signal 中止 → 原样抛 AbortError
+ * （调用方据 signal.aborted 判 aborted）。超时只覆盖到拿到响应头为止，流式读取期间的空闲由
+ * `readSseEvents` 的 `idleTimeoutMs` 控制。
  */
 export declare function postJson(url: string, options: PostOptions): Promise<Response>;
 /** undici 的 `fetch failed` 把真正原因藏在 cause 里；拼出来便于重试分类与排错。 */

package/dist/ai/http.js

@@ -1,9 +1,13 @@
 /**
  * fetch 包装（设计 §1.2 ai/http.ts）：超时、头合并（值为 null 删除）、错误体读取。
  *
- * 代理：Node 的全局 fetch 缺省不读 HTTP(S)_PROXY。Node ≥ 24 设 `NODE_USE_ENV_PROXY=1`
- * 即可让 fetch 走环境变量代理；Node 22 需在启动参数里加 `--use-env-proxy`（22.21+）。
- * 本模块不自行实现代理，env 原样透传给运行时处理。
+ * 代理：Node 的全局 fetch 缺省不读 HTTP(S)_PROXY。CLI 启动时由 cli/proxy.ts 调 Node 内置的
+ * `http.setGlobalProxyFromEnv()`（等价于 `NODE_USE_ENV_PROXY=1`）；SDK 嵌入方自行决定。
+ * 本模块不自行实现代理。
+ *
+ * 超时：`timeoutMs` 只管到拿到响应头为止；`idleTimeoutMs`（缺省 300 s，0 关闭）既管等响应头，
+ * 也管流式读取期间两次收到数据之间的间隔（每收到一块字节即重新计时，见 sse.ts）。空闲超时抛
+ * `IdleTimeoutError`，文案含 `idle timeout`，会话层按可重试错误处理。
  *
  * 协议层自身**不重试**（重试在会话层，§3.6）。
  */
@@ -76,6 +80,33 @@ export class RequestTimeoutError extends Error {
         this.name = "RequestTimeoutError";
     }
 }
+/** 流空闲超时缺省值：与 `request.idleTimeoutMs` / `AMA_IDLE_TIMEOUT_MS` 的缺省一致。 */
+export const DEFAULT_IDLE_TIMEOUT_MS = 300_000;
+/** 请求选项里的空闲超时；未给出用缺省值，0 或负数表示关闭（返回 undefined）。 */
+export function idleTimeoutOf(options) {
+    const value = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+    return Number.isFinite(value) && value > 0 ? value : undefined;
+}
+function formatDuration(ms) {
+    return ms >= 1000 && ms % 1000 === 0 ? `${ms / 1000} s` : `${ms} ms`;
+}
+/**
+ * 服务端在 `idleTimeoutMs` 内没有任何字节：`response` = 发出请求后迟迟没有响应头，
+ * `stream` = 流读到一半停住。文案含 `idle timeout`（重试分类据此判为可重试）。
+ */
+export class IdleTimeoutError extends Error {
+    idleTimeoutMs;
+    phase;
+    constructor(idleTimeoutMs, phase) {
+        const what = phase === "response"
+            ? `No response from the server within ${formatDuration(idleTimeoutMs)}`
+            : `Stream stalled: no data from the server for ${formatDuration(idleTimeoutMs)}`;
+        super(`${what} (idle timeout; adjust with request.idleTimeoutMs or AMA_IDLE_TIMEOUT_MS)`);
+        this.name = "IdleTimeoutError";
+        this.idleTimeoutMs = idleTimeoutMs;
+        this.phase = phase;
+    }
+}
 const MAX_ERROR_BODY = 4000;
 /**
  * 从错误体提取文本：识别 `{error:{type,message,code}}`、`{error:"..."}`、`{message}`、
@@ -141,12 +172,14 @@ function parseRetryAfter(headers) {
     return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
 }
 /**
- * POST JSON 并返回 2xx 响应（body 是 SSE 字节流）。非 2xx → HttpError；超时 → RequestTimeoutError；
- * 调用方的 signal 中止 → 原样抛 AbortError（调用方据 signal.aborted 判 aborted）。
- * 超时只覆盖到拿到响应头为止，流式读取期间由调用方的 signal 控制。
+ * POST JSON 并返回 2xx 响应（body 是 SSE 字节流）。非 2xx → HttpError；超时 → RequestTimeoutError
+ * （`timeoutMs`）或 IdleTimeoutError（`idleTimeoutMs`）；调用方的 signal 中止 → 原样抛 AbortError
+ * （调用方据 signal.aborted 判 aborted）。超时只覆盖到拿到响应头为止，流式读取期间的空闲由
+ * `readSseEvents` 的 `idleTimeoutMs` 控制。
  */
 export async function postJson(url, options) {
-    const timeout = options.timeoutMs;
+    const explicit = options.timeoutMs !== undefined && options.timeoutMs > 0;
+    const timeout = explicit ? options.timeoutMs : options.idleTimeoutMs;
     const timer = new AbortController();
     const handle = timeout !== undefined && timeout > 0 ? setTimeout(() => timer.abort(), timeout) : undefined;
     const signal = AbortSignal.any([options.signal, timer.signal]);
@@ -161,7 +194,7 @@ export async function postJson(url, options) {
     }
     catch (error) {
         if (timer.signal.aborted && !options.signal.aborted && timeout !== undefined) {
-            throw new RequestTimeoutError(timeout);
+            throw explicit ? new RequestTimeoutError(timeout) : new IdleTimeoutError(timeout, "response");
         }
         throw normalizeNetworkError(error);
     }