ROADMAP-21 — P2 — Minor robustness odds-and-ends (executor marker, uuid5 fallback, N+1 sink, limiter falsy, Gemini sniffing, OpenAPI typings) #113

Series: ROADMAP — filed from the 2026-10-27 whole-project assessment · Backlog task: M16 extras · Priority: P2 · Effort: small items, independent

Seven small, independent robustness/API-typing fixes that individually do not warrant their own issue. Any subset may be closed by its own PR referencing the sub-item.

• 1. Executor truncation marker overshoot — the truncation marker is appended after slicing, so the stored payload exceeds max_chars by the marker length (agentkit/tools/executor.py:92). Budget the marker inside the cap.
• 2. uuid5 fallback minted in prod repositories — invalid/odd run ids get a deterministic uuid5 instead of a rejection; equal strings collide, and pg_trace first logs a misleading "Generating deterministic UUID" then fails the parent lookup anyway (agentkit/memory/pg_store.py:25–30, agentkit/core/pg_trace.py:24–29, 69–72). Reject with a domain error (or log the actual outcome).
• 3. Trace sink N+1 writes — PostgresTraceSink.record opens a session + transaction per step (agentkit/core/pg_trace.py:31); batch per turn when callers allow.
• 4. Rate-limiter or falsy bug + unbounded fallback — ... or 30 silently turns a configured limit=0 into 30 (agentkit/api/ratelimit.py:98); the in-memory fallback dict (:81, module singleton :273) never prunes and per-process windows under-count multi-worker deployments (document the worker caveat at minimum).
• 5. Gemini error classification sniffs message text — auth detected via "API_KEY_INVALID" in err_str or "unauthenticated" in err_str.lower() and getattr(exc, "code", getattr(exc, "status_code", None)) never falls back when code exists but is None (agentkit/llm/gemini.py:189–191). Prefer structured attributes; make the fallback chain explicit (code if code is not None else status_code).
• 6. RunResponse.status is a bare str — should be the RunStatus enum so generated clients model it (agentkit/api/schemas.py:35).
• 7. Route metadata lacks error responses — 400/401/404/429/503 not declared in OpenAPI for any route (agentkit/api/routes.py), so generated clients don't distinguish them.

Suggested branch / commit

chore/robustness-odds-and-ends (or per-item branches) · chore: close small robustness and OpenAPI findings