@remnic/core 9.69.38 → 9.69.40

package/src/fallback-llm.ts

@@ -1,5 +1,4 @@
 import { log } from "./logger.js";
-import path from "node:path";
 import type { AgentPersonaModelConfig, GatewayConfig, ModelProviderConfig, PluginConfig } from "./types.js";
 import { extractJsonCandidates } from "./json-extract.js";
 import {
@@ -10,25 +9,38 @@ import {
 import {
   resolveProviderApiKey,
   getGatewayRuntimeAuthForModel,
-  type GetRuntimeAuthForModelFn,
-  type ResolveApiKeyFn,
 } from "./resolve-provider-secret.js";
 import {
   CODEX_SUBSCRIPTION_PROVIDER_ID,
   codexSubscriptionBuiltinProviderConfig,
-  getCodexSubscriptionRunnerForOwner,
 } from "./providers/codex-subscription.js";
 import { loadModelsJsonProviders } from "./models-json.js";
 import {
   abortReason,
+  classifyThrownProviderError,
+  defaultOpenClawWorkspaceDir,
+  extractResponsesOutputText,
+  fallbackLlmRuntimeContextFromConfig,
   isTerminalCodexSubscriptionError,
+  isTimeoutError,
+  isUnsupportedJsonSchemaError,
+  normalizeRuntimePath,
   raceFallbackLlmDeadline,
+  readGatewayWorkspaceDir,
   tryCodexSubscriptionProvider,
   withCodexRuntimeShutdown,
+  type FallbackLlmRuntimeContext,
+  type StructuredParseFailure,
+  type StructuredParseResult,
+} from "./fallback-llm-codex-subscription.js";
+
+export {
+  fallbackLlmRuntimeContextFromConfig,
+  type FallbackLlmRuntimeContext,
+  type StructuredParseFailure,
+  type StructuredParseFailureReason,
+  type StructuredParseResult,
 } from "./fallback-llm-codex-subscription.js";
-import type { CodexCliFallbackRunner } from "./cli-fallback.js";
-import { resolveHomeDir } from "./runtime/env.js";
-import { expandTildePath } from "./utils/path.js";
 
 export interface FallbackLlmOptions {
   temperature?: number;
@@ -53,6 +65,13 @@ export interface FallbackLlmOptions {
   agentId?: string;
   /** Reject a transport-successful response and continue through the configured model chain. */
   acceptResponse?: (response: FallbackLlmResponse) => boolean;
+  /**
+   * Optional out-box for the terminal failure cause (issue #2891): when every
+   * model in the chain fails, the last thrown provider error is recorded here
+   * so callers can classify it (e.g. HTTP 429 → rate-limited) in memory
+   * instead of seeing only null. Never logged.
+   */
+  failureDiag?: { lastError?: unknown };
 }
 
 export interface FallbackLlmAvailabilityOptions {
@@ -87,36 +106,9 @@ export interface FallbackLlmResponse {
   };
 }
 
-export interface FallbackLlmRuntimeContext {
-  agentDir?: string;
-  getRuntimeAuthForModel?: GetRuntimeAuthForModelFn | null;
-  resolveApiKeyForProvider?: ResolveApiKeyFn | null;
-  workspaceDir?: string;
-  /** Per-runtime Codex child owner. Shutdown must terminate only this runner. */
-  codexSubscriptionRunner?: CodexCliFallbackRunner;
-}
-
-export function fallbackLlmRuntimeContextFromConfig(
-  config: Pick<
-    GatewayBackedRuntimeConfig,
-    "providerApiKeyResolver" | "runtimeAuthForModelResolver" | "workspaceDir"
-  >,
-  overrides: FallbackLlmRuntimeContext = {},
-): FallbackLlmRuntimeContext {
-  return {
-    workspaceDir: config.workspaceDir,
-    resolveApiKeyForProvider: config.providerApiKeyResolver,
-    getRuntimeAuthForModel: config.runtimeAuthForModelResolver,
-    codexSubscriptionRunner: getCodexSubscriptionRunnerForOwner(config),
-    ...overrides,
-  };
-}
-
-type GatewayBackedRuntimeConfig = {
-  providerApiKeyResolver?: ResolveApiKeyFn | null;
-  runtimeAuthForModelResolver?: GetRuntimeAuthForModelFn | null;
-  workspaceDir?: string;
-};
+type ChatCompletionOutcome =
+  | { ok: true; response: FallbackLlmResponse }
+  | { ok: false; failure: Omit<StructuredParseFailure, "result"> };
 
 interface ModelRef {
   providerId: string;
@@ -125,22 +117,6 @@ interface ModelRef {
   modelString: string;
 }
 
-function isUnsupportedJsonSchemaError(error: unknown): boolean {
-  const message = error instanceof Error ? error.message : String(error);
-  // Require an HTTP status plus explicit schema/format context. A bare
-  // "unsupported" (e.g. "'temperature' is unsupported with this model") must
-  // NOT trigger the schema-stripping retry, or we pay a duplicate request
-  // for unrelated provider errors.
-  if (!/\b(?:400|404|422)\b/.test(message)) {
-    return false;
-  }
-  if (/(?:response[_ ]?format|json[_ ]?schema|structured[_ ]?output)/i.test(message)) {
-    return true;
-  }
-  // "unsupported" only counts when adjacent to schema/format terminology.
-  return /\bunsupported\b[\s\S]{0,40}\b(?:schema|format)\b/i.test(message);
-}
-
 const PROVIDER_ALIASES: Record<string, readonly string[]> = {
   "openai-codex": ["codex"],
   codex: ["openai-codex"],
@@ -152,16 +128,7 @@ const LEGACY_PROVIDER_IDS = new Set(["openai-codex", "claude-cli"]);
 const MANAGED_SECRETREF_MARKER = ["secretref", "managed"].join("-");
 const PROVIDER_API_KEY_FIELD = ["api", "Key"].join("") as keyof ModelProviderConfig;
 
-/**
- * Built-in provider fallbacks for providers that are commonly configured via
- * OAuth or gateway-managed auth rather than an explicit apiKey in
- * openclaw.json. These entries let resolveProviderConfig() succeed so the
- * chain proceeds to tryModel() → resolveRuntimeAuth(), which is where the
- * gateway's native OAuth token exchange happens.
- *
- * Without these, OAuth-only providers like `openai` are rejected with
- * "provider not found" before runtime auth is ever attempted.
- */
+/** Built-in OAuth/managed-auth providers so resolveProviderConfig reaches runtime auth. */
 const BUILT_IN_PROVIDER_FALLBACKS: Record<string, ModelProviderConfig> = {
   anthropic: {
     baseUrl: "https://api.anthropic.com/v1",
@@ -182,9 +149,10 @@ const BUILT_IN_PROVIDER_FALLBACKS: Record<string, ModelProviderConfig> = {
 };
 
 /**
- * Generic fallback LLM client that uses the gateway's default AI configuration
- * and walks through the full fallback chain (primary + fallbacks).
- * Supports OpenAI and Anthropic API formats.
+ * Gateway/task LLM client. In `modelSource: "gateway"` this is the primary
+ * configured path (taskModelChain / agent persona), not a secondary recovery
+ * client. The class name stays `FallbackLlmClient` because it is imported
+ * widely; prefer the `TaskLlmClient` alias in new code. Issue #2967.
  */
 export class FallbackLlmClient {
   private gatewayConfig: GatewayConfig | undefined;
@@ -224,6 +192,18 @@ export class FallbackLlmClient {
     messages: Array<{ role: "system" | "user" | "assistant"; content: string }>,
     options: FallbackLlmOptions = {},
   ): Promise<FallbackLlmResponse | null> {
+    const outcome = await this.completeChat(messages, options);
+    return outcome.ok ? outcome.response : null;
+  }
+
+  /**
+   * Same transport walk as chatCompletion, but tagged so structured parse can
+   * tell timeout / empty / HTTP error apart instead of collapsing them to null.
+   */
+  private async completeChat(
+    messages: Array<{ role: "system" | "user" | "assistant"; content: string }>,
+    options: FallbackLlmOptions = {},
+  ): Promise<ChatCompletionOutcome> {
     const models = this.getModelChain(
       options.agentId,
       options.model,
@@ -231,28 +211,52 @@ export class FallbackLlmClient {
       options.includeDefaultModelFallback,
     );
     if (models.length === 0) {
-      log.warn("fallback LLM: no models configured in gateway");
-      return null;
+      log.warn("task LLM: no models configured in gateway");
+      return { ok: false, failure: { failureReason: "no_models", errorClass: "no_models" } };
     }
     options = withCodexRuntimeShutdown(options, this.runtimeContext.codexSubscriptionRunner);
 
+    let lastFailure: Omit<StructuredParseFailure, "result"> = {
+      failureReason: "http_error",
+      errorClass: "network",
+    };
+
+    const recordFailure = (
+      failure: Omit<StructuredParseFailure, "result">,
+      attemptedModel?: string,
+    ): void => {
+      lastFailure = attemptedModel ? { ...failure, attemptedModel } : failure;
+    };
+
+    const throwIfCallerAborted = (signal: AbortSignal | undefined): void => {
+      if (!signal?.aborted) return;
+      const reason = abortReason(signal);
+      if (isTimeoutError(reason) && !options.signal?.aborted) {
+        recordFailure({ failureReason: "timeout", errorClass: "timeout" });
+        return;
+      }
+      throw reason;
+    };
+
     const runChain = async (
       initialOptions: FallbackLlmOptions,
     ): Promise<FallbackLlmResponse | null> => {
       let runOptions = initialOptions;
       let lastRejectedResponse: FallbackLlmResponse | null = null;
+      let lastError: unknown;
       let terminalError: unknown;
       // Try each model in the chain
       for (let i = 0; i < models.length; i++) {
         if (runOptions.signal?.aborted) {
-          throw abortReason(runOptions.signal);
+          throwIfCallerAborted(runOptions.signal);
+          if (lastFailure.failureReason === "timeout") return null;
         }
         const model = models[i];
         const isFallback = i > 0;
 
         try {
           const result = await this.tryModel(model, messages, runOptions);
-          if (result) {
+          if (result?.content) {
             const response = {
               content: result.content,
               modelUsed: model.modelString,
@@ -260,26 +264,29 @@ export class FallbackLlmClient {
             };
             if (runOptions.acceptResponse && !runOptions.acceptResponse(response)) {
               lastRejectedResponse = response;
-              log.debug(`fallback LLM: ${model.modelString} returned rejected output, trying next...`);
+              log.debug(`task LLM: ${model.modelString} returned rejected output, trying next...`);
               continue;
             }
             if (isFallback) {
-              log.debug(`fallback LLM: succeeded using ${model.modelString} (fallback ${i})`);
+              log.debug(`task LLM: succeeded using ${model.modelString} (fallback ${i})`);
             }
             return response;
           }
+          recordFailure({ failureReason: "empty", errorClass: "empty" }, model.modelString);
         } catch (err) {
           if (isTerminalCodexSubscriptionError(err) && runOptions.signal?.aborted) {
             throw err;
           }
           if (runOptions.signal?.aborted) {
-            throw abortReason(runOptions.signal);
+            throwIfCallerAborted(runOptions.signal);
+            if (lastFailure.failureReason === "timeout") return null;
           }
+          lastError = err;
           if (
             (runOptions.jsonSchema || runOptions.responsesJsonSchema) &&
             isUnsupportedJsonSchemaError(err)
           ) {
-            log.debug(`fallback LLM: ${model.modelString} rejected native JSON schema; retrying without it`);
+            log.debug(`task LLM: ${model.modelString} rejected native JSON schema; retrying without it`);
             // Degrade to prompt-only for the REST of the chain too, so an
             // N-model chain where every provider rejects structured output
             // costs N+1 requests instead of 2N.
@@ -290,7 +297,7 @@ export class FallbackLlmClient {
             };
             try {
               const result = await this.tryModel(model, messages, runOptions);
-              if (result) {
+              if (result?.content) {
                 const response = {
                   content: result.content,
                   modelUsed: model.modelString,
@@ -300,21 +307,28 @@ export class FallbackLlmClient {
                   return response;
                 }
                 lastRejectedResponse = response;
-                log.debug(`fallback LLM: ${model.modelString} unstructured retry output rejected by acceptResponse, trying next model...`);
+                log.debug(`task LLM: ${model.modelString} unstructured retry output rejected by acceptResponse, trying next model...`);
                 continue;
               }
+              recordFailure({ failureReason: "empty", errorClass: "empty" }, model.modelString);
             } catch (retryError) {
               if (isTerminalCodexSubscriptionError(retryError) && runOptions.signal?.aborted) {
                 throw retryError;
               }
-              if (runOptions.signal?.aborted) throw abortReason(runOptions.signal);
+              if (runOptions.signal?.aborted) {
+                throwIfCallerAborted(runOptions.signal);
+                if (lastFailure.failureReason === "timeout") return null;
+              }
+              lastError = retryError;
+              const retryClassified = classifyThrownProviderError(retryError);
+              recordFailure(retryClassified, model.modelString);
               const retryErrorMsg = runOptions.redactProviderErrors
                 ? "provider error details redacted"
                 : retryError instanceof Error
                   ? retryError.message
                   : String(retryError);
               log.debug(
-                `fallback LLM: ${model.modelString} unstructured retry failed (${retryErrorMsg})`,
+                `task LLM: ${model.modelString} unstructured retry failed (${retryErrorMsg})`,
               );
               if (isTerminalCodexSubscriptionError(retryError)) {
                 terminalError = retryError;
@@ -322,12 +336,14 @@ export class FallbackLlmClient {
             }
             continue;
           }
+          const classified = classifyThrownProviderError(err);
+          recordFailure(classified, model.modelString);
           const errorMsg = runOptions.redactProviderErrors
             ? "provider error details redacted"
             : err instanceof Error
               ? err.message
               : String(err);
-          log.debug(`fallback LLM: ${model.modelString} failed (${errorMsg}), trying next...`);
+          log.debug(`task LLM: ${model.modelString} failed (${errorMsg}), trying next...`);
           if (isTerminalCodexSubscriptionError(err)) {
             terminalError = err;
           }
@@ -335,7 +351,10 @@ export class FallbackLlmClient {
         }
       }
 
-      log.warn(`fallback LLM: all ${models.length} models in chain failed`);
+      log.warn(`task LLM: all ${models.length} models in chain failed`);
+      if (options.failureDiag && lastError !== undefined && !lastRejectedResponse) {
+        options.failureDiag.lastError = lastError;
+      }
       // A terminal typed provider failure must reach the caller when the
       // chain is exhausted — the documented timeout/re-login guidance
       // depends on it (issue #2833).
@@ -345,10 +364,15 @@ export class FallbackLlmClient {
       return lastRejectedResponse;
     };
 
+    const toOutcome = (response: FallbackLlmResponse | null): ChatCompletionOutcome => {
+      if (response) return { ok: true, response };
+      return { ok: false, failure: lastFailure };
+    };
+
     if (typeof options.timeoutMs === "number") {
       if (options.timeoutMs <= 0) {
-        log.warn("fallback LLM: timed out before request started");
-        return null;
+        log.warn("task LLM: timed out before request started");
+        return { ok: false, failure: { failureReason: "timeout", errorClass: "timeout" } };
       }
       const controller = new AbortController();
       const onCallerAbort = (): void => {
@@ -368,19 +392,26 @@ export class FallbackLlmClient {
         },
       );
       try {
+        const timeoutError = Object.assign(
+          new Error(`task LLM timed out after ${options.timeoutMs}ms`),
+          { name: "TimeoutError" },
+        );
         const outcome = await raceFallbackLlmDeadline(guarded, options.timeoutMs, () => {
-          log.warn(`fallback LLM: timed out after ${options.timeoutMs}ms`);
-          controller.abort(
-            new Error(`fallback LLM timed out after ${options.timeoutMs}ms`),
-          );
+          log.warn(`task LLM: timed out after ${options.timeoutMs}ms`);
+          recordFailure({ failureReason: "timeout", errorClass: "timeout" });
+          controller.abort(timeoutError);
+          if (options.failureDiag) options.failureDiag.lastError = timeoutError;
         });
-        return outcome.timedOut ? null : outcome.value;
+        if (outcome.timedOut) {
+          return { ok: false, failure: { failureReason: "timeout", errorClass: "timeout" } };
+        }
+        return toOutcome(outcome.value);
       } finally {
         options.signal?.removeEventListener("abort", onCallerAbort);
       }
     }
 
-    return await runChain(options);
+    return toOutcome(await runChain(options));
   }
 
   /**
@@ -404,13 +435,10 @@ export class FallbackLlmClient {
     messages: Array<{ role: "system" | "user" | "assistant"; content: string }>,
     schema: { parse: (data: unknown) => T },
     options: FallbackLlmOptions = {},
-  ): Promise<
-    | { result: T; modelUsed: string }
-    | { result: null; failureReason: "no_models" | "empty" | "http_error" }
-  > {
-    let response: FallbackLlmResponse | null;
+  ): Promise<StructuredParseResult<T>> {
+    let outcome: ChatCompletionOutcome;
     try {
-      response = await this.chatCompletion(messages, options);
+      outcome = await this.completeChat(messages, options);
     } catch (err) {
       // Caller aborts must propagate (e.g. recall planner cancellation) — do
       // not swallow them as a provider failure, or abort-driven callers lose
@@ -418,38 +446,65 @@ export class FallbackLlmClient {
       // Terminal codex-subscription failures propagate for the same reason:
       // their TimeoutError/auth guidance is the documented contract.
       if (options.signal?.aborted || isTerminalCodexSubscriptionError(err)) throw err;
-      log.warn("fallback LLM: chatCompletion threw during structured parse:", err);
-      return { result: null, failureReason: "http_error" };
+      if (isTimeoutError(err)) {
+        return { result: null, failureReason: "timeout", errorClass: "timeout" };
+      }
+      log.warn("task LLM: chatCompletion threw during structured parse:", err);
+      return { result: null, ...classifyThrownProviderError(err) };
     }
-    if (!response?.content) {
-      // chatCompletion returns null both when no models are configured
-      // (auth/config) and when every configured model errored (transient).
-      // Disambiguate via the resolved model chain so the retry layer can pick
-      // the right failure class.
-      const hasModels =
-        this.getModelChain(
-          options.agentId,
-          options.model,
-          options.modelChain,
-          options.includeDefaultModelFallback,
-        ).length > 0;
-      return { result: null, failureReason: hasModels ? "http_error" : "no_models" };
+    if (!outcome.ok) {
+      return { result: null, ...outcome.failure };
+    }
+    const response = outcome.response;
+    if (!response.content) {
+      return {
+        result: null,
+        failureReason: "empty",
+        attemptedModel: response.modelUsed,
+        errorClass: "empty",
+      };
     }
 
     try {
       const candidates = extractJsonCandidates(response.content);
+      let sawJson = false;
+      let sawSchemaReject = false;
       for (const c of candidates) {
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(c);
+          sawJson = true;
+        } catch {
+          continue;
+        }
         try {
-          const parsed = JSON.parse(c);
           return { result: schema.parse(parsed), modelUsed: response.modelUsed };
         } catch {
-          // keep trying other candidates
+          sawSchemaReject = true;
         }
       }
-      return { result: null, failureReason: "empty" };
+      if (sawSchemaReject) {
+        return {
+          result: null,
+          failureReason: "schema_rejection",
+          attemptedModel: response.modelUsed,
+          errorClass: "schema_rejection",
+        };
+      }
+      return {
+        result: null,
+        failureReason: "empty",
+        attemptedModel: response.modelUsed,
+        errorClass: "empty",
+      };
     } catch (err) {
-      log.warn("fallback LLM: failed to parse structured output:", err);
-      return { result: null, failureReason: "empty" };
+      log.warn("task LLM: failed to parse structured output:", err);
+      return {
+        result: null,
+        failureReason: "empty",
+        attemptedModel: response.modelUsed,
+        errorClass: "empty",
+      };
     }
   }
 
@@ -476,9 +531,9 @@ export class FallbackLlmClient {
 
     if (modelChainOverride?.primary) {
       modelConfig = modelChainOverride;
-      log.debug("fallback LLM: using explicit model chain override");
+      log.debug("task LLM: using explicit model chain override");
     } else if (modelChainOverride) {
-      log.warn("fallback LLM: ignoring explicit model chain override without primary model");
+      log.warn("task LLM: ignoring explicit model chain override without primary model");
     }
 
     if (!modelConfig && agentId) {
@@ -487,10 +542,10 @@ export class FallbackLlmClient {
       );
       if (persona?.model) {
         modelConfig = persona.model;
-        log.debug(`fallback LLM: using agent persona "${agentId}" model chain`);
+        log.debug(`task LLM: using agent persona "${agentId}" model chain`);
       } else {
         log.warn(
-          `fallback LLM: agent persona "${agentId}" not found or has no model config, falling back to defaults`,
+          `task LLM: agent persona "${agentId}" not found or has no model config, falling back to defaults`,
         );
       }
     }
@@ -552,7 +607,7 @@ export class FallbackLlmClient {
           chain.push(defaultRef);
           modelStrings.push(trimmed); // keep dedupe correct for later default fallbacks
           log.debug(
-            `fallback LLM: appended gateway default model "${trimmed}" as implicit last resort`,
+            `task LLM: appended gateway default model "${trimmed}" as implicit last resort`,
           );
         }
       }
@@ -571,7 +626,7 @@ export class FallbackLlmClient {
     // Parse "provider/model" format (e.g., "openai/gpt-5.5", "anthropic/claude-opus-4-6")
     const parts = modelString.split("/");
     if (parts.length < 2) {
-      log.warn(`fallback LLM: invalid model format: ${modelString}`);
+      log.warn(`task LLM: invalid model format: ${modelString}`);
       return null;
     }
 
@@ -586,7 +641,7 @@ export class FallbackLlmClient {
     const providerConfig = resolvedProvider?.config;
     if (!providerConfig) {
       log.warn(
-        `fallback LLM: provider not found: ${requestedProviderId} ` +
+        `task LLM: provider not found: ${requestedProviderId} ` +
         `(tried: ${this.providerResolutionCandidates(requestedProviderId).join(", ")})`,
       );
       return null;
@@ -613,7 +668,7 @@ export class FallbackLlmClient {
       const config = providers[candidate];
       if (config) {
         if (candidate !== providerId) {
-          log.debug(`fallback LLM: provider "${providerId}" resolved via alias "${candidate}"`);
+          log.debug(`task LLM: provider "${providerId}" resolved via alias "${candidate}"`);
         }
         return { providerId: candidate, config };
       }
@@ -622,17 +677,17 @@ export class FallbackLlmClient {
       const config = this.resolveFromModelsJson(candidate);
       if (config) {
         if (candidate !== providerId) {
-          log.debug(`fallback LLM: provider "${providerId}" resolved via models.json alias "${candidate}"`);
+          log.debug(`task LLM: provider "${providerId}" resolved via models.json alias "${candidate}"`);
         }
         return { providerId: candidate, config };
       }
       const builtInConfig = BUILT_IN_PROVIDER_FALLBACKS[candidate];
       if (builtInConfig) {
         if (candidate === providerId) {
-          log.debug(`fallback LLM: provider "${providerId}" resolved from built-in defaults`);
+          log.debug(`task LLM: provider "${providerId}" resolved from built-in defaults`);
           return { providerId, config: builtInConfig };
         }
-        log.debug(`fallback LLM: provider "${providerId}" resolved via built-in alias "${candidate}"`);
+        log.debug(`task LLM: provider "${providerId}" resolved via built-in alias "${candidate}"`);
         return { providerId: candidate, config: builtInConfig };
       }
     }
@@ -654,7 +709,7 @@ export class FallbackLlmClient {
     const allProviders = loadModelsJsonProviders();
     const config = allProviders[providerId];
     if (config) {
-      log.debug(`fallback LLM: resolved provider "${providerId}" from models.json (api: ${config.api ?? "default"})`);
+      log.debug(`task LLM: resolved provider "${providerId}" from models.json (api: ${config.api ?? "default"})`);
       return config;
     }
     return null;
@@ -761,13 +816,13 @@ export class FallbackLlmClient {
 
       if (result?.apiKey || result?.baseUrl) {
         log.debug(
-          `fallback LLM: resolved runtime auth for "${model.modelString}" (source: ${result.source ?? "unknown"}, mode: ${result.mode ?? "unknown"})`,
+          `task LLM: resolved runtime auth for "${model.modelString}" (source: ${result.source ?? "unknown"}, mode: ${result.mode ?? "unknown"})`,
         );
         return { apiKey: result.apiKey, baseUrl: result.baseUrl };
       }
     } catch (err) {
       log.debug(
-        `fallback LLM: gateway runtime auth failed for "${model.modelString}": ${err instanceof Error ? err.message : String(err)}`,
+        `task LLM: gateway runtime auth failed for "${model.modelString}": ${err instanceof Error ? err.message : String(err)}`,
       );
     }
     return null;
@@ -848,7 +903,7 @@ export class FallbackLlmClient {
 
     if (!response.ok) {
       const error = await response.text();
-      throw new Error(`OpenAI API error: ${response.status} ${error}`);
+      throw Object.assign(new Error(`OpenAI API error: ${response.status} ${error}`), { status: response.status });
     }
 
     const data = (await response.json()) as {
@@ -920,7 +975,7 @@ export class FallbackLlmClient {
 
     if (!response.ok) {
       const error = await response.text();
-      throw new Error(`Ollama API error: ${response.status} ${error}`);
+      throw Object.assign(new Error(`Ollama API error: ${response.status} ${error}`), { status: response.status });
     }
 
     const data = (await response.json()) as {
@@ -1018,7 +1073,7 @@ export class FallbackLlmClient {
 
     if (!response.ok) {
       const error = await response.text();
-      throw new Error(`OpenAI Responses API error: ${response.status} ${error}`);
+      throw Object.assign(new Error(`OpenAI Responses API error: ${response.status} ${error}`), { status: response.status });
     }
 
     const data = (await response.json()) as {
@@ -1110,7 +1165,7 @@ export class FallbackLlmClient {
 
     if (!response.ok) {
       const error = await response.text();
-      throw new Error(`Anthropic API error: ${response.status} ${error}`);
+      throw Object.assign(new Error(`Anthropic API error: ${response.status} ${error}`), { status: response.status });
     }
 
     const data = (await response.json()) as {
@@ -1142,57 +1197,3 @@ export class FallbackLlmClient {
   }
 }
 
-function normalizeRuntimePath(value: unknown): string | undefined {
-  if (typeof value !== "string") return undefined;
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? expandTildePath(trimmed) : undefined;
-}
-
-function readGatewayWorkspaceDir(gatewayConfig: GatewayConfig | undefined): string | undefined {
-  if (!gatewayConfig || typeof gatewayConfig !== "object") return undefined;
-  const raw = gatewayConfig as Record<string, unknown>;
-  return (
-    normalizeRuntimePath(raw.workspaceDir) ??
-    normalizeRuntimePath(raw.workspacePath) ??
-    normalizeRuntimePath(raw.workspace)
-  );
-}
-
-function defaultOpenClawWorkspaceDir(): string {
-  return path.join(resolveHomeDir(), ".openclaw", "workspace");
-}
-
-function extractResponsesOutputText(data: {
-  output_text?: string;
-  output?: Array<{
-    type?: string;
-    text?: string;
-    content?: Array<{
-      type?: string;
-      text?: string;
-    }>;
-  }>;
-}): string | null {
-  if (typeof data.output_text === "string" && data.output_text.trim().length > 0) {
-    return data.output_text;
-  }
-
-  const chunks: string[] = [];
-  for (const item of data.output ?? []) {
-    if (typeof item.text === "string" && item.text.trim().length > 0) {
-      chunks.push(item.text);
-    }
-    for (const part of item.content ?? []) {
-      if (
-        (part.type === "output_text" || part.type === "text") &&
-        typeof part.text === "string" &&
-        part.text.trim().length > 0
-      ) {
-        chunks.push(part.text);
-      }
-    }
-  }
-
-  const joined = chunks.join("\n").trim();
-  return joined.length > 0 ? joined : null;
-}