cleveragents/cleveractors-core

Fork 0

feat(executor): let provably zero-cost invocations pass the budget pre-flight #151

Merged

hurui200320 merged 1 commit from feature/m3-budget-gate-zero-cost-carveout into develop

2026-10-20 04:23:54 +00:00

hurui200320 commented

2026-10-13 10:29:04 +00:00

Member

Summary

A fresh execution starts at accumulated = 0, so a max_cost_usd limit of 0.0 (the embedding-platform wallet cap min(platform_cap, wallet.available_balance) on an empty wallet) tripped the >= pre-flight gate before the first node — for every run, regardless of its cost. This blocked runs whose every LLM invocation is provably free: an all-0/0-rate pricing entry (the growing real-world class: big-pickle, glm-5-free, …), the exact case cleveragents-webapp had to work around with a platform-side static zero-cost estimator (cleveragents/cleveragents-webapp#473/#531).

The gate now resolves the upcoming invocation's (provider, model) rates through the exact ladder the gate charges by (lifted from _compute_cost into core.exceptions._resolve_pricing_rates, with a new conservative _is_zero_rated_invocation predicate) and lets a provably free invocation — both resolved rates exactly 0.0 — pass the tripped gate. Everything unresolvable stays blocked: missing/incomplete/invalid entries, half-zero entries, non-AGENT nodes, non-LLM agents, unresolved agent names, empty pricing tables (AC5). PR #80 semantics are preserved: the post-node/post-invocation checks still use >, an exactly-at-limit node still completes, and only the next payable node/invocation is refused (AC6).

What changed

Carve-out at all three pre-flight enforcement points:
- PureLangGraph._check_budget_pre_flight — per node, with the conservative taxonomy helper PureLangGraph._upcoming_node_invocation_is_zero_rated (serves both execute and stream via the shared _node_budget_context). A provably-free node is logged at INFO and allowed.
- LLMAgent._check_budget_before_invoke — tool-loop pre-invoke, via current_pricing + self.provider/self.model (correct at all five call sites; each precedes self.chat_model) — giving it consistent semantics with the per-node pre-flight (AC3). _should_skip_pruning is deliberately unchanged (ADR-2038 D-3: the carve-out does not resurrect extra pruning calls).
- new shared runtime_dispatch._check_single_llm_budget_pre_flight on both single type: llm dispatch functions (AC4): a payable upstream invocation is refused before any agent creation/call; in _execute_llm_stream it raises inside the early-validation wrapper so the billing-integrity executor.last_result placeholder is still populated.
Owner-approved full alignment (review Q2): the non-stream _execute_llm previously had no max_cost_usd enforcement at all — it now mirrors the stream/graph paths with the post-invocation > cost check, the bool/non-numeric limit ladder, and the ADR-2029 "non-empty pricing table ⇒ entry mandatory" validation, so the same config no longer succeeds or fails depending on which executor shape it lands in.
Docs: new docs/adr/ADR-2038-budget-gate-zero-cost-carveout.md (D-1..D-6 + rejected alternatives A-1..A-5, continuing the ADR-2029/PR-#80 lineage) and a CHANGELOG.md [Unreleased] entry. No pyproject.toml bump: no release tag exists and v2.1.0 is still unreleased (analysis recorded on the issue); consumers re-pin by commit SHA.

Tests (written first — confirmed red against the pre-change tree)

Behave (unit BDD): 21 new scenarios — graph path incl. a payable→free→payable chain where the exactly-at-limit payable node completes, the free middle node passes, and the next payable node is blocked (features/execution_limits.feature); tool-loop path incl. pruning-skip and no-pricing-table locks (features/llm_agent_tool_loop.feature); new single-LLM executor suite with invocation-counting mock models asserting no upstream invocation on a payable zero-wallet run (features/budget_gate_single_llm.feature). Two stream scenarios whose enforcement point moved from post-stream to pre-flight are updated so both gates keep dedicated coverage (features/execute_stream.feature).
Robot (integration): 7 new end-to-end tests through real create_executor actors (graph execute, single-LLM execute + stream, tool-loop round; robot/budget_gate_zero_cost.robot).
No ASV benchmark: the carve-out only runs on the exceptional tripped-gate path and the rate-ladder extraction is a pure refactor — nothing performance-sensitive (rationale in ADR-2038 Follow-up).

Quality gates (final tree)

Session	Result
`nox -s format` / `lint`	pass
`nox -s typecheck` (pyright strict)	pass (0 errors)
`nox -s security_scan` (+ `dead_code`)	pass
`nox -s unit_tests`	pass — 155 features, 3136 scenarios, 0 failed
`nox -s integration_tests`	pass — 373 tests, 373 passed, 0 failed
`nox -s coverage_report`	pass — 97.1% (improved from origin/master's 96.90%; every new line covered)

Acceptance criteria check

✅ AC1 — all-zero-rate graph run completes with max_cost_usd: 0.0 (BDD + Robot).
✅ AC2 — positive-rate model with 0.0 fails fast budget_exhausted before any upstream invocation.
✅ AC3 — _check_budget_before_invoke shares the per-node pre-flight semantics.
✅ AC4 — single-LLM (execute + stream) never fires a payable invocation on an exhausted budget.
✅ AC5 — missing/incomplete/invalid pricing entries are never treated as free (conservative default, incl. empty-table).
✅ AC6 — PR #80 >=/> split preserved (exactly-at-limit completes; next payable blocked).

Closes #150

Design record: docs/adr/ADR-2038-budget-gate-zero-cost-carveout.md · Issue journal: full TDD/decision/coverage notes on #150.

Base branch — retargeted to `develop` (2026-10-20)

The PR originally targeted master (the only long-lived branch when the feature branch was cut; decision recorded on #150). Per the updated project policy — new features land on develop — the branch was rebased and the PR retargeted:

Rebased onto origin/develop (9631ee6, virtual-provider docs): new head 4a9818c (previous 17b2e1c; the old base was 14d2132, master's tip and the merge base with develop). Still a single atomic commit — same message, ISSUES CLOSED: #150 footer preserved, no merge commits.
One conflict resolved: CHANGELOG.md [Unreleased] › Added — develop's #155 (backends/strategy) entry kept first, then this PR's #150 entry (newest-first). The llm.py auto-merge was verified sound: develop's virtual-provider wiring and this PR's carve-out touch disjoint regions.
Diff vs develop now contains exactly this feature's 16 files (+2224/−26).
Quality gates re-run on the rebased tree: format (ruff, clean) · lint (ruff) · typecheck (pyright strict) · security_scan (bandit/semgrep) · dead_code (vulture) · complexity — all pass. unit_tests: 156 features, 3174 scenarios, 0 failed (includes develop's virtual-provider suite). integration_tests: 374 tests, 374 passed, 0 failed. coverage_report: 97.2% (97.156% raw; threshold 96.5%, ≥97% standard met). build: wheel OK.

## Summary A fresh execution starts at `accumulated = 0`, so a `max_cost_usd` limit of `0.0` (the embedding-platform wallet cap `min(platform_cap, wallet.available_balance)` on an empty wallet) tripped the `>=` pre-flight gate **before the first node** — for every run, regardless of its cost. This blocked runs whose every LLM invocation is provably free: an all-0/0-rate pricing entry (the growing real-world class: `big-pickle`, `glm-5-free`, …), the exact case cleveragents-webapp had to work around with a platform-side static zero-cost estimator (cleveragents/cleveragents-webapp#473/#531). The gate now resolves the **upcoming invocation's** `(provider, model)` rates through the exact ladder the gate charges by (lifted from `_compute_cost` into `core.exceptions._resolve_pricing_rates`, with a new conservative `_is_zero_rated_invocation` predicate) and lets a **provably free** invocation — both resolved rates exactly `0.0` — pass the tripped gate. Everything unresolvable stays blocked: missing/incomplete/invalid entries, half-zero entries, non-AGENT nodes, non-LLM agents, unresolved agent names, empty pricing tables (AC5). PR #80 semantics are preserved: the post-node/post-invocation checks still use `>`, an exactly-at-limit node still completes, and only the **next payable** node/invocation is refused (AC6). ## What changed - **Carve-out at all three pre-flight enforcement points:** - `PureLangGraph._check_budget_pre_flight` — per node, with the conservative taxonomy helper `PureLangGraph._upcoming_node_invocation_is_zero_rated` (serves both execute and stream via the shared `_node_budget_context`). A provably-free node is logged at INFO and allowed. - `LLMAgent._check_budget_before_invoke` — tool-loop pre-invoke, via `current_pricing` + `self.provider`/`self.model` (correct at all five call sites; each precedes `self.chat_model`) — giving it consistent semantics with the per-node pre-flight (AC3). `_should_skip_pruning` is deliberately unchanged (ADR-2038 D-3: the carve-out does not resurrect extra pruning calls). - new shared `runtime_dispatch._check_single_llm_budget_pre_flight` on **both** single ``type: llm`` dispatch functions (AC4): a payable upstream invocation is refused before any agent creation/call; in `_execute_llm_stream` it raises inside the early-validation wrapper so the billing-integrity `executor.last_result` placeholder is still populated. - **Owner-approved full alignment (review Q2):** the non-stream `_execute_llm` previously had **no** `max_cost_usd` enforcement at all — it now mirrors the stream/graph paths with the post-invocation `>` cost check, the bool/non-numeric limit ladder, and the ADR-2029 "non-empty pricing table ⇒ entry mandatory" validation, so the same config no longer succeeds or fails depending on which executor shape it lands in. - **Docs:** new `docs/adr/ADR-2038-budget-gate-zero-cost-carveout.md` (D-1..D-6 + rejected alternatives A-1..A-5, continuing the ADR-2029/PR-#80 lineage) and a `CHANGELOG.md` [Unreleased] entry. No `pyproject.toml` bump: no release tag exists and v2.1.0 is still unreleased (analysis recorded on the issue); consumers re-pin by commit SHA. ## Tests (written first — confirmed red against the pre-change tree) - **Behave (unit BDD):** 21 new scenarios — graph path incl. a payable→free→payable chain where the exactly-at-limit payable node completes, the free middle node passes, and the next payable node is blocked (`features/execution_limits.feature`); tool-loop path incl. pruning-skip and no-pricing-table locks (`features/llm_agent_tool_loop.feature`); new single-LLM executor suite with invocation-counting mock models asserting **no upstream invocation** on a payable zero-wallet run (`features/budget_gate_single_llm.feature`). Two stream scenarios whose enforcement point moved from post-stream to pre-flight are updated so both gates keep dedicated coverage (`features/execute_stream.feature`). - **Robot (integration):** 7 new end-to-end tests through real `create_executor` actors (graph execute, single-LLM execute + stream, tool-loop round; `robot/budget_gate_zero_cost.robot`). - **No ASV benchmark:** the carve-out only runs on the exceptional tripped-gate path and the rate-ladder extraction is a pure refactor — nothing performance-sensitive (rationale in ADR-2038 Follow-up). ## Quality gates (final tree) | Session | Result | |---|---| | `nox -s format` / `lint` | pass | | `nox -s typecheck` (pyright strict) | pass (0 errors) | | `nox -s security_scan` (+ `dead_code`) | pass | | `nox -s unit_tests` | pass — 155 features, 3136 scenarios, 0 failed | | `nox -s integration_tests` | pass — 373 tests, 373 passed, 0 failed | | `nox -s coverage_report` | pass — **97.1%** (improved from origin/master's 96.90%; every new line covered) | ## Acceptance criteria check - ✅ AC1 — all-zero-rate graph run completes with `max_cost_usd: 0.0` (BDD + Robot). - ✅ AC2 — positive-rate model with 0.0 fails fast `budget_exhausted` before any upstream invocation. - ✅ AC3 — `_check_budget_before_invoke` shares the per-node pre-flight semantics. - ✅ AC4 — single-LLM (execute + stream) never fires a payable invocation on an exhausted budget. - ✅ AC5 — missing/incomplete/invalid pricing entries are never treated as free (conservative default, incl. empty-table). - ✅ AC6 — PR #80 `>=`/`>` split preserved (exactly-at-limit completes; next payable blocked). Closes #150 Design record: `docs/adr/ADR-2038-budget-gate-zero-cost-carveout.md` · Issue journal: full TDD/decision/coverage notes on #150. ## Base branch — retargeted to `develop` (2026-10-20) The PR originally targeted `master` (the only long-lived branch when the feature branch was cut; decision recorded on #150). Per the updated project policy — new features land on `develop` — the branch was rebased and the PR retargeted: - **Rebased onto `origin/develop`** (`9631ee6`, virtual-provider docs): new head `4a9818c` (previous `17b2e1c`; the old base was `14d2132`, master's tip and the merge base with develop). Still a single atomic commit — same message, `ISSUES CLOSED: #150` footer preserved, no merge commits. - **One conflict resolved:** `CHANGELOG.md` `[Unreleased] › Added` — develop's #155 (`backends`/`strategy`) entry kept first, then this PR's #150 entry (newest-first). The `llm.py` auto-merge was verified sound: develop's virtual-provider wiring and this PR's carve-out touch disjoint regions. - **Diff vs develop now contains exactly this feature's 16 files** (+2224/−26). - **Quality gates re-run on the rebased tree:** `format` (ruff, clean) · `lint` (ruff) · `typecheck` (pyright strict) · `security_scan` (bandit/semgrep) · `dead_code` (vulture) · `complexity` — all pass. `unit_tests`: **156 features, 3174 scenarios, 0 failed** (includes develop's virtual-provider suite). `integration_tests`: **374 tests, 374 passed, 0 failed**. `coverage_report`: **97.2%** (97.156% raw; threshold 96.5%, ≥97% standard met). `build`: wheel OK.

hurui200320 added 1 commit

2026-10-13 10:29:05 +00:00

feat(executor): let provably zero-cost invocations pass the budget pre-flight

CI / integration_tests (pull_request) Has been cancelled

Details

CI / quality (pull_request) Has been cancelled

Details

CI / lint (pull_request) Has been cancelled

Details

CI / build (pull_request) Has been cancelled

Details

CI / status-check (pull_request) Has been cancelled

Details

CI / security (pull_request) Has been cancelled

Details

CI / typecheck (pull_request) Has been cancelled

Details

CI / unit_tests (pull_request) Has been cancelled

Details

CI / coverage (pull_request) Has been cancelled

Details

CI / benchmark (pull_request) Has been cancelled

Details

17b2e1c35b

The max_cost_usd pre-flight gate raises budget_exhausted when
accumulated >= limit before an invocation (issue #76, PR #80). A fresh
execution starts at accumulated = 0, so a 0.0 limit (the embedding-
platform case max_cost_usd = min(platform_cap, wallet.available_balance)
on an empty wallet) tripped the gate before the first node for every
run, blocking runs whose every LLM invocation is provably free — a real,
growing class of catalogued 0/0-rate models (big-pickle, glm-5-free).
Consumers had to ship a platform-side static zero-cost estimator purely
to work around it (cleveragents/cleveragents-webapp#531).

The gate now resolves the upcoming invocation's (provider, model) rates
through the exact ladder the gate charges by — lifted from _compute_cost
into core.exceptions._resolve_pricing_rates with a conservative
_is_zero_rated_invocation predicate — and lets the invocation pass the
tripped gate only when both resolved rates are exactly 0.0. Anything
unresolvable still blocks: missing/incomplete/invalid entries, half-zero
entries, non-AGENT nodes, non-LLM agents, unresolved agent names, empty
pricing tables (issue #150 AC5, the same conservative default the
platform-side estimator applies). PR #80 semantics are preserved: post-
node/post-invocation checks stay >, so an exactly-at-limit node still
completes and only the next payable node/invocation is refused.

Applied at all three pre-flight enforcement points:
- PureLangGraph._check_budget_pre_flight (per node, execute and stream
  share it via _node_budget_context), with the conservative taxonomy
  helper _upcoming_node_invocation_is_zero_rated;
- LLMAgent._check_budget_before_invoke (tool-loop pre-invoke, correct
  for all five call sites since each precedes self.chat_model);
  purely-suppressant _should_skip_pruning is deliberately unchanged
  (ADR-2038 D-3: a free invocation does not resurrect pruning);
- new shared runtime_dispatch._check_single_llm_budget_pre_flight for
  both single-type:llm dispatch functions (AC4). In _execute_llm_stream
  it raises inside the early-validation wrapper so the billing-integrity
  executor.last_result placeholder is still populated.

Owner-approved full alignment also closes a discovered enforcement gap:
the non-stream _execute_llm path had no max_cost_usd enforcement at all
(neither pre-flight nor post-invocation). It now mirrors the stream and
graph shapes with the post-invocation > cost check, the bool/non-numeric
limit ladder, and the ADR-2029 non-empty-pricing-table entry validation,
so the same config no longer succeeds or fails depending on which
executor shape it lands in.

Docs: new ADR-2038 (docs/adr/ADR-2038-budget-gate-zero-cost-carveout.md,
continuing the ADR-2029/PR-80 budget lineage) and a CHANGELOG.md
[Unreleased] entry; no pyproject version bump since v2.1.0 is still
unreleased (no tags; every prior milestone feature also landed under
[Unreleased]) and the release process is tag-driven.

Tests: 21 new Behave scenarios (features/execution_limits.feature graph
path incl. the payable-then-free-then-payable chain, features/
llm_agent_tool_loop.feature tool-loop path incl. pruning-skip and
no-pricing-table locks, new features/budget_gate_single_llm.feature
single-LLM execute/stream with invocation-counting mock models) plus 7
new Robot integration tests (robot/budget_gate_zero_cost.robot) driving
real create_executor actors end to end. The two single-LLM stream
scenarios whose enforcement point moved from post-stream to pre-flight
were updated to cover both gates separately. Gates: nox format, lint,
typecheck, security_scan, dead_code, unit_tests (3136 scenarios),
integration_tests (373 tests), coverage_report all pass; coverage
improved from 96.90% (origin/master, measured) to 97.11%, above the
97% standard, with every new line covered.

ISSUES CLOSED: #150

hurui200320 added this to the v2.1.0 milestone

2026-10-13 10:29:52 +00:00

hurui200320 added the

Type

Feature

label

2026-10-13 10:29:55 +00:00

hurui200320 added a new dependency

2026-10-13 10:29:57 +00:00

#150 Budget pre-flight gate (accumulated >= limit) blocks provably zero-cost runs when max_cost_usd=0.0

hurui200320 referenced this pull request

2026-10-13 10:32:26 +00:00

Budget pre-flight gate (accumulated >= limit) blocks provably zero-cost runs when max_cost_usd=0.0 #150

hurui200320 referenced this pull request

2026-10-13 10:54:04 +00:00

Budget pre-flight gate (accumulated >= limit) blocks provably zero-cost runs when max_cost_usd=0.0 #150

hurui200320 force-pushed feature/m3-budget-gate-zero-cost-carveout from 17b2e1c35b

CI / integration_tests (pull_request) Has been cancelled

Details

CI / quality (pull_request) Has been cancelled

Details

CI / lint (pull_request) Has been cancelled

Details

CI / build (pull_request) Has been cancelled

Details

CI / status-check (pull_request) Has been cancelled

Details

CI / security (pull_request) Has been cancelled

Details

CI / typecheck (pull_request) Has been cancelled

Details

CI / unit_tests (pull_request) Has been cancelled

Details

CI / coverage (pull_request) Has been cancelled

Details

CI / benchmark (pull_request) Has been cancelled

Details

to 4a9818cbdf

CI / lint (pull_request) Successful in 1m5s

Details

CI / typecheck (pull_request) Successful in 1m32s

Details

CI / quality (pull_request) Successful in 1m32s

Details

CI / build (pull_request) Successful in 2m19s

Details

CI / security (pull_request) Successful in 3m3s

Details

CI / integration_tests (pull_request) Successful in 3m39s

Details

CI / benchmark (pull_request) Failing after 19m14s

Details

CI / unit_tests (pull_request) Failing after 19m28s

Details

CI / lint (push) Successful in 32s

Details

CI / typecheck (push) Successful in 1m6s

Details

CI / security (push) Successful in 55s

Details

CI / quality (push) Successful in 1m5s

Details

CI / build (push) Successful in 36s

Details

CI / integration_tests (push) Failing after 3m42s

Details

CI / unit_tests (push) Successful in 5m35s

Details

CI / benchmark (push) Failing after 13m33s

Details

CI / coverage (push) Failing after 13m19s

Details

CI / coverage (pull_request) Has been cancelled

Details

CI / status-check (pull_request) Has been cancelled

Details

CI / status-check (push) Has been cancelled

Details

2026-10-20 03:40:38 +00:00

Compare

hurui200320 changed target branch from master to develop

2026-10-20 03:40:49 +00:00

hurui200320 referenced this pull request

2026-10-20 03:42:16 +00:00

Budget pre-flight gate (accumulated >= limit) blocks provably zero-cost runs when max_cost_usd=0.0 #150

hurui200320 referenced this pull request

2026-10-20 04:18:49 +00:00

Budget pre-flight gate (accumulated >= limit) blocks provably zero-cost runs when max_cost_usd=0.0 #150

hurui200320 reviewed

2026-10-20 04:18:50 +00:00

hurui200320 left a comment

Self-QA Review — ✅ Approve

PR: #151 · Ticket: #150 · Reviewed head: 4a9818c · Base: develop (9631ee6)

Verdict: Approve — 0 critical / 0 major / 3 minor / 2 nits. The change faithfully implements the ticket's zero-cost carve-out at all three pre-flight enforcement points, preserves PR #80's >=/> split (AC6), and closes the single-LLM enforcement gaps (AC4).

Verified in depth:

The _resolve_pricing_rates extraction (lifted from _compute_cost) is a pure, behavior-preserving refactor — same ladder, same errors/coercion; exceptions.py at 100% line coverage.
The carve-out resolves rates through the exact ladder the gate charges by, so the conservative taxonomy (AC5) cannot drift from the charging rule: missing/incomplete/invalid/half-zero entries, empty table, non-AGENT nodes, non-LLM agents, unknown nodes all stay blocked.
All _check_budget_before_invoke call sites precede self.chat_model; _should_skip_pruning deliberately unchanged (ADR-2038 D-3).
Single-LLM dispatch (execute + stream): payable invocations are refused before any agent creation; the stream path raises inside the early-validation wrapper so the billing-integrity executor.last_result placeholder stays populated.
Non-stream _execute_llm now mirrors the stream/graph post-invocation semantics (bool/non-numeric limit ladder, ADR-2029 entry validation).
Tests: invocation-counting mocks prove zero upstream invocations on refusal; the payable→free→payable chain pins both carve-out sides plus AC6; 27 new Behave scenarios and 7 Robot tests.
Commit hygiene: single atomic commit, ISSUES CLOSED: #150 footer, no merge commits.

Quality gates — run locally (CI is currently broken; CI status was not used):

Session	Result
format / lint / security_scan / dead_code / complexity	pass
typecheck	pass (0 errors) *
unit_tests	pass — 156 features, 3,174 scenarios, 0 failed
integration_tests	pass — 374/374
coverage_report	pass — 97.2% (raw 97.156%; threshold 96.5%)

* Observation (pre-existing, not this PR): pyrightconfig.json sets typeCheckingMode: "off", which overrides strict in pyproject.toml — worth a separate issue.

Non-blocking follow-ups (nothing blocks merge):

(m) Mixed graphs remain blocked on a 0.0 wallet — SPEND-inert TOOL/FUNCTION/ROUTER/SUBGRAPH nodes are deliberately not carved out (ADR-2038 D-2); the limitation should be documented / a follow-up opened so the webapp estimator replacement is not over-promised.
(m) No direct Behave/Robot scenario for the graph stream carve-out (shared via _node_budget_context; low risk).
(m) ADR number collision: ADR-2038-* already exists on develop (virtual-provider-load-balanced-backend-routing); resolve before v2.1.0 is tagged.
(n) Prose says "21 new Behave scenarios"; the actual count is 27 (committed tests are correct).
(n) Grammar in ADR-2038 (~line 181): "is fold into" → "is folded into".
(n) _is_zero_rated_invocation annotation should accept dict | None (runtime-safe today).

Self-QA loop: iteration 1/5 — approved on the first cycle; no fix cycle was required.

## Self-QA Review — ✅ Approve **PR:** #151 · **Ticket:** #150 · **Reviewed head:** 4a9818c · **Base:** develop (9631ee6) **Verdict: Approve** — 0 critical / 0 major / 3 minor / 2 nits. The change faithfully implements the ticket's zero-cost carve-out at all three pre-flight enforcement points, preserves PR #80's >=/> split (AC6), and closes the single-LLM enforcement gaps (AC4). **Verified in depth:** - The `_resolve_pricing_rates` extraction (lifted from `_compute_cost`) is a pure, behavior-preserving refactor — same ladder, same errors/coercion; `exceptions.py` at 100% line coverage. - The carve-out resolves rates through the exact ladder the gate charges by, so the conservative taxonomy (AC5) cannot drift from the charging rule: missing/incomplete/invalid/half-zero entries, empty table, non-AGENT nodes, non-LLM agents, unknown nodes all stay blocked. - All `_check_budget_before_invoke` call sites precede `self.chat_model`; `_should_skip_pruning` deliberately unchanged (ADR-2038 D-3). - Single-LLM dispatch (execute + stream): payable invocations are refused before any agent creation; the stream path raises inside the early-validation wrapper so the billing-integrity `executor.last_result` placeholder stays populated. - Non-stream `_execute_llm` now mirrors the stream/graph post-invocation semantics (bool/non-numeric limit ladder, ADR-2029 entry validation). - Tests: invocation-counting mocks prove zero upstream invocations on refusal; the payable→free→payable chain pins both carve-out sides plus AC6; 27 new Behave scenarios and 7 Robot tests. - Commit hygiene: single atomic commit, `ISSUES CLOSED: #150` footer, no merge commits. **Quality gates — run locally (CI is currently broken; CI status was not used):** | Session | Result | |---|---| | format / lint / security_scan / dead_code / complexity | pass | | typecheck | pass (0 errors) * | | unit_tests | pass — 156 features, 3,174 scenarios, 0 failed | | integration_tests | pass — 374/374 | | coverage_report | pass — 97.2% (raw 97.156%; threshold 96.5%) | \* Observation (pre-existing, not this PR): `pyrightconfig.json` sets `typeCheckingMode: "off"`, which overrides `strict` in `pyproject.toml` — worth a separate issue. **Non-blocking follow-ups (nothing blocks merge):** 1. (m) Mixed graphs remain blocked on a 0.0 wallet — SPEND-inert TOOL/FUNCTION/ROUTER/SUBGRAPH nodes are deliberately not carved out (ADR-2038 D-2); the limitation should be documented / a follow-up opened so the webapp estimator replacement is not over-promised. 2. (m) No direct Behave/Robot scenario for the graph **stream** carve-out (shared via `_node_budget_context`; low risk). 3. (m) ADR number collision: `ADR-2038-*` already exists on develop (`virtual-provider-load-balanced-backend-routing`); resolve before v2.1.0 is tagged. 4. (n) Prose says "21 new Behave scenarios"; the actual count is 27 (committed tests are correct). 5. (n) Grammar in ADR-2038 (~line 181): "is fold into" → "is folded into". 6. (n) `_is_zero_rated_invocation` annotation should accept `dict | None` (runtime-safe today). Self-QA loop: iteration 1/5 — approved on the first cycle; no fix cycle was required.

hurui200320 merged commit 4a9818cbdf into develop

2026-10-20 04:23:54 +00:00

hurui200320 deleted branch feature/m3-budget-gate-zero-cost-carveout

2026-10-20 04:23:55 +00:00