KAME 1.2.0

The wait, said out loud: when every key is cooling, a wait longer than 90s now says so in the chat (counts and pool name only, never a key) and closes itself the instant a key answers.

Settings screen rewritten in Agent Zero's native markup, with defaults that no longer save themselves off.

Verified end-to-end on Agent Zero v2.10 — 12/12 fingerprints unchanged, 71/71 live checks green.

KAME v1.0.9 — Delegated Execution

KAME now only CHOOSES the key. Agent Zero makes the call itself.

Up to v1.0.8 the plugin re-implemented A0's model call inside itself — build the request, call litellm.acompletion, parse every stream chunk, accumulate, build the result. That copy went stale on every Agent Zero release. v1.0.9 deletes it: KAME injects api_key= into Agent Zero's own unified_call / unified_turn and returns A0's result untouched.

What that buys you

• 5 upstream symbols and litellm itself left KAME's dependency surface (watch list 14 -> 11). Agent Zero can rewrite its model layer freely.
• Entry points are found BY SIGNATURE SHAPE, so an upstream rename is survivable — including a rename that also moves the method into a base class (MRO-walking shape detection).
• A0's own internal retry loop is disabled per call, with the knob names read out of A0's source at runtime — so a rename there is handled automatically too.
• Activation now ships through THREE independent doors instead of one silent single point of failure.
• Worst case for a future A0 release: KAME prints one line and steps aside. Agent Zero keeps running, natively and unmodified.
• A0 v2.7+ @extensible hooks on unified_call / unified_turn now fire again, and v2.8's tool_choice / provider-native function calling are inherited free.

Subscription / OAuth models are untouched
Codex, GitHub Copilot, Gemini API and xAI Grok sign in through Agent Zero's own OAuth plugin instead of with API keys. KAME reads key pools from the .env and never calls models.get_api_key — which is exactly where that plugin hooks in — so those models find no pool, take KAME's passthrough branch, and reach Agent Zero unchanged. You can rotate a pool of Gemini keys and keep a Codex subscription model in the same Agent Zero. Proven every run, on every supported version, by comparing the same call with KAME uninstalled vs installed.

Speed, measured on a real A0 v2.8 stack
A rotation off a 429 costs 0.77s and 2 network calls. Without KAME's retry-knob suppression — letting A0 retry the dead key first, as its defaults would — the same rotation costs 3.77s and 4 calls.

Unchanged for you: same rotation behavior, same settings, no new dependencies, no notifications of any kind (no email, no webhook, no telemetry).

One bad JSON no longer ends the turn
Agent Zero stops a turn after N consecutive model replies it cannot parse into a tool request, "to prevent further API charges". A0's own default for N moved 2 -> 5 in v2.8, but an install upgraded from v2.4-v2.7 keeps the tight 2 in its settings file forever - so one escaping slip from the model ends the turn while healthy keys sit idle. KAME now applies a FLOOR, never a ceiling: effective = max(A0's setting, kame_unusable_response_limit), default 5. Past that count A0's stop is honored untouched, so a model genuinely stuck in a formatting loop still cannot drain your pool. Set 0 to never interfere. Settings -> Plugins -> KAME -> Unusable-response floor.

The upgrade checker also understands version-gated symbols now: auditing an Agent Zero older than v2.4 reports "not present (optional)" instead of failing.

Note: the attached KAME_v1.0.9.zip is the authoritative build and is kept current; the tag points at the initial v1.0.9 commit. The Plugin Hub installs from main, so it always gets the latest 1.0.9 state.

Verified end to end — real classes, real key rotation — on Agent Zero v1.14, v1.20, v2.1, v2.4, v2.7 and v2.8. One code path for all six. 230 offline checks and 374 live ones, all green.

KAME v1.0.8 — early-stop contract fix + Agent Zero v2.7 verified

Honors Agent Zero's early-stop contract, quarantines permanently-denied keys, and is
verified against Agent Zero v2.7.

Three real behavioral fixes, one documentation correction, a new live-compatibility
harness, and a proper upgrade protocol so the next Agent Zero release is a one-command
check. The rotation / selection / cooldown carousel and all 13 shields are otherwise
untouched. No new dependencies.

Re-shipped under the same version number: the zip and the v1.0.8 tag were replaced
in place after two more fixes were found in a production log, and again to add the
upgrade protocol (item 6). Re-download or hit Update if you installed an earlier
v1.0.8 build.

1. The streamed response callback's return value is now honored (the fix).
Since Agent Zero V2, Agent.monologue's stream callback returns the accumulated
text the moment a complete, valid tool request has been streamed, and A0's native
unified_call / unified_turn break the stream and use that text (stop_response).
KAME owns the stream, and up to v1.0.7 it awaited the callback and threw the
return value away — so on every single turn the model kept generating past the
finished tool call. Cost: wasted output tokens and latency on each turn, plus
trailing junk accumulating after the tool JSON in result.response. v1.0.8 breaks
the stream exactly like native A0 does. A blank early stop is not mistaken for an
empty stream, so the key is never wrongly penalized. On Agent Zero v1.x the
callback returns None and behavior is unchanged.

2. A permanently-denied key (403) is now quarantined instead of re-probed every
20 seconds. A 403 PERMISSION_DENIED — "Your project has been denied access", the
API never enabled for that project, or the model not authorized for that key's tier —
is the provider refusing the key on purpose. It does not clear in 20s. Up to v1.0.7 it
fell into the generic other bucket with a 20s cooldown, so the dead key kept returning
to the front of the carousel three times a minute and burned a full round trip on nearly
every user turn. Confirmed in a 15-key production pool: one denied key was selected first
on eight consecutive calls. v1.0.8 classifies it as a new denied kind and quarantines
the key for the daily cooldown (default 1h), so it is re-probed about once an hour — still
self-healing the moment the project is fixed. The health map is per provider:model, so a
model-specific 403 never takes the key out of the pool for other models. A 429 is still
classified before this branch, and a 403 is still not terminal, so KAME rotates and
never aborts the run.

3. The cosmetic startup banner can no longer fail the patch. On a non-UTF-8 console
(a native Windows run with a cp1252 code page) the emoji in the shield banner raised
UnicodeEncodeError, which escaped into apply_kame_patch's outer handler and printed
"Patch Failed" / returned False — even though every patch had already been applied.
Docker installs (UTF-8) were never affected.

4. The v1.0.7 response-tool claim is corrected. Agent Zero v2.6+ fixed the
crash upstream: tools/response.py now raises a RepairableException instead of
KeyError: 'message', so the framework asks the model to retry rather than dying.
KAME's empty-args injection is therefore a crash guard for older A0 only
(harmless on new A0 — blank text still routes to the repair path). What still earns
its keep on every version is the wrong-key salvage: a reply stranded under
content / answer / response / answer_text is moved into text, turning a
wasted repair round-trip into the answer the model actually wrote.

5. New tests/test_a0_compat.py — a live harness against a real A0 checkout.
The other suites stub Agent Zero so they run anywhere; this one imports the genuine
models, helpers.history, helpers.extension, agent and tools.response,
then applies and reverts KAME's patches against those real classes. Run it when a
new Agent Zero ships:

python tests/test_a0_compat.py /path/to/agent-zero

It skips cleanly (exit 0) when no path is given.

6. Upgrade protocol — KAME now tells you when Agent Zero breaks it, and where.

python tools/a0_upgrade_check.py --latest              # is there even a new A0?
python tools/a0_upgrade_check.py /path/to/agent-zero   # the real audit

Three stages: A0's newest tag from the GitHub API, then source fingerprints of all 14
A0 symbols KAME patches or depends on (whitespace- and comment-insensitive hashes,
parsed with ast so A0 does not need to be importable) diffed against a pinned baseline,
then the live harness. Exit 0 = compatible. Exit 1 = it names the exact function that
changed and why KAME cares about it. --update-baseline vX.Y re-pins after an audit.

Ships with it: a0_compat.json (the baseline + per-symbol rationale) and
COMPATIBILITY.md — the compatibility matrix, the full patch-point map (including
the two @extensible folder paths that fail silently if A0 renames Agent.monologue
or Agent.validate_tool_request), a "where to look in the A0 tree" cheat-sheet, and the
step-by-step upgrade runbook.

The plugin description now starts with [UPDATED TO A0 V2.7], so Agent Zero's plugin
list shows which A0 the installed KAME was verified against without opening anything.

Agent Zero v2.7 compatibility: verified, all green. Every patch point audited
against the v2.7 tag — unified_call / unified_turn, ChatCompletionsTransport.parse,
Topic.summarize_messages, Bulk.summarize, RateLimiter, the two @extensible
extension folders KAME ships into, LLMResult.from_chat, plugin manifest schema and
the fw.topic_summary prompts. Two notes for the record:

• v2.7 added @extensible to unified_call and unified_turn. KAME's monkey-patch
  replaces those decorated wrappers, so the new _functions/models/LiteLLMChatWrapper/ unified_{call,turn}/{start,end} extension points do not fire while KAME is active.
  Nothing in A0 v2.7 ships an extension there, so there is no live breakage — but a
  future third-party extension at those points would be silently skipped. Migrating
  KAME off the monkey-patch onto those extension points is tracked for a later release.
• KAME forces chat-completions and strips a0_* kwargs (including
  a0_responses_function_tools), so provider-native function calling is not used on
  KAME's path. A0 drops the tools kwarg on the chat path anyway, so nothing breaks;
  A0's JSON-in-text tool protocol is what runs, exactly as before.

Not a KAME issue, for the record (both traced from a production Docker log while
diagnosing this release, both upstream Agent Zero behavior by design):

• "Sending a new message does not stop the current run." Since A0 V2 the WebUI queues
  a message when the context is running (webui/index.js -> message_queue) and sends the
  batch only after the monologue ends (process_chain_end/_50_process_queue.py). The
  nudge button is the explicit interrupt. KAME already honors InterventionException
  between rotations and during every cooling slice — it cannot interrupt what the UI never sent.
• "Agent stopped after 2 consecutive unusable model responses to prevent further API
  charges." That is A0's own cost circuit-breaker (_90_stop_unusable_response_loop.py),
  tripped when the model returns a misformatted or repeated reply twice in a row. The API call
  succeeded — there is no error for KAME to rotate on. Raise
  max_consecutive_unusable_responses in settings, or use a model that keeps to A0's JSON contract.

Tests: tests/test_v1_0_8.py (22) + tests/test_a0_compat.py (24, against A0 v2.7)

• all prior suites green.

Install / update

Existing users: hit Update on the plugin card in the Agent Zero Plugin Hub. New users: download KAME_v1.0.8.zip below, or install from the repo URL.

v1.0.7 — Response Shield

Heals empty/null/wrong-key response-tool args in the KAME Shield extension, preventing upstream Agent Zero's KeyError: 'message' crash (tools/response.py, still unfixed upstream). Salvages replies stranded under content/answer/response/answer_text keys. Rotation engine unchanged. Tests: test_v1_0_7.py (19) + all prior suites green.

v1.0.1

KAME v1.0.1 — reliability fixes, log levels, config declutter

Additive release. The proven selection/rotation engine is unchanged — with at least one healthy key, behavior is identical to v1.0.0. These changes only affect cooldown duration on failures, the all-keys-sick sleep cadence, error reporting, and the log.

Reliability fixes

• Mid-run nudge works without the button — A0 control-flow exceptions (Intervention / Repairable / Handled) now pass through the carousel, so a chat message sent while the agent is working is received immediately.
• No more stream restart from zero — a stream that fails after emitting content re-raises instead of regenerating the whole response.
• Gentle server-outage escalation — sustained 503/500s back off 5 → 10 → 20 → 40 → 80s (capped 90s) on a separate counter, reset on success, instead of spinning forever.

Daily-quota & account-limit awareness (multi-provider)

• KAME no longer trusts a misleading short retryDelay on an exhausted key (e.g. Google's 1s on a daily 429). It rests the key for the configured cooldown (default 1h) and sleeps through the outage instead of burning wasted requests against a dead key.

Logging

• Configurable level: silent / normal / verbose. Success is never silent, yet the plugin can stay fully out of the Docker log when you need it.

Config

• Decluttered to three settings: kame_log_level, daily_quota_cooldown_seconds, key_log_style.

Verified through Agent Zero v1.18.

v1.0.0 — First Stable Release 🐢⚡

🐢⚡ KAME v1.0.0 — First Stable Release

The Key-Aware Management Engine for Agent Zero. Production-validated across 1,163 KAME operations and 117 rate-limit events in a single day of intensive A0 usage. Zero engine crashes, 99% pool-healthy uptime, sleep precision within the random jitter window (±300ms on a 7.7s sleep).

Highlights

• Identity-Aware Health: per-provider:model pool isolation.
• RPM-Aware Predictive Selection: 60-second sliding window per key.
• Anti-Dogpile + Anti-Thundering-Herd: concurrent calls spread automatically.
• ETA-Driven Sleep: sleep until the soonest recovery — never burn wasted 429 requests.
• Trust the Connection: zero artificial timeouts on chat, utility, or compression.
• Smart Quarantine: parses providers retry-delay and respects it to the second.
• Long-Delay Warning: surfaces >60s delays (likely daily quotas) for operator awareness.
• Verbose Trace Mode: opt-in observability with key short-id, selection latency, pool snapshot.
• Clean Uninstall: monkey-patches reverted automatically.

Install

1. Download the KAME_v1.0.0.zip asset below.
2. Extract api_rotation_by_kame/ into your Agent Zero /a0/usr/plugins/ directory.
3. In Agent Zero → Settings → Model Provider, enter API keys comma-separated: key1, key2, key3, ...
4. Restart Agent Zero.

Look for the active banner on startup:

🐢⚡ KAME v1.0.0 — ACTIVE

Compatibility

• Agent Zero v1.14+ (verified through v1.15)
• Python 3.10+
• All LiteLLM-supported providers (Google, OpenAI, Anthropic, Mistral, Groq, DeepSeek, xAI, ...)
• No new dependencies

License

MIT — see LICENSE.

Support the project

If KAME saved you from rate-limit hell, consider a tip:

Bitcoin — 36BGYhMEVFgY8PLGMVux93pjGt92KVM6dJ

Full changelog

See CHANGELOG.md for the complete version history (v0.4.x → v1.0.0).

---

🐢⚡ 4P1 R0T4T10N — 4FRE3D0M