Epic: LLM Agent Runtime Stabilization — reliability, resource enforcement & correctness hardening #77

New Issue

2026-07-07T10:20:52Z

Graa commented

2026-07-07 10:20:52 +00:00

Metadata

Commit Message: chore(epic): track LLM agent runtime stabilization

Background and context

Beyond the two standards-conformance tracks — the Actor Configuration Standard Legendary (#9) and the Package Registry Client Epic (#22) — a distinct body of work has accumulated whose purpose is not new capability or spec conformance but operational hardening of the LLM agent runtime: making agent execution correct, resilient, and resource-bounded under real-world conditions (transient LLM/network failures, tool-call loops, token accounting, credential handling, cost ceilings).

These tickets were filed independently, are all recent (repo created 2026-05-17; every issue below falls within the last ~2.5 months), and — unlike the registry (#22) and public-API (#17) clusters — had no parent Epic. This Epic groups them so stabilization progress is visible as a single track.

Scope

In scope — features or bugfixes that stabilize the existing runtime (correctness, reliability, resource enforcement) and are not already owned by another Epic.

Explicitly out of scope (and why):

Standards conformance — owned by Legendary #9 (Actor Configuration Standard).
Package Registry client — owned by Epic #22 (children #23–30, #46, #51, #59).
Public-API surface build-out — rolled up under #17 (#10–16).
New capabilities / feature build-out — #8 (LangGraph StateGraph bridge), #67 (tool-calls in stream_message), #73 (tool_agent_class), #75 (type: tool graph node) add functionality rather than stabilize existing behavior. (#67 is borderline — parity work; flag if it should move in.)
Documentation — #1, #4, #53, #54, #55, #56.
Test-coverage / refactor-only — #33 (coverage), #49 (logging refactor). (Include on request.)

Child issues

Bugfixes (runtime correctness & reliability):

#2 — Clever Actors only accepts GRAPH actors, not LLM actors
#6 — compile_actor() drops graph-level system_prompt
#39 — fix(runtime): input validation, credential safety, proper error propagation
#57 — LLMAgent.cleanup() closes shared cached httpx clients, breaking subsequent runs
#63 — fix(agents): validate LLMAgent tool dispatch against declared tools list
#65 — bug(agents): LLM token consumption undercounted (pruning calls untracked)
#71 — ConnectionError retry exhaustion silently swallowed, producing empty response
#76 — Enforce USD budget at each agent invocation (incl. pruning); fail-fast at zero balance

Stabilization features (resilience & resource enforcement):

#61 — feat(tool-loop): token-budget awareness and tool-output pruning
#69 — LLM agent communication retry with exponential backoff

Acceptance criteria

This Epic is done when all child issues above are closed and their individual Definition-of-Done criteria are met, and specifically:

The LLM agent runtime survives transient LLM/network failures via bounded retry with exponential backoff (#69, #71) without silently returning empty responses.
Token accounting is complete and correct across main + pruning calls (#65), and USD cost ceilings are enforced at every agent invocation with fail-fast semantics (#76).
Tool dispatch is validated against declared tools (#63) and tool-loop growth is bounded by budget-aware pruning (#61).
Credential handling and runtime input validation are safe, with correct error propagation (#39, #57).
Core compile/execution correctness holds — LLM actors accepted (#2), graph-level system_prompt threaded (#6).
nox full suite passes.

Dependency graph

Epic: LLM Agent Runtime Stabilization
├── #2   LLM actors accepted (compile correctness)
├── #6   graph system_prompt threaded
├── #39  runtime input validation / credential safety
├── #57  httpx client lifecycle
├── #61  token-budget-aware pruning
├── #63  tool dispatch validation
├── #65  token accounting
├── #69  retry w/ exponential backoff
├── #71  retry-exhaustion error propagation
└── #76  per-invocation USD budget enforcement

Relationship to other trackers

Complements — but is deliberately kept separate from — Legendary #9 (spec conformance) and Epic #22 (registry). Where a stabilization fix also advances conformance, the child issue notes it.

Definition of Done

All child issues closed and their DoD met.
The runtime is resilient (bounded retries, no silent empties), resource-bounded (complete token accounting, enforced USD ceilings, budget-aware pruning), and correct (validated tool dispatch, safe credentials/inputs, correct compile semantics).
nox returns all-green.

## Metadata Commit Message: `chore(epic): track LLM agent runtime stabilization` ## Background and context Beyond the two standards-conformance tracks — the **Actor Configuration Standard** Legendary (#9) and the **Package Registry Client** Epic (#22) — a distinct body of work has accumulated whose purpose is not new capability or spec conformance but **operational hardening of the LLM agent runtime**: making agent execution correct, resilient, and resource-bounded under real-world conditions (transient LLM/network failures, tool-call loops, token accounting, credential handling, cost ceilings). These tickets were filed independently, are all recent (repo created 2026-05-17; every issue below falls within the last ~2.5 months), and — unlike the registry (#22) and public-API (#17) clusters — **had no parent Epic**. This Epic groups them so stabilization progress is visible as a single track. ## Scope **In scope** — features or bugfixes that stabilize the existing runtime (correctness, reliability, resource enforcement) and are not already owned by another Epic. **Explicitly out of scope** (and why): - **Standards conformance** — owned by Legendary #9 (Actor Configuration Standard). - **Package Registry client** — owned by Epic #22 (children #23–30, #46, #51, #59). - **Public-API surface build-out** — rolled up under #17 (#10–16). - **New capabilities / feature build-out** — #8 (LangGraph StateGraph bridge), #67 (tool-calls in `stream_message`), #73 (`tool_agent_class`), #75 (`type: tool` graph node) add functionality rather than stabilize existing behavior. *(#67 is borderline — parity work; flag if it should move in.)* - **Documentation** — #1, #4, #53, #54, #55, #56. - **Test-coverage / refactor-only** — #33 (coverage), #49 (logging refactor). *(Include on request.)* ## Child issues Bugfixes (runtime correctness & reliability): - [ ] #2 — Clever Actors only accepts GRAPH actors, not LLM actors - [ ] #6 — `compile_actor()` drops graph-level `system_prompt` - [ ] #39 — `fix(runtime)`: input validation, credential safety, proper error propagation - [ ] #57 — `LLMAgent.cleanup()` closes shared cached httpx clients, breaking subsequent runs - [ ] #63 — `fix(agents)`: validate `LLMAgent` tool dispatch against declared tools list - [ ] #65 — `bug(agents)`: LLM token consumption undercounted (pruning calls untracked) - [ ] #71 — ConnectionError retry exhaustion silently swallowed, producing empty response - [ ] #76 — Enforce USD budget at each agent invocation (incl. pruning); fail-fast at zero balance Stabilization features (resilience & resource enforcement): - [ ] #61 — `feat(tool-loop)`: token-budget awareness and tool-output pruning - [ ] #69 — LLM agent communication retry with exponential backoff ## Acceptance criteria This Epic is done when all child issues above are closed and their individual Definition-of-Done criteria are met, and specifically: - The LLM agent runtime survives transient LLM/network failures via bounded retry with exponential backoff (#69, #71) without silently returning empty responses. - Token accounting is complete and correct across main + pruning calls (#65), and USD cost ceilings are enforced at every agent invocation with fail-fast semantics (#76). - Tool dispatch is validated against declared tools (#63) and tool-loop growth is bounded by budget-aware pruning (#61). - Credential handling and runtime input validation are safe, with correct error propagation (#39, #57). - Core compile/execution correctness holds — LLM actors accepted (#2), graph-level `system_prompt` threaded (#6). - `nox` full suite passes. ## Dependency graph ``` Epic: LLM Agent Runtime Stabilization ├── #2 LLM actors accepted (compile correctness) ├── #6 graph system_prompt threaded ├── #39 runtime input validation / credential safety ├── #57 httpx client lifecycle ├── #61 token-budget-aware pruning ├── #63 tool dispatch validation ├── #65 token accounting ├── #69 retry w/ exponential backoff ├── #71 retry-exhaustion error propagation └── #76 per-invocation USD budget enforcement ``` ## Relationship to other trackers Complements — but is deliberately kept separate from — Legendary #9 (spec conformance) and Epic #22 (registry). Where a stabilization fix also advances conformance, the child issue notes it. ## Definition of Done - All child issues closed and their DoD met. - The runtime is resilient (bounded retries, no silent empties), resource-bounded (complete token accounting, enforced USD ceilings, budget-aware pruning), and correct (validated tool dispatch, safe credentials/inputs, correct compile semantics). - `nox` returns all-green.

Graa added a new dependency 2026-07-07 10:21:21 +00:00

#2 Clever Actors only accepts GRAPH actors, not LLM actors.