mosaicstack/stack
1
0
Fork 0
Code Issues 24 Pull Requests 3 Actions Packages Projects Releases 14 Wiki Activity

feat(orchestration): budget windows with arbitrary reset datetimes #558

New Issue
Open
opened 2026-06-19 21:50:30 +00:00 by jason.woltje · 0 comments
jason.woltje commented 2026-06-19 21:50:30 +00:00
Owner
Copy Link

Problem

Mosaic orchestration currently has no durable concept of AI-provider budget windows. OAuth subscription quotas can reset at arbitrary datetimes, not only calendar/month boundaries. Without budget-window awareness, an orchestrator can over-dispatch expensive workers near quota exhaustion, or under-use available quota before reset.

Desired capability

Add a first-class budget/reset model for Mosaic Stack orchestration so the system can:

  • store per-provider / per-profile budget limits and reset datetimes;
  • allow explicit user entry when the reset time is known;
  • attempt autodetection from provider/OAuth subscription signals where feasible;
  • treat reset datetime as arbitrary, not just daily/monthly;
  • make orchestration dispatch mindful of remaining budget, task estimates, model tier, and time until reset;
  • surface budget state clearly in mission status / coordinator output;
  • degrade gracefully when budget state is unknown.

Initial product requirements

Budget model

  • Support multiple budget scopes:
    • provider account/subscription, e.g. Claude OAuth, OpenAI/ChatGPT, OpenRouter, etc.
    • Hermes profile / Mosaic agent role;
    • project or mission override where needed.
  • Store:
    • budget amount and unit, e.g. messages, tokens, dollars, credits, compute-minutes, provider-specific quota unit;
    • observed/entered usage;
    • reset datetime with timezone/offset;
    • confidence/source: user-entered, provider-detected, estimated, unknown;
    • last detection/check timestamp.
  • Reset datetime must accept arbitrary ISO timestamps, not only recurrence presets.

User entry

  • Provide a safe CLI/config path to set/update budget and reset time manually.
  • Prefer commands shaped like:
    • mosaic budget set --provider <name> --limit <n> --unit <unit> --reset-at <iso-datetime>
    • mosaic budget status
    • mosaic budget reset --provider <name> --reset-at <iso-datetime>
  • Validate timezone handling and display both local and UTC where useful.

Autodetection

  • Investigate provider-specific detection seams.
  • Autodetection must be best-effort and source-tagged; do not pretend confidence where provider APIs/OAuth UIs do not expose authoritative reset data.
  • Include a manual override path for every detected value.
  • Never scrape or store secrets outside existing Mosaic credential rails.

Orchestration behavior

  • Coordinator should consider budget before dispatching workers:
    • avoid launching high-cost lanes when budget is low and reset is far away;
    • prefer cheaper model/runtime when acceptable;
    • delay/schedule non-urgent work until after reset;
    • spend remaining budget intentionally when reset is near and critical work is ready;
    • record budget-based routing decisions in mission state.
  • Budget checks should become a dispatch gate, not an afterthought.

Evidence and observability

  • Mission status should report budget state and reset horizon.
  • Dispatch logs should record why a model/runtime was selected or deferred.
  • CI/tests should cover boundary cases: reset passed, reset imminent, unknown reset, manual override, and exhausted budget.

Suggested implementation lanes

  1. PRD/ADR: define budget domain model, storage location, config format, and provider detection boundaries.
  2. CLI skeleton: mosaic budget status/set/reset with local config persistence and tests.
  3. Coordinator integration: dispatch gate reads budget state and records decisions.
  4. Provider detection spikes: Claude OAuth/OpenAI/OpenRouter/etc. as source-tagged adapters.
  5. UX/status: expose budget window in mission status and orchestration summaries.

Acceptance criteria

  • A user can manually enter a budget limit and arbitrary reset datetime.
  • The system stores and displays budget/reset state without losing timezone semantics.
  • Orchestration dispatch can consume budget state and choose/defer work based on configured policy.
  • Unknown/autodetected/user-entered states are distinguishable.
  • Tests cover arbitrary reset datetimes and budget gate decisions.
  • Documentation explains provider limitations and the manual override workflow.

Notes

This should be implemented as a proper Mosaic Stack feature, not a one-off local convention. It belongs in the orchestration/control-plane roadmap and should align with the AI Guide delivery model: PRD first, decomposed lanes, independent review, green CI, and post-merge verification.

## Problem Mosaic orchestration currently has no durable concept of AI-provider budget windows. OAuth subscription quotas can reset at arbitrary datetimes, not only calendar/month boundaries. Without budget-window awareness, an orchestrator can over-dispatch expensive workers near quota exhaustion, or under-use available quota before reset. ## Desired capability Add a first-class budget/reset model for Mosaic Stack orchestration so the system can: - store per-provider / per-profile budget limits and reset datetimes; - allow explicit user entry when the reset time is known; - attempt autodetection from provider/OAuth subscription signals where feasible; - treat reset datetime as arbitrary, not just daily/monthly; - make orchestration dispatch mindful of remaining budget, task estimates, model tier, and time until reset; - surface budget state clearly in mission status / coordinator output; - degrade gracefully when budget state is unknown. ## Initial product requirements ### Budget model - Support multiple budget scopes: - provider account/subscription, e.g. Claude OAuth, OpenAI/ChatGPT, OpenRouter, etc. - Hermes profile / Mosaic agent role; - project or mission override where needed. - Store: - budget amount and unit, e.g. messages, tokens, dollars, credits, compute-minutes, provider-specific quota unit; - observed/entered usage; - reset datetime with timezone/offset; - confidence/source: `user-entered`, `provider-detected`, `estimated`, `unknown`; - last detection/check timestamp. - Reset datetime must accept arbitrary ISO timestamps, not only recurrence presets. ### User entry - Provide a safe CLI/config path to set/update budget and reset time manually. - Prefer commands shaped like: - `mosaic budget set --provider <name> --limit <n> --unit <unit> --reset-at <iso-datetime>` - `mosaic budget status` - `mosaic budget reset --provider <name> --reset-at <iso-datetime>` - Validate timezone handling and display both local and UTC where useful. ### Autodetection - Investigate provider-specific detection seams. - Autodetection must be best-effort and source-tagged; do not pretend confidence where provider APIs/OAuth UIs do not expose authoritative reset data. - Include a manual override path for every detected value. - Never scrape or store secrets outside existing Mosaic credential rails. ### Orchestration behavior - Coordinator should consider budget before dispatching workers: - avoid launching high-cost lanes when budget is low and reset is far away; - prefer cheaper model/runtime when acceptable; - delay/schedule non-urgent work until after reset; - spend remaining budget intentionally when reset is near and critical work is ready; - record budget-based routing decisions in mission state. - Budget checks should become a dispatch gate, not an afterthought. ### Evidence and observability - Mission status should report budget state and reset horizon. - Dispatch logs should record why a model/runtime was selected or deferred. - CI/tests should cover boundary cases: reset passed, reset imminent, unknown reset, manual override, and exhausted budget. ## Suggested implementation lanes 1. PRD/ADR: define budget domain model, storage location, config format, and provider detection boundaries. 2. CLI skeleton: `mosaic budget status/set/reset` with local config persistence and tests. 3. Coordinator integration: dispatch gate reads budget state and records decisions. 4. Provider detection spikes: Claude OAuth/OpenAI/OpenRouter/etc. as source-tagged adapters. 5. UX/status: expose budget window in mission status and orchestration summaries. ## Acceptance criteria - A user can manually enter a budget limit and arbitrary reset datetime. - The system stores and displays budget/reset state without losing timezone semantics. - Orchestration dispatch can consume budget state and choose/defer work based on configured policy. - Unknown/autodetected/user-entered states are distinguishable. - Tests cover arbitrary reset datetimes and budget gate decisions. - Documentation explains provider limitations and the manual override workflow. ## Notes This should be implemented as a proper Mosaic Stack feature, not a one-off local convention. It belongs in the orchestration/control-plane roadmap and should align with the AI Guide delivery model: PRD first, decomposed lanes, independent review, green CI, and post-merge verification.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#558
Delete Branch "%!s()"

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?