akiiwa-games/AgentCompass / skills/agent-compass
agent-compass
UnverifiedMulti-agent task router and subscription quota scheduler. Choose owner, model and effort, outbound authorization, advisor use, and continuation for delegated work. Reads local usage and effective account policy, profiles the task with the configured System-One scorer, then allocates a compatible worker. Use for independent worker or advisor work; ordinary local execution needs no routing.
references/provider-discovery.md
View on GitHub# Local provider discovery contract
The router rereads local sign-ins, Paseo launcher bindings, Magpie and CC Switch
before allocation and at the prepared dispatch's launch check. `agentcompass providers` also refreshes the inventory at
`~/.agent-compass/provider-inventory.json`. Discovery performs no network requests
and does not read the VPS connection configuration.
## Availability decision
- Failure: a signed-out, disabled or removed account can otherwise keep receiving
work because `accounts.json` still says `verified`. Product display names and
CC Switch's selected profile can differ from the account actually launched.
- Action: exclude the affected account/launcher from new work. Listing, diagnosis,
repairs, unrelated accounts and already running workers continue.
- Evidence: effective launcher credentials, stable account identity (or exact
credential binding where no stable identity exists), explicit launcher disable,
Magpie provider/key `off`, removed built-in subscription `hidden`, and login
`paused`/`hidden`/`lapsed`/backup `on`, and
CC Switch's persisted `provider_health.is_healthy`, or a matching local collector
credential's explicit authentication refusal. A confirmed removal from a
successfully read product source pauses its previously bound account too.
- Recovery: credentials restored, product status healthy/enabled, or the deleted
entry restored becomes usable on the next allocation. Changing to a different
account does not inherit the previous account's pause. No `verified` edit or
confirmation phrase is needed. Explicit host and disabled-model policy still wins.
- Degradation: malformed/missing product files do not imply account deletion or
block unrelated native sign-ins. An already confirmed pause survives a temporary
source read failure. A removed-entry marker persists only for the same account.
Missing native credentials remain unavailable. Unknown quota stays unknown.
Magpie's `on` controls backup participation; the current native account need not
have it set. A stale Claude `lapsed` credential does not invalidate a refreshed
credential for the same account; explicit account pause still does. CC Switch's
`is_current` and `in_failover_queue` are not generic enable/disable flags.
Magpie's empty model picks restore defaults unless `noModels` explicitly selects
none. Removing only a built-in subscription's custom picks also restores defaults.
## Read and storage boundary
Read Magpie's local `providers.json` and `logins.json`, and CC Switch's SQLite
provider/health tables with `mode=ro` and bounded queries. Resolve default,
portable and product-recorded relocated data directories. Never switch product
selection, execute stored usage scripts, refresh OAuth, copy credentials or call a
model. Secret values only participate in in-memory binding; the published snapshot
contains metadata and one-way fingerprints, not keys, tokens or raw settings.
Saved profiles attach to an existing launcher by actual identity or endpoint/key.
Additional enabled Claude/Codex Paseo launchers inherit the existing family policy
and permission mode. A saved profile without a launcher is visible as `saved`;
it is not an independent concurrent worker account. Explicit launchers advertising
models can be loaded without an account template. Model scores use exact calibrated
rows first, then normalized names, the same-series row's scores (series conversion,
no shrink), and a conservative generic baseline only for a name with no series. These
are estimates, not benchmark measurements.
Duplicate launchers share one subscription quota owner.
Account IDs do not determine provider family, credential home or quota reserves.
Discovery supplies family and home; an explicit account `family` can describe an
offline configuration. Worker credentials and session-limit logs use the discovered
home, including custom paths. Per-window `launch_min_remaining_pct` expresses an account's reserve; no
additional reserve is inferred from a secondary-account name or plan label.
Quota sharing between independent integrations is explicit: top-level
`quota_sources` maps an account to its quota owner, or an account sets `quota_source`.
The shipped template binds the Grok Bot to Grok (`"quota_sources": {"grok-bot": "grok"}`),
the same meter the usage collector reads for it, so the Bot routes as a subscription
account. An override can remove the binding; other products stay independent unless bound.
## Automatic admission of newly discovered accounts
`known_accounts` in `~/.agent-compass/host-policy.json` records which accounts have
already been seen alongside `allowed_accounts`. New accounts discovered afterward
are admitted only once their native discovery is ready, their account has a
non-disabled dispatch contract and no known expired subscription. An unready or
unregistered newcomer is not marked seen; signing in/registering it later can
admit it. Unknown names supplied in a request are never admission evidence.
The same `known_accounts` field records user intent: a name that is known but no
longer allowed remains disabled. The existing account-admission panel preserves
the marker when saving checkboxes, including exclusions for currently absent
accounts. Native disabled/removed/rejected/expired states still block dispatch;
automatic admission does not clear them. Refreshes are idempotent and use the
existing file lock/atomic writer. Missing evidence or a failed policy write does
not grant permission; other discovery results remain visible for diagnosis.
Saving settings records only changes from the displayed admission state, not
every displayed account: an untouched unready newcomer remains eligible for
later admission, and concurrent admissions survive unrelated checkbox changes.
`agentcompass providers` and normal account loading refresh this registration.
Account admission preserves each provider's capability and scoring policy;
it does not invent model benchmarks or quota capacity.
## Grok and advertised model defaults (2026-10-27)
`grok-bot` is a separate remote text runner and automatic routing candidate. It appears in
`agentcompass providers`; a configured exact Bot ID plus the pinned local CLI
and Node makes its launcher available. This is setup availability, not proof of
current login: upstream performs a live read-only check before send. Billing and
underlying model identity remain unknown. It has no cited category scores, so it is
dispatched only when named.
Quota sharing is an explicit binding (shipped for Grok); the bound
owner supplies observation freshness, reset and capacity policy. Execution
enablement stays independent, and missing/stale quota never proves unlimited
capacity. See
[setup, receipts and roll commands](grok-bot.md).
Grok Build owns its own subscription meter and configured bundles. Another runner
uses that meter only through an explicit quota-source binding. Local evidence is
an enabled Paseo Grok definition, a Grok CLI/config directory, or an active CC
Switch Grok/GrokBuild profile. Cache metadata alone does not prove a client is
installed. An explicit Paseo disable or bound CC Switch unhealthy state still
excludes it. The official active GrokBuild profile binds to this same account.
Reported Grok window IDs keep quota accounting enabled (weekly window, provisional
1% per worker-hour when no capacity prior exists). Without reported windows Grok
uses `unmetered`, without `unlimited`: no missing-snapshot exclusion and no free
usage bonus. An existing user expiry or disabled bundle still applies.
Dispatch adapter contract change: permit the locally ready Grok/ACP launcher
families to form a Paseo launch request. The previous family list rejected the
configured Grok ACP command before any launch. Missing/unready unfamiliar launchers
remain rejected; recovery is restoring the configured launcher. This changes only
request preparation; existing account, quota and launch authorization checks still
apply. Grok/ACP receives no invented permission mode. Tests pair ready and disabled
launchers, exercise reported/missing quota, and verify no unlimited bonus.
Without a usable Paseo launcher, `roll` runs a ready Grok provider through its own
Grok Build CLI (`dispatch_mode: cli`): `grok --always-approve -m <model>
[--reasoning-effort <effort>] --cwd <cwd> --prompt-file <run>/brief.md`, with stdin closed
(headless Grok ignores stdin) and the reply on stdout; exit `0` ok, `1` error. The routed
model and effort are passed unchanged; the CLI has no fast mode (the registry already
rejects `fast` for non-fast-capable models). The executable is the provider's configured
Paseo command (its sibling `grok` when that names `agent`), else `grok` on PATH, else
`~/.grok/bin/grok` (the installer does not edit PATH), the same binary discovery counts.
The provider's Paseo `env` is applied; a configured command that is missing or is not a
Grok executable (bare names resolve through PATH) fails the launch (native handoff)
instead of picking another install. `grok-bot` is separate.
Normalization strips provider prefixes, dated/version tags and known suffixes,
then tries longest known prefixes and family defaults; the result says which of these
matched ([rules](router-internals.md#model-names-efforts-and-pins)). Scores never replace the
advertised launch ID. A model ID with no scores stays out of automatic routing until public data has them; naming it still dispatches it.
Saved CC Switch profiles remain metadata until bound to a real launcher; discovery
never switches the active product account or contacts a gateway.
Plan labels come from current credentials or a matching local collector snapshot; for
Codex the snapshot's usage API `plan_type` outranks the id_token claim, and a
disagreement is a warning. Known plans reuse policy capacity estimates; unknown plans
are priced at the family's smallest paid plan with a warning. OAuth expiry and next
billing dates do not prove subscription cancellation. Remote closure that has not yet
reached the local product/collector cannot be detected by this read-only local scan;
once a reading or a launch reports it the account is `plan_inactive`
(`scripts/account_state.py`), and a reading that keeps failing makes it `usage_failing`.
## Verification
`test_provider_inventory.py` uses isolated homes and SQLite fixtures, without
starting agents. Each scenario exercises the decision and its recovery or isolation:
- Actual identity vs stale CC Switch selection, read-only files and secret-free output.
- New registered launcher, sign-out, explicit disable and restored credentials.
- Magpie account pause/refusal/hide, backup participation and provider/key disable.
- CC Switch unhealthy/healthy transitions and confirmed profile removal/restoration.
- Collector authentication refusal vs ordinary outage, matching credential and recovery.
- Persisted deletion markers, changed identity and unreadable source after a pause.
- Default/portable/relocated product paths and absence of network/VPS access.
- Claude token rotation preserves account pause but supersedes old credential failure.
- Duplicate quota ownership (including a disabled alias), changed usage binding and unknown plan estimates.
- Corrupt sources leave unrelated sign-ins available; host/model policy still wins.
- Effective secure-storage home and API settings identify the account actually used.
Allocation, dispatch and host-policy tests isolate discovery from the
machine's live subscriptions. Obsolete documentation of direct OAuth probes and
gateway discovery has been removed: collection belongs to the existing backend.
Explicit model overrides cannot bypass account pause, and a prepared dispatch
rechecks availability immediately before claiming its launch.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |