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.