plugin improvement proposal

[SPIKESPIGEL404]

Current State vs. Updated Plugin Docs

Your plugin is already well-structured — it has a proper manifest, provider registration, tools, service lifecycle, and
auth. But comparing against the latest docs, there are several areas worth discussing:

1. Missing Runtime Hooks (22 available, you use ~2)

The docs define 22 provider runtime hooks. You currently implement:

• before_model_resolve (routing)
• Basic auth via formatApiKey

You're not leveraging hooks that could significantly improve the experience:

• capabilities — publish provider-family quirks (e.g., which models support vision, function calling)
• augmentModelCatalog — append synthetic model rows so openclaw models list shows BitRouter-routed models
• suppressBuiltInModel — hide upstream models that BitRouter is intercepting (avoids duplicates)
• isBinaryThinking / supportsXHighThinking — expose reasoning UX for models that support it
• buildMissingAuthMessage — replace generic auth errors with BitRouter-specific guidance
• buildAuthDoctorHint — integrate with openclaw plugins doctor
• isCacheTtlEligible — opt into response caching for cost savings
• fetchUsageSnapshot — expose usage/quota data in OpenClaw's billing UI

2. Agent Lifecycle Hooks (before_prompt_build)

The docs describe before_prompt_build which lets plugins inject context into agent sessions. You could use this to:

• Prepend BitRouter status/routing info as system context
• Inject available model aliases so the agent knows what's routable
• Add guardrail policy context when guardrails are enabled

3. Gateway HTTP Routes

The docs show registerHttpRoute for exposing HTTP endpoints. You're using internal RPC methods (bitrouter.metrics,
bitrouter.routing.explain, bitrouter.wallet), but you could also expose proper HTTP routes for:

• A dashboard endpoint (/bitrouter/dashboard)
• Webhook receivers for upstream provider notifications
• A metrics endpoint compatible with Prometheus/Grafana

4. providerAuthChoices & providerAuthEnvVars in Manifest

The docs require these in openclaw.plugin.json. Are you declaring them? This would improve the auth wizard UX — OpenClaw
can show proper labels and CLI metadata for each auth method.

5. Plugin Slots

The docs introduce memory and contextEngine slots. If BitRouter ever wants to act as a context engine (e.g., routing
context to different backends), this is a future extensibility path.

6. openclaw.setupEntry for Lightweight Loading

The docs mention an optional setupEntry in package.json for fast setup-only loading. Your plugin currently loads everything
on activation — a separate setup entry could speed up openclaw plugins install and first-run without loading the full
daemon machinery.

7. Discovery Phase (discovery.run)

The docs describe an implicit discovery phase where plugins can auto-detect configuration. Your auto-detect.ts does this
internally, but wiring it into the formal discovery.run(ctx) hook would make it participate in OpenClaw's standard
discovery flow.

8. runNonInteractive Auth

The docs distinguish interactive vs non-interactive auth. Your BYOK wizard is interactive, but adding runNonInteractive
would support CI/CD and headless environments where users set env vars and expect BitRouter to just work.