@ai-setting/roy-agent-core 1.7.62 → 1.7.63

package/dist/env/agent/agent-component.d.ts

@@ -231,6 +231,19 @@ export declare class AgentComponent extends BaseComponent {
     private abortControllers;
     private defaultTools;
     private doomLoopCaches;
+    /**
+     * Task #4623 — per-run fallback state.
+     *
+     * Keyed by runId. The value is the model that the run has *already* been
+     * downgraded to (or the primary model, once a downgrade happened).
+     *
+     * ⚠️ Why per-run and not global: a quota exhaustion is a durable condition
+     * for the *current* run, but the next run may legitimately want the primary
+     * model again (e.g. the user fixed the key). Scoping the sticky state to a
+     * single run keeps the behaviour predictable and prevents a permanently
+     * downgraded agent.
+     */
+    private fallbackState;
     /** ConfigComponent 用于配置管理 */
     private configComponent?;
     /** 配置变更 watcher 清理函数 */
@@ -531,6 +544,26 @@ export declare class AgentComponent extends BaseComponent {
      * —— 入参 ctx 带全量消息，返回值是完整模型输出。
      */
     private invokeLLM;
+    /**
+     * Task #4623 — 解析最终的 fallback model。
+     *
+     * 优先级：AgentContext.fallbackModel（CLI `--fallback-model`）> 配置 `llm.fallbackModel`。
+     * 若结果只有 modelId（无 `provider/` 前缀）且配置了 `llm.fallbackProvider`，
+     * 则补成 `providerId/modelId`（与 `--model` 同语义）。
+     */
+    private resolveFallbackModel;
+    /**
+     * review P2-3 — 判断两个 model 标识是否"同一个模型"。
+     *
+     * `"GLM-5.3-Flash"` 与 `"tong/GLM-5.3-Flash"` 指向同一模型，仅前缀不同；
+     * 若按字符串严格比较会误判为"换了模型"，白跑一次注定失败的 primary。
+     */
+    private static sameModel;
+    /**
+     * Task #4623 — 归一化 LLM 返回值为内部 AgentLLMOutput。
+     * 抽成方法以便 primary / fallback 两条路径共用同一套映射。
+     */
+    private normalizeLLMOutput;
     /**
      * Task #2723: 归一化上游 tool-call shape → 内部 `Record<string, unknown>`。
      *

package/dist/env/agent/agent-component.js

@@ -7,16 +7,17 @@ import {
   filterToolsByAgent,
   parseToolList,
   toLLMMessage
-} from "../../shared/@ai-setting/roy-agent-core-5bj0xfjk.js";
+} from "../../shared/@ai-setting/roy-agent-core-g23yp3t1.js";
 import"../../shared/@ai-setting/roy-agent-core-w2ev3z5q.js";
 import"../../shared/@ai-setting/roy-agent-core-wzp4tbsn.js";
 import"../../shared/@ai-setting/roy-agent-core-06jakebr.js";
 import"../../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";
 import"../../shared/@ai-setting/roy-agent-core-p8rf4z89.js";
-import"../../shared/@ai-setting/roy-agent-core-x1d6edkh.js";
-import"../../shared/@ai-setting/roy-agent-core-9qgrc9dy.js";
+import"../../shared/@ai-setting/roy-agent-core-rfhxj8v2.js";
+import"../../shared/@ai-setting/roy-agent-core-03k5drfp.js";
 import"../../shared/@ai-setting/roy-agent-core-zjdzk1gg.js";
 import"../../shared/@ai-setting/roy-agent-core-c1v263jn.js";
+import"../../shared/@ai-setting/roy-agent-core-ntn32q7j.js";
 import"../../shared/@ai-setting/roy-agent-core-e25xkv53.js";
 import"../../shared/@ai-setting/roy-agent-core-ctdhjv68.js";
 import"../../shared/@ai-setting/roy-agent-core-7hh0brvs.js";

package/dist/env/agent/index.js

@@ -4,16 +4,17 @@ import {
 import {
   AgentComponent,
   AgentComponentConfigSchema
-} from "../../shared/@ai-setting/roy-agent-core-5bj0xfjk.js";
+} from "../../shared/@ai-setting/roy-agent-core-g23yp3t1.js";
 import"../../shared/@ai-setting/roy-agent-core-w2ev3z5q.js";
 import"../../shared/@ai-setting/roy-agent-core-wzp4tbsn.js";
 import"../../shared/@ai-setting/roy-agent-core-06jakebr.js";
 import"../../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";
 import"../../shared/@ai-setting/roy-agent-core-p8rf4z89.js";
-import"../../shared/@ai-setting/roy-agent-core-x1d6edkh.js";
-import"../../shared/@ai-setting/roy-agent-core-9qgrc9dy.js";
+import"../../shared/@ai-setting/roy-agent-core-rfhxj8v2.js";
+import"../../shared/@ai-setting/roy-agent-core-03k5drfp.js";
 import"../../shared/@ai-setting/roy-agent-core-zjdzk1gg.js";
 import"../../shared/@ai-setting/roy-agent-core-c1v263jn.js";
+import"../../shared/@ai-setting/roy-agent-core-ntn32q7j.js";
 import"../../shared/@ai-setting/roy-agent-core-e25xkv53.js";
 import"../../shared/@ai-setting/roy-agent-core-ctdhjv68.js";
 import"../../shared/@ai-setting/roy-agent-core-7hh0brvs.js";

package/dist/env/agent/types.d.ts

@@ -41,6 +41,16 @@ export interface AgentContext {
     agentType?: string;
     /** 使用的模型 */
     model?: string;
+    /**
+     * Task #4623 — 兜底模型（`providerId/modelId`）。
+     *
+     * 主模型调用失败（404 / 429 / 配额耗尽 / 5xx / 超时 / 重试耗尽）时，
+     * 本次 run 自动切换到该模型继续执行。优先级：
+     *   CLI `--fallback-model` > AgentContext.fallbackModel > 配置 `llm.fallbackModel`
+     *
+     * 认证失败（401/403）、请求错误（400）、主动取消、上下文超限 **不** 触发降级。
+     */
+    fallbackModel?: string;
     /** 允许的工具列表（上下文级别，会覆盖 agent 配置） */
     allowedTools?: string[];
     /** 拒绝的工具列表（上下文级别，会覆盖 agent 配置） */
@@ -224,6 +234,13 @@ export interface HookContext {
     };
     /** 执行上下文（可直接修改属性） */
     context: AgentContext;
+    /**
+     * Task #4623 — 本次 run 的唯一 ID（internal use）。
+     *
+     * 仅用于把「本次 run 已降级到 fallback model」的粘性状态 key 到 run 维度，
+     * 避免跨 run 串味（上一轮额度耗尽不代表下一轮还失效）。
+     */
+    _runId?: string;
     /** 是否已停止 */
     _stopped?: boolean;
     /** 停止原因 */

package/dist/env/error-reply.d.ts

@@ -72,7 +72,7 @@
  *
  * 顺序即优先级：越具体的越先匹配。
  */
-export type ReactFailureKind = "ask_user" | "upstream_retry" | "timeout" | "upstream_aborted" | "aborted" | "context_overflow" | "unknown";
+export type ReactFailureKind = "ask_user" | "quota_exhausted" | "upstream_retry" | "timeout" | "upstream_aborted" | "aborted" | "context_overflow" | "unknown";
 export interface ReactFailureInfo {
     kind: ReactFailureKind;
     /** 命中的规则 id（可观测性 / 测试锚点） */
@@ -92,6 +92,16 @@ export interface ReactFailureInfo {
     notify: boolean;
     /** 技术细节（截断，供定位；不直接展示给用户） */
     technical?: string;
+    /** 上游声明的恢复窗口（秒），来自 `Retry-After`。无法判定时 undefined */
+    retryAfterSeconds?: number;
+    /**
+     * 「你可以怎么办」的替代建议。
+     *
+     * 默认由 `retryable` 推导（true → 重发；false → 压缩/新开会话），但有些
+     * 失败两者都不对 —— 例如额度用尽：重发无用，压缩会话也无用，唯一出路
+     * 是换模型 / 充值 / 等。规则可以在这里覆盖默认文案。
+     */
+    suggestion?: string;
 }
 /** replyChannel 的最小形态（同时兼容 EnvReplyChannel / event-source ReplyChannel） */
 export interface FailureReplyChannelLike {
@@ -140,6 +150,26 @@ export interface NotifyReactFailureResult {
     /** 投递错误（sent=false 且确实尝试过时有值） */
     error?: string;
 }
+/**
+ * 从任意错误对象里挖出 `Retry-After`（秒）。
+ *
+ * 上游把窗口放在哪一层并不统一：
+ * - `error.headers["retry-after"]`            (openai SDK 挂在 error 上)
+ * - `error.responseHeaders["retry-after"]`    (AI SDK APICallError)
+ * - `error.data.error.retry_after`            (自定义 body)
+ * - `error.retryAfter` / `error.retry_after`  (扁平形态)
+ *
+ * 也会处理 HTTP-date 形态（`Wed, 21 Oct 2026 07:28:00 GMT`），因为它合法。
+ * 返回值单位是秒，无法判定时返回 undefined（**绝不猜**）。
+ */
+export declare function extractRetryAfterSeconds(error: unknown, depth?: number): number | undefined;
+/**
+ * 把秒数说成人话（"约 22 小时后恢复"）。
+ *
+ * 只在**粗粒度**上承诺时间：22.008h 说成 "约 22 小时"，避免给出虚假精度。
+ * < 90s 说明「很快」，分钟级/小时级分别取整。
+ */
+export declare function humanizeRetryAfter(seconds: number | undefined): string | undefined;
 /** 当前生效的规则 id 列表（供可观测性 / 文档 / 测试锚定顺序）。 */
 export declare function getFailureRuleIds(): string[];
 /**
@@ -162,6 +192,28 @@ export declare function buildFailureReplyMarkdown(info: ReactFailureInfo, opts?:
     query?: string;
     sessionId?: string;
 }): string;
+/**
+ * Task #4625：把任意失败压成**一行**给 CLI 用户看的说明。
+ *
+ * ## 为什么 CLI 需要这个（而飞书不需要）
+ *
+ * 飞书路径走 `buildFailureReplyMarkdown`，正文可以有标题/建议/技术细节。
+ * CLI 路径（`act.ts` catch）只有一行 `output.error("执行失败: " + message)`，
+ * 而 `message` 是上游原文 + AI SDK 的 `RetryError` 前缀：
+ *
+ *     ✗ 执行失败: Failed after 4 attempts. Last error: Free usage limit
+ *       reached. Free models work in OpenCode (https://opencode.ai); ...
+ *
+ * 对额度用尽这种"重试无用"的失败，这句话既没说清是什么问题，也没说
+ * 多久能恢复 —— 用户唯一能做的就是反复重试。
+ *
+ * ## 产出契约
+ *
+ * - **单行**、无 `\n`、长度 < 300（不进 stack）
+ * - 额度类失败必须带恢复窗口（"约 22 小时后"）
+ * - 其他失败退回分类规则的 `title`，保证**任何**错误都不空串
+ */
+export declare function formatCliFailureLine(error: unknown): string;
 /** 测试用：清空去重状态 */
 export declare function __resetFailureReplyDedupForTest(): void;
 /**

package/dist/env/error-reply.js

@@ -2,16 +2,23 @@ import {
   __resetFailureReplyDedupForTest,
   buildFailureReplyMarkdown,
   classifyReactFailure,
+  extractRetryAfterSeconds,
+  formatCliFailureLine,
   getFailureRuleIds,
+  humanizeRetryAfter,
   notifyReactFailure
-} from "../shared/@ai-setting/roy-agent-core-9nvyffxg.js";
+} from "../shared/@ai-setting/roy-agent-core-va4m04e8.js";
+import"../shared/@ai-setting/roy-agent-core-ntn32q7j.js";
 import"../shared/@ai-setting/roy-agent-core-m880qz3y.js";
 import"../shared/@ai-setting/roy-agent-core-6awgfh3x.js";
 import"../shared/@ai-setting/roy-agent-core-jnszp0jq.js";
 import"../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";
 export {
   notifyReactFailure,
+  humanizeRetryAfter,
   getFailureRuleIds,
+  formatCliFailureLine,
+  extractRetryAfterSeconds,
   classifyReactFailure,
   buildFailureReplyMarkdown,
   __resetFailureReplyDedupForTest

package/dist/env/event-source/event-source-handlers.js

@@ -10,9 +10,9 @@ import {
   patchCardByLarkCli,
   renderRuleNoticeSection,
   timerHandler
-} from "../../shared/@ai-setting/roy-agent-core-nmn853z0.js";
+} from "../../shared/@ai-setting/roy-agent-core-t6nx0rsz.js";
 import"../../shared/@ai-setting/roy-agent-core-bxkjk7zx.js";
-import"../../shared/@ai-setting/roy-agent-core-9nvyffxg.js";
+import"../../shared/@ai-setting/roy-agent-core-va4m04e8.js";
 import {
   cliCommandHandler
 } from "../../shared/@ai-setting/roy-agent-core-p37kh0kt.js";
@@ -29,6 +29,7 @@ import"../../shared/@ai-setting/roy-agent-core-kmvw6b4v.js";
 import"../../shared/@ai-setting/roy-agent-core-p6a4v4fq.js";
 import"../../shared/@ai-setting/roy-agent-core-jrj30vq3.js";
 import"../../shared/@ai-setting/roy-agent-core-p8rf4z89.js";
+import"../../shared/@ai-setting/roy-agent-core-ntn32q7j.js";
 import"../../shared/@ai-setting/roy-agent-core-e25xkv53.js";
 import"../../shared/@ai-setting/roy-agent-core-m880qz3y.js";
 import"../../shared/@ai-setting/roy-agent-core-az13yzmc.js";

package/dist/env/event-source/index.js

@@ -1,7 +1,7 @@
 import"../../shared/@ai-setting/roy-agent-core-5enxfga2.js";
 import {
   EventSourceComponent
-} from "../../shared/@ai-setting/roy-agent-core-w2h6xt6k.js";
+} from "../../shared/@ai-setting/roy-agent-core-g6pw4esq.js";
 import {
   BountyIMInstance,
   TimerInstance,
@@ -13,7 +13,7 @@ import {
   larkCliHandler,
   resolveBountyIMSystemPrompt,
   timerHandler
-} from "../../shared/@ai-setting/roy-agent-core-nmn853z0.js";
+} from "../../shared/@ai-setting/roy-agent-core-t6nx0rsz.js";
 import {
   BUILT_IN_EVENT_SOURCE_TYPES,
   BUILT_IN_EVENT_SOURCE_TYPE_LIST,
@@ -23,7 +23,7 @@ import {
   isValidEventSourceType,
   validateEventSourceConfig
 } from "../../shared/@ai-setting/roy-agent-core-bxkjk7zx.js";
-import"../../shared/@ai-setting/roy-agent-core-9nvyffxg.js";
+import"../../shared/@ai-setting/roy-agent-core-va4m04e8.js";
 import {
   CLI_COMMAND_ES_TYPE,
   CLI_SESSION_CHAT_ID_PREFIX,
@@ -49,6 +49,7 @@ import"../../shared/@ai-setting/roy-agent-core-kmvw6b4v.js";
 import"../../shared/@ai-setting/roy-agent-core-p6a4v4fq.js";
 import"../../shared/@ai-setting/roy-agent-core-jrj30vq3.js";
 import"../../shared/@ai-setting/roy-agent-core-p8rf4z89.js";
+import"../../shared/@ai-setting/roy-agent-core-ntn32q7j.js";
 import"../../shared/@ai-setting/roy-agent-core-e25xkv53.js";
 import"../../shared/@ai-setting/roy-agent-core-m880qz3y.js";
 import"../../shared/@ai-setting/roy-agent-core-az13yzmc.js";

package/dist/env/index.js

@@ -1,12 +1,12 @@
 import {
   BaseEnvironment
-} from "../shared/@ai-setting/roy-agent-core-gz2jnaan.js";
+} from "../shared/@ai-setting/roy-agent-core-b4zdm2n4.js";
 import {
   TaskComponent
-} from "../shared/@ai-setting/roy-agent-core-cqpd41gf.js";
+} from "../shared/@ai-setting/roy-agent-core-5hq4v41q.js";
 import"../shared/@ai-setting/roy-agent-core-amkqnyzy.js";
 import"../shared/@ai-setting/roy-agent-core-jm136jzh.js";
-import"../shared/@ai-setting/roy-agent-core-fqandv0a.js";
+import"../shared/@ai-setting/roy-agent-core-gnt23yx0.js";
 import"../shared/@ai-setting/roy-agent-core-jw63js86.js";
 import"../shared/@ai-setting/roy-agent-core-5mrynf9g.js";
 import"../shared/@ai-setting/roy-agent-core-8gxth0eh.js";
@@ -14,11 +14,11 @@ import"../shared/@ai-setting/roy-agent-core-as0dd70m.js";
 import"../shared/@ai-setting/roy-agent-core-rn57psp0.js";
 import {
   EventSourceComponent
-} from "../shared/@ai-setting/roy-agent-core-w2h6xt6k.js";
+} from "../shared/@ai-setting/roy-agent-core-g6pw4esq.js";
 import {
   builtInHandlers,
   larkCliHandler
-} from "../shared/@ai-setting/roy-agent-core-nmn853z0.js";
+} from "../shared/@ai-setting/roy-agent-core-t6nx0rsz.js";
 import {
   EventSourceInitHooks,
   getDefaultConfigForType,
@@ -26,7 +26,7 @@ import {
   isValidEventSourceType,
   validateEventSourceConfig
 } from "../shared/@ai-setting/roy-agent-core-bxkjk7zx.js";
-import"../shared/@ai-setting/roy-agent-core-9nvyffxg.js";
+import"../shared/@ai-setting/roy-agent-core-va4m04e8.js";
 import"../shared/@ai-setting/roy-agent-core-p37kh0kt.js";
 import"../shared/@ai-setting/roy-agent-core-anb53t3v.js";
 import"../shared/@ai-setting/roy-agent-core-ye4bfzqg.js";
@@ -38,13 +38,13 @@ import"../shared/@ai-setting/roy-agent-core-cxpgd415.js";
 import"../shared/@ai-setting/roy-agent-core-m3w3ytxt.js";
 import {
   WorkflowComponent
-} from "../shared/@ai-setting/roy-agent-core-h3fwjbhp.js";
+} from "../shared/@ai-setting/roy-agent-core-ebws32tv.js";
 import"../shared/@ai-setting/roy-agent-core-dfqhc9ey.js";
 import"../shared/@ai-setting/roy-agent-core-h0x19xgn.js";
 import"../shared/@ai-setting/roy-agent-core-1ce3fqrk.js";
-import"../shared/@ai-setting/roy-agent-core-fr296a53.js";
-import"../shared/@ai-setting/roy-agent-core-48h4zh60.js";
-import"../shared/@ai-setting/roy-agent-core-2veqhrxa.js";
+import"../shared/@ai-setting/roy-agent-core-60f7h284.js";
+import"../shared/@ai-setting/roy-agent-core-bm3gav5d.js";
+import"../shared/@ai-setting/roy-agent-core-1dnsk6ht.js";
 import"../shared/@ai-setting/roy-agent-core-hhrg314p.js";
 import"../shared/@ai-setting/roy-agent-core-6wxww10t.js";
 import"../shared/@ai-setting/roy-agent-core-bpvz1dqr.js";
@@ -66,7 +66,7 @@ import"../shared/@ai-setting/roy-agent-core-jagkferh.js";
 import {
   AgentComponent,
   AgentComponentConfigSchema
-} from "../shared/@ai-setting/roy-agent-core-5bj0xfjk.js";
+} from "../shared/@ai-setting/roy-agent-core-g23yp3t1.js";
 import"../shared/@ai-setting/roy-agent-core-w2ev3z5q.js";
 import"../shared/@ai-setting/roy-agent-core-wzp4tbsn.js";
 import"../shared/@ai-setting/roy-agent-core-06jakebr.js";
@@ -76,10 +76,11 @@ import {
   getXDGPaths
 } from "../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";
 import"../shared/@ai-setting/roy-agent-core-p8rf4z89.js";
-import"../shared/@ai-setting/roy-agent-core-x1d6edkh.js";
-import"../shared/@ai-setting/roy-agent-core-9qgrc9dy.js";
+import"../shared/@ai-setting/roy-agent-core-rfhxj8v2.js";
+import"../shared/@ai-setting/roy-agent-core-03k5drfp.js";
 import"../shared/@ai-setting/roy-agent-core-zjdzk1gg.js";
 import"../shared/@ai-setting/roy-agent-core-c1v263jn.js";
+import"../shared/@ai-setting/roy-agent-core-ntn32q7j.js";
 import"../shared/@ai-setting/roy-agent-core-e25xkv53.js";
 import {
   PluginComponent

package/dist/env/llm/adapter-pi-ai.d.ts

@@ -166,6 +166,53 @@ export declare function buildPiCacheOptions(args: {
 export declare function resolvePiModel(provider: string, modelId: string, baseURL?: string, capabilities?: {
     reasoning?: boolean;
 }): Model<any>;
+/**
+ * Task #4625 — capture the upstream HTTP response so `Retry-After` survives.
+ *
+ * ## Why a hook is the only way
+ *
+ * pi-ai flattens every provider failure into `AssistantMessage.errorMessage`,
+ * a plain string (`openai-completions.js:314-327` does exactly
+ * `output.errorMessage = error.message`). `responseHeaders` are dropped on the
+ * floor. So by the time roy-agent sees `stopReason === "error"`, the only
+ * remaining trace of "how long until the quota resets" is what we saved
+ * ourselves.
+ *
+ * `onResponse` is pi-ai's public hook for that moment — it fires right after
+ * `.withResponse()` resolves, *before* the body is consumed
+ * (`openai-completions.js:90`), with `{status, headers}`.
+ *
+ * ## Why it captures unconditionally
+ *
+ * The hook cannot know in advance whether this response will become an error
+ * (a 200 can still fail later while streaming). Capturing every response costs
+ * one object allocation per request and lets `enrichProviderError()` decide
+ * afterwards. Skipping non-error statuses would risk losing the very headers we
+ * need when a `2xx` starts streaming and then dies.
+ */
+export interface CapturedProviderResponse {
+    status: number;
+    headers: Record<string, string>;
+}
+export declare function createResponseCapture(): {
+    onResponse: (response: CapturedProviderResponse) => void;
+    captured: () => CapturedProviderResponse | undefined;
+};
+/**
+ * Task #4625 — attach the captured HTTP response to a failed pi-ai result.
+ *
+ * pi-ai reports failures as `{stopReason:"error", errorMessage}` rather than by
+ * throwing, so roy-agent has to turn that into a real `Error` for the caller to
+ * fall back on. Throwing a *bare* `new Error(errorMessage)` was how the
+ * `Retry-After` got lost: the message string cannot carry headers.
+ *
+ * The captured response is attached twice on purpose:
+ * - as `responseHeaders`, the shape `@ai-sdk/provider`'s `APICallError` uses, so
+ *   `extractRetryAfterSeconds()` finds it on the first branch it tries;
+ * - as `cause`, so anything that only walks `cause` (including
+ *   `collectErrorText()`, which builds the user-facing text) also sees it.
+ */
+export declare function buildProviderError(message: string, captured: CapturedProviderResponse | undefined, knownSecrets?: Array<string | undefined>): Error;
 /**
  * 将 LLMMessage 转换为 pi-ai 的消息结构
  */

package/dist/env/llm/index.js

@@ -13,7 +13,7 @@ import {
   createLLMAdapter,
   getLLMProviderOverride,
   setLLMProvider
-} from "../../shared/@ai-setting/roy-agent-core-vvb4cyyy.js";
+} from "../../shared/@ai-setting/roy-agent-core-2cw72f16.js";
 import"../../shared/@ai-setting/roy-agent-core-adg9ghbt.js";
 import {
   PiAiAdapter,
@@ -27,8 +27,9 @@ import {
   isOpencodeEndpoint,
   isOpencodeProvider,
   parseModelString
-} from "../../shared/@ai-setting/roy-agent-core-9qgrc9dy.js";
+} from "../../shared/@ai-setting/roy-agent-core-03k5drfp.js";
 import"../../shared/@ai-setting/roy-agent-core-zjdzk1gg.js";
+import"../../shared/@ai-setting/roy-agent-core-ntn32q7j.js";
 import"../../shared/@ai-setting/roy-agent-core-ctdhjv68.js";
 import"../../shared/@ai-setting/roy-agent-core-7hh0brvs.js";
 import"../../shared/@ai-setting/roy-agent-core-gtdtzbs7.js";

package/dist/env/llm/model-fallback.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Model fallback eligibility detection (Task #4623).
+ *
+ * Background
+ * ----------
+ * The user reported that `roy-agent act ... --model <provider/model>` works for
+ * the default agent, but sub-agents spawned via `delegate_task` silently fall
+ * back to the configured default model. On top of that, when the primary model
+ * runs out of quota the whole run dies with `Error | 404 Page not found` and
+ * there is no way to keep going.
+ *
+ * This module owns two pure concerns:
+ *
+ *   1. `isFallbackEligibleError()` — decide whether a given failure should
+ *      trigger a model downgrade.
+ *   2. `parseFallbackModel()` — normalise a `providerId/modelId` string.
+ *
+ * ⚠️ WHY TEXT MATCHING (and not `instanceof`)
+ *
+ * The production error chain destroys the error *type* before it ever reaches
+ * us:
+ *
+ *   - `llm.ts:873`  → `throw new Error(result.result)` (AI SDK stringifies
+ *                     the error, `statusCode` is lost)
+ *   - `environment.ts:handle_query` → `throw new Error(result.error)`
+ *   - `error-reply.ts` → `classifyReactFailure()` matches on **text**
+ *     (its own comment says "不能依赖 instanceof RetryError")
+ *
+ * So the only signal that survives to the fallback layer is the message text
+ * (plus, when the provider happens to expose it, a `statusCode` property).
+ * Both are inspected here.
+ */
+/**
+ * Decide whether a failure should trigger a model fallback.
+ *
+ * @param error       The thrown value (may be an Error, a plain object, or a string).
+ * @param hasFallback Whether a fallback model is actually configured. When
+ *                    `false` this always returns `false` so callers can use it
+ *                    as a single guard.
+ */
+export declare function isFallbackEligibleError(error: unknown, hasFallback?: boolean): boolean;
+/**
+ * Normalise a fallback model string.
+ *
+ * Accepted formats:
+ *   - `"providerId/modelId"`  → `{ providerId, modelId }`
+ *   - `"modelId"`             → `{ providerId: undefined, modelId }`
+ *
+ * @returns `undefined` when the input is empty / whitespace-only.
+ */
+export declare function parseFallbackModel(fallbackModel: string | undefined): {
+    providerId?: string;
+    modelId: string;
+} | undefined;

package/dist/env/llm/redact.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Secret redaction for upstream error text.
+ *
+ * ## Why this is a shared module and not a private helper
+ *
+ * Task #4465 established the rule: never trust an upstream error message to be
+ * secret-free — AI SDK / fetch errors routinely embed the request URL, the
+ * `Authorization` header, or a provider payload, any of which can contain the
+ * API key. `invoke.ts` therefore redacts before putting the message in
+ * `result.result`.
+ *
+ * Task #4625 added a second channel for the *same* error object: the raw
+ * `Error` is attached as `cause` so that `Retry-After` (the "when does the
+ * quota reset" header) survives the stringification boundaries, because a bare
+ * message string cannot carry headers.
+ *
+ * That created a hole. `error-reply.ts` walks `cause` while building the
+ * `technical` line, and that line is rendered into the user-facing failure
+ * reply (Feishu + CLI). So the raw, un-redacted upstream text — the very thing
+ * `invoke.ts` had just stripped out — came back in through the side door.
+ *
+ * Redaction therefore has to happen at **both** ends, which means it cannot stay
+ * private to `invoke.ts`. Kept dependency-free on purpose so both the LLM layer
+ * and the error-reporting layer can import it without a cycle.
+ */
+/**
+ * Redact credentials from free-form text before logging or showing it.
+ *
+ * Two passes:
+ * 1. exact known secrets (caller-supplied, e.g. the configured `apiKey`) — this
+ *    is defense in depth for formats the patterns below do not know about;
+ * 2. well-known key shapes (`sk-…`, `oc_sk_…`, `Bearer …`).
+ *
+ * @param text          free-form text that may embed a credential
+ * @param knownSecrets  exact values to scrub; entries shorter than 8 chars are
+ *                      ignored so a trivial value cannot wreck the message
+ */
+export declare function redactSecrets(text: string, knownSecrets?: Array<string | undefined>): string;
+export declare function redactErrorForTransport(error: unknown, knownSecrets?: Array<string | undefined>, depth?: number): unknown;

package/dist/env/llm/types.d.ts

@@ -65,6 +65,19 @@ export interface ToolResult {
     result: string;
     /** 是否为错误 */
     isError?: boolean;
+    /**
+     * Task #4625：保留原始错误对象（**已脱敏的结构副本**）。
+     *
+     * `result` 是字符串，装不下 `APICallError.responseHeaders` 之类结构化信息，
+     * 而 `Retry-After`（额度多久恢复）只存在那里。上层构造 `Error` 时把它挂到
+     * `cause` 上，`extractRetryAfterSeconds()` 才能一路挖到。
+     *
+     * ⚠️ **不要用 `instanceof Error` 判断它。** 为了脱敏，`invoke.ts` 交给这里的
+     * 是 `redactErrorForTransport()` 产出的**普通对象副本**（不是 Error 实例），
+     * 这样才能按值擦掉 apiKey。下游一律按结构化字段访问
+     * （`name` / `message` / `statusCode` / `responseHeaders` / `cause`）。
+     */
+    originalError?: Error | Record<string, unknown>;
 }
 /**
  * Usage Information

package/dist/env/session/index.js

@@ -3,17 +3,18 @@ import {
   MIN_SESSION_ID_LENGTH,
   SessionComponent,
   isValidSessionId
-} from "../../shared/@ai-setting/roy-agent-core-48h4zh60.js";
+} from "../../shared/@ai-setting/roy-agent-core-bm3gav5d.js";
 import {
   MemorySessionStore
-} from "../../shared/@ai-setting/roy-agent-core-2veqhrxa.js";
+} from "../../shared/@ai-setting/roy-agent-core-1dnsk6ht.js";
 import"../../shared/@ai-setting/roy-agent-core-ze068vc9.js";
 import"../../shared/@ai-setting/roy-agent-core-rvxg1wps.js";
 import {
   SessionMessageConverter
-} from "../../shared/@ai-setting/roy-agent-core-x1d6edkh.js";
-import"../../shared/@ai-setting/roy-agent-core-9qgrc9dy.js";
+} from "../../shared/@ai-setting/roy-agent-core-rfhxj8v2.js";
+import"../../shared/@ai-setting/roy-agent-core-03k5drfp.js";
 import"../../shared/@ai-setting/roy-agent-core-zjdzk1gg.js";
+import"../../shared/@ai-setting/roy-agent-core-ntn32q7j.js";
 import"../../shared/@ai-setting/roy-agent-core-7hh0brvs.js";
 import"../../shared/@ai-setting/roy-agent-core-gtdtzbs7.js";
 import"../../shared/@ai-setting/roy-agent-core-7tce05jt.js";

package/dist/env/session/storage/index.js

@@ -3,10 +3,11 @@ import {
   SQLiteSessionStore,
   getDefaultDataDir,
   getDefaultSessionDbPath
-} from "../../../shared/@ai-setting/roy-agent-core-2veqhrxa.js";
-import"../../../shared/@ai-setting/roy-agent-core-x1d6edkh.js";
-import"../../../shared/@ai-setting/roy-agent-core-9qgrc9dy.js";
+} from "../../../shared/@ai-setting/roy-agent-core-1dnsk6ht.js";
+import"../../../shared/@ai-setting/roy-agent-core-rfhxj8v2.js";
+import"../../../shared/@ai-setting/roy-agent-core-03k5drfp.js";
 import"../../../shared/@ai-setting/roy-agent-core-zjdzk1gg.js";
+import"../../../shared/@ai-setting/roy-agent-core-ntn32q7j.js";
 import"../../../shared/@ai-setting/roy-agent-core-386wa4wy.js";
 import"../../../shared/@ai-setting/roy-agent-core-6awgfh3x.js";
 import"../../../shared/@ai-setting/roy-agent-core-jnszp0jq.js";

package/dist/env/task/delegate/delegate-tool.d.ts

@@ -209,6 +209,20 @@ export interface BackgroundTask {
     /** Timestamp of the latest lifecycle state change or progress notification. */
     lastUpdatedAt?: number;
     startedAt?: number;
+    /**
+     * Task #4623 — 父 agent 本次 run 使用的模型（`providerId/modelId`）。
+     *
+     * `roy-agent act "..." --model X` 时，父 agent 的 AgentContext.model 会经
+     * ToolContext 透传到 delegate_task，最终写在这里，并在
+     * `executeWithAbort` 里作为 sub-agent 的 `AgentContext.model` 传入。
+     *
+     * 注意：**不写进 sub-agent 的注册配置**（`ensureSubAgentRegistered`）。
+     * 注册只在首次发生（已存在则跳过），写注册期 model 会导致「第一次对、
+     * 第二次旧」的状态漂移；per-run 透传天然每次都是最新值。
+     */
+    model?: string;
+    /** Task #4623 — 父 agent 的兜底模型，同样透传给 sub-agent。 */
+    fallbackModel?: string;
     /**
      * ★ Task #4552 (A1)：本任务被允许的运行时长（毫秒，createTask 时确定）。
      *
@@ -289,6 +303,13 @@ export interface CreateBackgroundTaskOptions {
      *  2. 透传到后续所有 task.background.* event metadata（让 CLI event-handler 反查 EventStore）
      */
     triggerEventId?: string;
+    /**
+     * Task #4623 — 父 agent 本次 run 的模型（`providerId/modelId`）。
+     * 透传给 sub-agent，使 `--model` 对 delegate 出来的子 agent 同样生效。
+     */
+    model?: string;
+    /** Task #4623 — 父 agent 的兜底模型，透传给 sub-agent。 */
+    fallbackModel?: string;
 }
 /**
  * 构建 entry-agent 调度的 prompt 包装 (Task #2164 beta-compare divergence #2)
@@ -703,5 +724,10 @@ existingSubSessionId?: string,
  * 传入时透传给 createTask → publishBackgroundEvent，写进 task.background.*
  * 事件 metadata，供主 agent 反查原始 chatId。
  */
-triggerEventId?: string): Promise<ToolResult>;
+triggerEventId?: string, 
+/**
+ * Task #4623 — 父 agent 本次 run 的 model / fallbackModel。
+ * 透传给 createTask → sub-agent 的 AgentContext。
+ */
+model?: string, fallbackModel?: string): Promise<ToolResult>;
 export { handleBackgroundTask };