feat(agent): clear missing-package error, opt-in strict, on_error hook (O1/O2 engine half)#25
Merged
Merged
Conversation
…k (O1/O2 engine) Engine foundation for the agent-error-clarity work (fastapi-guard + guard-agent halves to follow). - to_agent_config() raises AgentPackageNotInstalledError (naming the package and install command) instead of returning an ambiguous None, so a missing guard-agent can no longer masquerade as an 'invalid config / check agent_api_key' error in adapters. - SecurityConfig.agent_strict (default False): adapters raise at init instead of degrading to agent-off when True. - SecurityConfig.on_error (default None): one best-effort on_error(stage, exc, context) hook; utils.invoke_error_hook invokes it and never lets a raising hook propagate into the request path. - Stop the silent GeoIP drop: SecurityEventBus._lookup_country now logs at warning and fires on_error(stage='geoip') instead of swallowing the exception. Async + sync mirror; full suites green; all pre-commit gates incl. check-sync green.
github-actions
Bot
added
area: core-subsystems
- cover the defensive branches O5/O6 left uncovered: _ip_in_list non-IP entry fallback + _check_whitelist empty (utils), restrictive route whitelist block (helpers), AWS prefix without a region field (cloud_handler), and the CompositeAgentHandler started/degraded/failed_handlers properties. - replace deprecated redis setex(k, ttl, v) with set(k, v, ex=ttl) (async+sync). - filter the unavoidable opentelemetry SelectableGroups DeprecationWarning. Full async+sync suite: 100% lines + branches, 3696 passed, zero warnings.
github-actions
Bot
added
area: handlers
rennf93
added a commit
that referenced
this pull request
Jun 23, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Engine foundation for the agent-error-clarity design-partner feedback (O1 + O2). The fastapi-guard adapter half and the guard-agent transport half build on this.
What
A design partner couldn't tell when agent telemetry failed: a missing
guard-agentpackage produced a silent warning and a misleading "check agent_api_key" error, and other failures (GeoIP) were swallowed silently.to_agent_config()now raisesAgentPackageNotInstalledError(naming the package + install command) instead of returning an ambiguousNone. A missingguard-agentcan no longer masquerade as "configuration is invalid / check agent_api_key" in adapters.SecurityConfig.agent_strict(defaultFalse) — adapters raise at init instead of degrading to agent-off whenTrue. Fail-soft stays the default for availability-sensitive deployments.on_errorhook (O2).SecurityConfig.on_error(defaultNone) is one best-efforton_error(stage, exc, context)callback (stage∈agent_init/geoip/transport_send/encryption).utils.invoke_error_hookinvokes it and never lets a raising hook propagate into the request path.SecurityEventBus._lookup_countrynow logs at warning and fireson_error(stage="geoip")instead of a bareexcept Exception: return None.Decisions (confirmed with maintainer)
Fail-soft default + opt-in strict · fix in guard-core engine (all adapters benefit) · single
on_error(stage, exc, context)hook · (fastapi-guard[agent]extra lands in the adapter PR).Verification
tests/test_agent_error_clarity.py(+ updatedto_agent_configimport-error test); generated sync mirror runs the same suite (parity).check-syncgreen.Follow-ups (same feature, separate repos)
AgentConfig.on_error+ fire at transport send/flush + encryption-abort swallow points.[agent]extra + middleware restructure (catchAgentPackageNotInstalledError→ one clear error; honoragent_strict; fireon_error; surface agent-degraded state viaget_stats/health_check).Version bump deferred until the three repos land together.