didericis/bot-bottle
1
0
Fork 0
Code Issues 7 Pull Requests 15 Actions Packages Projects Releases Wiki Activity

PRD: Egress control plane — metering, budgets, and forced cutoff #285

Open
didericis-claude wants to merge 1 commits from prd-egress-control-plane into main
pull from: prd-egress-control-plane
merge into: didericis:main
Conversation 0 Commits 1 Files Changed 1
+247
didericis-claude commented 2026-06-25 19:15:59 -04:00
Collaborator
Copy Link
Copy Source

Closes #251.

PRD: 99ba532783/docs/prds/prd-new-egress-control-plane.md

Summary

Drafts the design for an out-of-band egress enforcement & cost-control plane (Plane A), distinct from the agent-initiated supervise sidecar (Plane B, PRD 0013). The egress proxy meters authoritative token usage per bottle/provider, budgets are evaluated with agent → bottle → parent → global precedence, and budget exhaustion fires a per-bottle cutoff policy (cutoff / freeze / kill) host-side — never via the supervise queue.

Captures the decisions from the #251 thread:

  • SQLite, now but narrow. New host-level ledger at ~/.bot-bottle/bot-bottle.db behind a thin repository API; sqlite3 is stdlib so it doesn't break the stdlib-first stance. Existing per-bottle flat-file state is not migrated.
  • Gate vs. account split. Accounting uses authoritative response usage (via the existing egress response hook, with SSE final-usage tailing); a count_tokens estimator/endpoint is reserved for an optional pre-flight gate.
  • ~/.bot-bottle/settings.yml (host root, not per-repo) for budgets keyed by provider + default shutdown policy, within the yaml_subset.py subset.
  • Host-level controller + TUI dashboard, host-only — remote control / authn deferred.

Open questions

Carried in the PRD: SSE usage-tailing robustness, mid-request budget crossing vs. pre-flight gate, provider↔host attribution, parent-bottle budget semantics for extends chains, and the dashboard↔controller transport seam.

Closes #251. PRD: https://gitea.dideric.is/didericis/bot-bottle/src/commit/99ba5327830363cd2cc2a081eca0e6cd0c1e2076/docs/prds/prd-new-egress-control-plane.md ## Summary Drafts the design for an **out-of-band egress enforcement & cost-control plane** (Plane A), distinct from the agent-initiated supervise sidecar (Plane B, PRD 0013). The egress proxy meters authoritative token usage per bottle/provider, budgets are evaluated with **agent → bottle → parent → global** precedence, and budget exhaustion fires a per-bottle **cutoff policy** (`cutoff` / `freeze` / `kill`) host-side — never via the supervise queue. Captures the decisions from the #251 thread: - **SQLite, now but narrow.** New host-level ledger at `~/.bot-bottle/bot-bottle.db` behind a thin repository API; `sqlite3` is stdlib so it doesn't break the stdlib-first stance. Existing per-bottle flat-file state is **not** migrated. - **Gate vs. account split.** Accounting uses authoritative response `usage` (via the existing egress `response` hook, with SSE final-usage tailing); a `count_tokens` estimator/endpoint is reserved for an optional pre-flight gate. - **`~/.bot-bottle/settings.yml`** (host root, not per-repo) for budgets keyed by provider + default shutdown policy, within the `yaml_subset.py` subset. - **Host-level controller + TUI dashboard**, host-only — remote control / authn deferred. ## Open questions Carried in the PRD: SSE usage-tailing robustness, mid-request budget crossing vs. pre-flight gate, provider↔host attribution, parent-bottle budget semantics for `extends` chains, and the dashboard↔controller transport seam.
didericis-claude added 1 commit 2026-06-25 19:16:00 -04:00
docs(prd): add PRD for egress control plane 99ba532783 
Out-of-band egress enforcement & cost-control plane: meter token usage
at the egress proxy, evaluate budgets with agent→bottle→parent→global
precedence, and force cutoff/freeze/kill without the agent in the loop.
Introduces a host-level SQLite ledger behind a thin repository API and a
host-only TUI dashboard. Closes the design discussion on #251.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NkwFXLFff9PYPy4wgVBJp9
This pull request can be merged automatically.
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin prd-egress-control-plane:prd-egress-control-plane
git checkout prd-egress-control-plane
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Low
4
The priority is low
Priority
Medium
3
The priority is medium
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
didericis-claude (didericis (claude)) didericis-codex (didericis (codex)) didericis-gemma (gemma) didericis
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: didericis/bot-bottle#285
Delete Branch "prd-egress-control-plane"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?