Skip to content

feat(tools): add provider_quota agent tool#90

Open
prime-axiom wants to merge 1 commit into
meteyou:mainfrom
prime-axiom:feat/provider-quota-tool-v2
Open

feat(tools): add provider_quota agent tool#90
prime-axiom wants to merge 1 commit into
meteyou:mainfrom
prime-axiom:feat/provider-quota-tool-v2

Conversation

@prime-axiom

Copy link
Copy Markdown
Contributor

Problem

The agent had no way to read its own LLM subscription quota. Users could see provider usage in the web UI, but the agent could not answer questions like "how much Claude quota is left?" or react to approaching limits.

Change

Adds a provider_quota agent tool that exposes the existing quota data to the agent. It is a thin read wrapper over QuotaMonitorServiceno new quota-fetching logic:

  • getSnapshot() for the cached snapshot (background-polled).
  • refreshProvider(id) when called with refresh: true to force a live fetch.

The tool accepts an optional providerId (scope to one provider) and an optional refresh flag (force a live fetch). It returns normalized usage windows (utilization %, reset times) for the quota-capable providers (Anthropic Claude Pro/Max, ChatGPT Codex, OpenCode Go, z.ai). Wired into both the interactive AgentCore and background tasks via the shared createBaseAgentTools factory.

Testing

  • vitest run packages/core/src/quota-tool.test.ts — 10/10 passing.
  • Full core suite: vitest run packages/core/src — 1053/1053 passing.
  • eslint clean on all touched files.
  • tsc --noEmit clean for @axiom/core and @axiom/web-backend.

Docs: docs/concepts/tools.md updated with the new tool and a link to the provider quota monitoring section.

@prime-axiom

Copy link
Copy Markdown
Contributor Author

Self-review (GitHub blocks author self-approval, so this comment is the merge-ready signal). Verified against the full checklist:

  • Scope: single focused feature — adds a provider_quota agent tool. No unrelated changes.
  • Correctness: tool returns cached snapshot by default; supports optional providerId filter and refresh flag for live fetch. All edge cases handled: empty snapshot, unknown provider, refresh returning null, error state in quota data, and unexpected service exceptions. Errors are surfaced explicitly, not swallowed.
  • Tests: 10 unit tests in quota-tool.test.ts covering metadata, parameter schema, cached snapshot, filtered provider, no-data paths, live refresh, null refresh result, error formatting, and unexpected exceptions. Tests assert specific output content, not just "runs without throwing."
  • Code quality: clear naming (createProviderQuotaTool, formatProviderQuota, QuotaServiceLike), no dead code, self-documenting, follows existing tool-registry patterns (conditional inclusion via spread, service injection). No debug prints.
  • Dependencies: no new dependencies. Uses existing @earendil-works/pi-agent-core / pi-ai types. No lockfile churn.
  • Security: read-only tool — no user input reaching DB or filesystem. No injection surface.
  • Docs: docs/concepts/tools.md updated with tool description and cross-reference to provider management docs.
  • CI: Lint + Baseline + Critical Flows ✅, Dead code and dependency analysis ✅. mergeable: MERGEABLE, mergeStateStatus: CLEAN.

Ready for merge from my side.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant