fix(types): definite failover reason + OTel docs correction

CG-Intelligence-Agent-Jack · CG-Intelligence-Agent-Jack · commit 6f3fc2309f8a · 2026-07-03T06:06:04.000-04:00
- model-fallback.ts:1814: fallback reason now defaults to 'unknown' when
  failure.reason is undefined, satisfying the string type requirement
- opentelemetry.md:219: remove from_hash/to_hash from counter attrs;
  clarify profile hashes are exported on corresponding span attributes
diff --git a/docs/gateway/opentelemetry.md b/docs/gateway/opentelemetry.md
@@ -216,7 +216,7 @@ on the public diagnostic event bus.
 - `openclaw.model_call.response_bytes` (histogram, UTF-8 byte size of streamed response chunk payloads; high-frequency text, thinking, and tool-call deltas count only incremental `delta` bytes; no raw response content)
 - `openclaw.model_call.time_to_first_byte_ms` (histogram, elapsed time before the first streamed response event)
 - `openclaw.model.failover` (counter, attrs: `openclaw.provider`, `openclaw.model`, `openclaw.failover.to_provider`, `openclaw.failover.to_model`, `openclaw.failover.reason`, `openclaw.failover.suspended`, `openclaw.lane`)
-- `openclaw.auth_profile.fallback` (counter, attrs: `openclaw.provider`, `openclaw.model`, `openclaw.auth_profile.from_hash`, `openclaw.auth_profile.to_hash`, `openclaw.auth_profile.reason`)
+- `openclaw.auth_profile.fallback` (counter, attrs: `openclaw.provider`, `openclaw.model`, `openclaw.auth_profile.reason`; profile hashes are exported on the corresponding span attributes)
 - `openclaw.skill.used` (counter, attrs: `openclaw.skill.name`, `openclaw.skill.source`, `openclaw.skill.activation`, optional `openclaw.agent`, optional `openclaw.toolName`)
 
 ### Message flow
diff --git a/src/agents/model-fallback.ts b/src/agents/model-fallback.ts
@@ -1811,7 +1811,7 @@ async function runWithModelFallbackInternal<T>(
           fromModel: candidate.model,
           toProvider: nextCandidate.provider,
           toModel: nextCandidate.model,
-          reason: failure.reason,
+          reason: failure.reason ?? "unknown",
           suspended: normalized instanceof FailoverError ? Boolean(normalized.suspend) : false,
         });
       }

Original file line number	Diff line number	Diff line change
`@@ -1811,7 +1811,7 @@ async function runWithModelFallbackInternal<T>(`
`1811`	`1811`	`fromModel: candidate.model,`
`1812`	`1812`	`toProvider: nextCandidate.provider,`
`1813`	`1813`	`toModel: nextCandidate.model,`
`1814`		`- reason: failure.reason,`
	`1814`	`+ reason: failure.reason ?? "unknown",`
`1815`	`1815`	`suspended: normalized instanceof FailoverError ? Boolean(normalized.suspend) : false,`
`1816`	`1816`	`});`
`1817`	`1817`	`}`