jackwener/maka-agent

fix(runtime): distinguish usage limits from authentication failures

Geschlossen

#2.516 geöffnet am 08.08.2026

 (0 Kommentare) (0 Reaktionen) (0 zugewiesene Personen)TypeScript (0 Forks)github user discovery
bughelp wanted

Repository-Metriken

Stars
 (1 Stern)
PR-Merge-Metriken
 (Keine gemergten PRs in 30 T)

Beschreibung

What happened

While using the TUI with a valid Kimi Code login after the plan limit was exhausted, Maka reported:

Authentication failed

That points the user toward signing in again or replacing credentials, even though the useful action is to wait for the limit to reset or check the subscription.

The shared classifier currently maps every HTTP 401/403 to auth and every 429 to a retryable rate_limit. Those status codes are not enough on their own: depending on the provider, they can mean an invalid credential, missing permission, exhausted credits, a subscription window, or transient throttling.

How to reproduce

  1. Sign in to Kimi Code with a valid account.
  2. Exhaust the five-hour or weekly plan allowance.
  3. Start another turn in the TUI.
  4. Maka shows an authentication failure instead of a usage-limit failure.

Environment

  • Maka: current main still has the status-first classification described above
  • Surface observed: TUI
  • Provider observed: Kimi Code plan

Suggested direction

I think this belongs at the ModelAdapter/runtime error-projection boundary, not in a Kimi-only TUI branch.

  • Extract structured provider evidence first (status, provider error code/type, retry metadata), then map it to a stable Maka failure meaning.
  • Keep authentication, permission, billing/credits, subscription usage limits, and transient rate limiting distinct where the provider gives enough evidence.
  • Derive retry policy from that meaning: a short throttle may retry, but a five-hour or weekly cap should not be retried blindly.
  • Let TUI, Desktop, non-interactive CLI, and Headless consume the same semantic result. Provider adapters should not own user-facing strings.
  • Preserve the current redaction boundary. Do not display raw response bodies, tokens, or guessed reset times.
  • For compatible relays with ambiguous errors, keep a safe generic fallback instead of pretending to know the account state.

A useful fixture matrix would cover at least:

  • Kimi: expired credentials vs exhausted plan
  • OpenAI: invalid key vs insufficient quota/project spend limit vs transient RPM/TPM throttling
  • OpenRouter: credits, permission/guardrail, and transient rate limit
  • an unknown OpenAI-compatible relay with incomplete error metadata

Expected behavior

  • The Kimi plan-limit case no longer tells the user to fix credentials.
  • Non-transient account limits are not automatically retried as short throttles.
  • Desktop localization, TUI text, and Headless/CLI machine-readable outcomes agree on the same failure meaning.
  • Provider-specific evidence parsing is covered by fixtures; surface tests only verify projection and presentation.
  • Unknown or malformed provider errors remain safe and do not leak raw payloads.

I’m happy to implement this once the failure taxonomy and fixture boundary look right.

我在真实使用 Maka TUI 时遇到:Kimi Code 登录仍然有效,但五小时或周限额已经耗尽,TUI 却显示“认证失败”。这个提示会引导用户重新登录或更换凭据,实际应该做的是等待额度恢复或检查套餐。

当前共享分类器把所有 401/403 都当作认证失败,把所有 429 都当作可重试的临时限流。但不同服务会用这些状态表示无效凭据、权限不足、余额耗尽、套餐周期限额或瞬时限流,仅靠 HTTP 状态无法得到正确结论。

建议在 ModelAdapter/Runtime 的共享错误投影边界修复,而不是在 Kimi TUI 中写专用判断:优先读取 provider 的结构化错误码和重试信息,再投影为 Maka 的稳定错误语义;TUI、Desktop、非交互 CLI 和 Headless 共用这份结果。短期限流可以重试,五小时或周限额不应盲目重试。无法可靠识别的兼容中转站错误应安全降级,不猜测额度或恢复时间,也不泄露原始响应。

我愿意在错误分类和 fixture 边界确认后实现。

Contributor Guide