feat: 2.1.0 — ExecutorErrorCode taxonomy + structured error events (Phase 1)

[CocoRoF]

Adds stable, fine-grained error codes to every executor exception so hosts can group errors for logging / Sentry / i18n / telemetry without parsing message strings. Fully backward compatible — every existing call site keeps working unchanged.

Why

The current error surface gives downstream consumers only:

• An exception class (APIError, StageError, …) — too coarse for i18n.
• A free-form English message — fragile to parse, hostile to translate.
• ErrorCategory on APIError only — answers "should I retry?" but not "what specifically broke?".

Hosts working around this have to grep message text (Geny's frontend currently does exactly this for the red "Error: Claude Code CLI is not authenticated…" banner — verbatim English server message, no i18n hook).

What's new

1. ExecutorErrorCode enum (core/errors.py)

~30 codes in exec.<component>.<reason> format spanning the api / cli / pipeline / stage / tool / mutation / mcp components. Naming mirrors the existing ToolErrorCode precedent. Examples:

ExecutorErrorCode.EXEC_CLI_AUTH_FAILED          # = "exec.cli.auth_failed"
ExecutorErrorCode.EXEC_API_RATE_LIMITED         # = "exec.api.rate_limited"
ExecutorErrorCode.EXEC_API_RETRY_EXHAUSTED      # = "exec.api.retry_exhausted"
ExecutorErrorCode.EXEC_STAGE_GUARD_REJECTED     # = "exec.stage.guard_rejected"
ExecutorErrorCode.EXEC_TOOL_CRASHED             # = "exec.tool.crashed"

Full table + recoverability + recommended user-facing action lives in docs/error_codes.md.

2. GenyExecutorError.code attribute

Every executor exception now exposes a code attribute resolved as:

explicit code= kwarg > category-derived (APIError) > subclass _DEFAULT_CODE

code is always set on the exception instance; downstream consumers can rely on it never being None.

3. Structured error event payloads

pipeline.error / stage.error / api.retry events now carry:

{
    "error": "<stringified message>",      # legacy field, preserved
    "code": "exec.cli.auth_failed",         # new, stable identifier
    "exception_type": "geny_executor.core.errors.APIError"  # new
}

Hosts can switch over to data["code"] for i18n / telemetry without disturbing existing consumers that read data["error"].

4. Explicit codes on Stage 6's most operational raise sites

• EXEC_API_NO_CLIENT — state.llm_client is None config bug
• EXEC_API_RETRY_EXHAUSTED — recoverable category but max_retries hit
• EXEC_API_STREAM_INCOMPLETE — stream ended without message_complete

All other Stage 6 APIError raises auto-resolve via the category default mapping — no per-site change needed.

5. docs/error_codes.md

Authoritative reference for every code: recoverability, source raise sites, description, recommended user-facing action. Includes "how to add a new code" + "how to deprecate a code" workflow so the taxonomy stays curated.

6. tests/contract/test_error_codes_stability.py

Pins every shipped code's exact string value in a frozen dict. Renaming / repurposing / accidentally deleting a code now fails CI before release. Verifies:

• frozen string values match enum (catches renames)
• every enum member is in the frozen pin (catches additions that bypass the docs flow)
• all codes match the exec.<component>.<reason> format (lowercase, dot-separated, ≤4 segments)
• every ErrorCategory has a non-fallback default code (so legacy raises never degrade to exec.unknown)
• APIError resolution matrix (explicit > category > default) works correctly across all combinations

Stability contract

Once a release ships, a code's string value never changes. Renaming or repurposing is a major-version change. The regression test enforces this.

Backward compatibility

• All existing call sites work unchanged. raise APIError("...", category=ErrorCategory.CLI_AUTH_FAILED) keeps working and now carries .code = ExecutorErrorCode.EXEC_CLI_AUTH_FAILED for free.
• All existing event consumers work unchanged. data["code"] is purely additive.
• No exception class signatures break. Only an optional code= kwarg added.

Roadmap (post-merge)

• Phase 2: Geny middleware — agent_session.py error-catch paths preserve code, session_logger metadata, WebSocket payload, frontend ErrorBanner renders via i18n key executor.{code}.
• Phase 3: Refit remaining raise sites (StageError, MutationError, MCP) with explicit codes; drain generic RuntimeError/ValueError to typed exceptions.
• Phase 4: Doc polish + per-code "what does the user do" advice.

Test results

3138 passed, 8 skipped, 0 failed (+11 new stability tests; previous baseline was 3127).

🤖 Generated with Claude Code