@armadra/agent 0.3.0 → 0.4.0

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

@@ -13,6 +13,7 @@
 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";
@@ -53,6 +54,7 @@ export class AgentSessionImpl {
     systemInput;
     subagentPool;
     disposed = false;
+    classifier;
     /** 已入队、尚未投递的消息（投递时发 queue_update）。 */
     queuedMessages = new WeakSet();
     constructor(options) {
@@ -103,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();
@@ -479,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";
@@ -249,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 });
@@ -260,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/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);
     }

package/dist/ai/providers/registry.d.ts

@@ -90,10 +90,17 @@ export declare class ProviderRegistry implements ProviderRegistryApi {
     /** 追加 / 替换模型（例如本地枚举得到的 ollama 模型）。 */
     addModels(providerId: string, models: readonly Model[], source?: ModelSource): void;
     private synthesize;
-    /** 按渠道取模型：渠道不在模型的 channels 里 → 列出可用渠道。 */
+    /** 按渠道取模型：渠道不在模型的 channels 里 → channel_not_found，列出可用渠道。 */
     private withChannel;
+    /**
+     * `provider/model`、`provider/model@渠道` 或裸模型 id。`@` 先按渠道解析（id 里本来就带 `@` 且已登记的
+     * 模型除外），中转供应商的「未登记即合成」不会把 `@渠道` 吞进模型 id。失败的 reason：供应商不存在 →
+     * provider_not_found（候选是编辑距离最近的供应商）；渠道不存在 → channel_not_found；模型不存在 →
+     * not_found（候选是最接近的模型）。
+     */
     findModel(ref: string): ModelLookup;
     private findPlain;
+    /** 最接近的模型（包含关系优先，其次编辑距离），`provider/id` 形式。 */
     private similar;
     hasConfiguredKey(providerId: string): boolean;
     resolveApiKey(providerId: string, channel?: string): Promise<ApiKeyResolution>;

package/dist/ai/providers/registry.js

@@ -30,6 +30,7 @@ import { BUILTIN_PROVIDERS, fallbackEnvKey, isRelayedBaseUrl } from "./builtin.j
 import { applyModelOverride, loadBuiltinCatalog, toModel, withCustomDefaults } from "./catalog.js";
 import { channelKeyId, modelChannels, parseChannels, splitChannelRef } from "./channels.js";
 import { catalogMetadata, enrichEntry, lazyIndex, } from "./enrich.js";
+import { closest } from "./suggest.js";
 /**
  * 物化：模型补齐供应商级字段（不可变：返回新对象）。给了 `channel` 时协议与地址取渠道的（模型级
  * `explicit` 覆盖优先），headers / compat 按 供应商 ← 渠道 ← 模型 合并，并记下渠道名。
@@ -326,36 +327,40 @@ export class ProviderRegistry {
         const channelData = provider.channels?.find((c) => c.name === (channel ?? model.channels?.[0]));
         return materializeModel(model, provider, channelData);
     }
-    /** 按渠道取模型：渠道不在模型的 channels 里 → 列出可用渠道。 */
+    /** 按渠道取模型：渠道不在模型的 channels 里 → channel_not_found，列出可用渠道。 */
     withChannel(provider, model, channel) {
         const available = model.channels ?? [];
-        if (!available.includes(channel)) {
+        if (!available.includes(channel) || !provider.channels?.some((c) => c.name === channel)) {
             return {
                 ok: false,
-                reason: "not_found",
-                candidates: available.map((c) => `${provider.id}/${model.id}@${c}`),
+                reason: "channel_not_found",
+                candidates: available.filter(Boolean).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 };
     }
+    /**
+     * `provider/model`、`provider/model@渠道` 或裸模型 id。`@` 先按渠道解析（id 里本来就带 `@` 且已登记的
+     * 模型除外），中转供应商的「未登记即合成」不会把 `@渠道` 吞进模型 id。失败的 reason：供应商不存在 →
+     * provider_not_found（候选是编辑距离最近的供应商）；渠道不存在 → channel_not_found；模型不存在 →
+     * not_found（候选是最接近的模型）。
+     */
     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;
+            return this.findPlain(trimmed);
+        const exact = this.findPlain(trimmed, undefined, false);
+        if (exact.ok)
+            return exact;
         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 base;
         return this.withChannel(base.provider, base.model, split.channel);
     }
-    findPlain(trimmed, channel) {
+    findPlain(trimmed, channel, synthesize = true) {
         const slash = trimmed.indexOf("/");
         if (slash > 0) {
             const provider = this.providers.get(trimmed.slice(0, slash));
@@ -364,7 +369,8 @@ export class ProviderRegistry {
                 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 relayed = provider.models.length === 0 || this.relayed.has(provider.id);
+                if (synthesize && relayed && 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])];
@@ -374,6 +380,14 @@ export class ProviderRegistry {
             }
         }
         const matches = this.listModels().filter((entry) => entry.model.id === trimmed);
+        if (matches.length === 0 && slash > 0) {
+            const ids = [...this.providers.keys()];
+            return {
+                ok: false,
+                reason: "provider_not_found",
+                candidates: closest(trimmed.slice(0, slash), ids),
+            };
+        }
         if (matches.length === 1 && matches[0]) {
             return { ok: true, model: matches[0].model, provider: matches[0].provider };
         }
@@ -390,16 +404,10 @@ export class ProviderRegistry {
             candidates: (configured.length > 0 ? configured : matches).map((entry) => `${entry.provider.id}/${entry.model.id}`),
         };
     }
+    /** 最接近的模型（包含关系优先，其次编辑距离），`provider/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}`);
+        const entries = this.listModels().filter((entry) => providerId === undefined || entry.provider.id === providerId);
+        return closest(id, entries, 5, (entry) => entry.model.id).map((entry) => `${entry.provider.id}/${entry.model.id}`);
     }
     hasConfiguredKey(providerId) {
         const provider = this.providers.get(providerId);

package/dist/ai/providers/suggest.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 模型 / 供应商 / 渠道写错时的候选与报错文案（W4-C）。
+ *
+ * 候选排序：包含关系（`sonnet` ⊂ `claude-sonnet-5`）优先，其次按编辑距离；距离超过
+ * `max(2, ⌈长度 / 3⌉)` 的不算接近。只比较 id 本身（不含 `provider/` 前缀），大小写不敏感。
+ */
+import type { ModelLookup } from "../types.js";
+/** Levenshtein 距离（插入 / 删除 / 替换各计 1）。 */
+export declare function editDistance(a: string, b: string): number;
+/**
+ * 从 `candidates` 里挑与 `needle` 最接近的至多 `limit` 个。`key` 取参与比较的部分
+ * （缺省整串），返回原值。
+ */
+export declare function closest<T>(needle: string, candidates: readonly T[], limit?: number, key?: (item: T) => string): T[];
+/** 解析失败的一行说明（不含前缀标签）：`渠道不存在：x；该模型可用渠道：…` 等。 */
+export declare function describeLookupFailure(ref: string, failure: Extract<ModelLookup, {
+    ok: false;
+}>): string;

package/dist/ai/providers/suggest.js

@@ -0,0 +1,72 @@
+/**
+ * 模型 / 供应商 / 渠道写错时的候选与报错文案（W4-C）。
+ *
+ * 候选排序：包含关系（`sonnet` ⊂ `claude-sonnet-5`）优先，其次按编辑距离；距离超过
+ * `max(2, ⌈长度 / 3⌉)` 的不算接近。只比较 id 本身（不含 `provider/` 前缀），大小写不敏感。
+ */
+/** Levenshtein 距离（插入 / 删除 / 替换各计 1）。 */
+export function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const row = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            row[j] = Math.min((prev[j] ?? 0) + 1, (row[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+        }
+        prev = row;
+    }
+    return prev[b.length] ?? 0;
+}
+/**
+ * 从 `candidates` 里挑与 `needle` 最接近的至多 `limit` 个。`key` 取参与比较的部分
+ * （缺省整串），返回原值。
+ */
+export function closest(needle, candidates, limit = 5, key = String) {
+    const target = needle.toLowerCase();
+    if (target === "")
+        return [];
+    const budget = Math.max(2, Math.ceil(target.length / 3));
+    const scored = [];
+    candidates.forEach((item, index) => {
+        const value = key(item).toLowerCase();
+        if (value === "")
+            return;
+        if (value.includes(target) || target.includes(value)) {
+            scored.push({ item, score: Math.abs(value.length - target.length) / 1000, index });
+            return;
+        }
+        const distance = editDistance(target, value);
+        if (distance <= budget)
+            scored.push({ item, score: distance, index });
+    });
+    return scored
+        .sort((a, b) => a.score - b.score || a.index - b.index)
+        .slice(0, limit)
+        .map((entry) => entry.item);
+}
+/** 解析失败的一行说明（不含前缀标签）：`渠道不存在：x；该模型可用渠道：…` 等。 */
+export function describeLookupFailure(ref, failure) {
+    const list = failure.candidates.slice(0, 20).join(", ");
+    switch (failure.reason) {
+        case "channel_not_found":
+            return failure.candidates.length > 0
+                ? `渠道不存在：${ref}；该模型可用渠道：${list}`
+                : `渠道不存在：${ref}；该模型没有可选渠道（去掉 @ 后缀）`;
+        case "provider_not_found":
+            return failure.candidates.length > 0
+                ? `供应商不存在：${ref}；最接近的供应商：${list}`
+                : `供应商不存在：${ref}（ama providers list 查看已配置的供应商）`;
+        case "ambiguous":
+            return `模型名有歧义：${ref}；候选：${list}`;
+        default:
+            return failure.candidates.length > 0
+                ? `模型不存在：${ref}；最接近的模型：${list}`
+                : `模型不存在：${ref}（ama models list 查看可用模型）`;
+    }
+}

package/dist/ai/sse.d.ts

@@ -28,5 +28,9 @@ export declare class SseParser {
     private processLine;
     private dispatch;
 }
-/** 从字节流读 SSE 事件；`signal` 中止时停止读取（调用方据此产出 aborted）。 */
-export declare function readSseEvents(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<SseEvent>;
+/**
+ * 从字节流读 SSE 事件；`signal` 中止时停止读取（调用方据此产出 aborted）。
+ * `idleTimeoutMs`：等待下一块字节的上限，每收到一块即重新计时（消费者处理事件的时间不计）；
+ * 超时取消底层流并抛 `IdleTimeoutError`（phase `stream`）。
+ */
+export declare function readSseEvents(body: ReadableStream<Uint8Array>, signal?: AbortSignal, idleTimeoutMs?: number): AsyncGenerator<SseEvent>;