Skip to content

akiiwa-games/AgentCompass / skills/agent-compass

agent-compass

Flagged

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.

FileKindSize
SKILL.mdskill md5.5 KB
agents/openai.yamlconfig427 B
calibration/README.mdmarkdown55.2 KB
calibration/arena_capture.pyscript14.0 KB
calibration/community.pyscript25.2 KB
calibration/five_axis.pyscript196.4 KB
calibration/measurements.pyscript68.4 KB
calibration/refresh.pyscript48.6 KB
calibration/series.pyscript10.2 KB
calibration/sources.pyscript24.1 KB
calibration/tiers.pyscript14.6 KB
grok-bot/.gitignoreother47 B
grok-bot/dependency_patch.pyscript4.5 KB
grok-bot/install_cli.pyscript3.6 KB
grok-bot/test-recovery.mjsscript8.6 KB
grok-bot/test_install_cli.pyscript4.1 KB
grok-bot/upstream.jsonconfig3.4 KB
references/accounts.jsonconfig155.9 KB
references/classifier-cases.jsonconfig21.5 KB
references/dispatch-lifecycle.mdmarkdown28.9 KB
references/dispatch-rules.mdmarkdown11.3 KB
references/effort-matching.mdmarkdown5.1 KB
references/fast-modes.mdmarkdown3.5 KB
references/five-axis-scores.jsonconfig3.1 MB
references/gemini-decisions-api.mdmarkdown2.9 KB
references/grok-bot.mdmarkdown13.0 KB
references/herdr.mdmarkdown5.1 KB
references/jev-api.mdmarkdown1.6 KB
references/level-3-conversion.jsonconfig2.4 KB
references/model-capabilities.jsonconfig3.6 KB
references/model-capabilities.mdmarkdown14.6 KB
references/parent-address-gate.mdmarkdown10.1 KB
references/plan-templates.jsonconfig13.2 KB
references/provider-discovery.mdmarkdown11.5 KB
references/provider-usage.mdmarkdown4.1 KB
references/public-data.jsonconfig816 B
references/public-measurements.jsonconfig1.3 MB
references/roll-reference.mdmarkdown26.7 KB
references/router-internals.mdmarkdown93.7 KB
references/task-classifier.mdmarkdown6.1 KB
references/user-scores.jsonconfig6.8 KB
references/work-kinds.mdmarkdown4.7 KB
references/worker-communication.mdmarkdown2.1 KB
scripts/account_fleet.pyscript32.9 KB
scripts/account_state.pyscript22.2 KB
scripts/accounts_override.pyscript14.8 KB
scripts/allocator.pyscript19.8 KB
scripts/antigravity_plan.pyscript18.7 KB
scripts/antigravity_telemetry.pyscript5.1 KB
scripts/auto_bundles.pyscript31.3 KB
scripts/axis_scores.pyscript40.3 KB
scripts/caller_input.pyscript3.0 KB
scripts/candidate_eval.pyscript54.0 KB
scripts/candidate_ranking.pyscript9.5 KB
scripts/capability_catalog.pyscript8.0 KB
scripts/check_router_contract.pyscript2.8 KB
scripts/conftest.pyscript2.5 KB
scripts/cwd_policy.pyscript1.5 KB
scripts/data_age.pyscript1.5 KB
scripts/decision_ledger.pyscript18.9 KB
scripts/demo_plan.pyscript6.3 KB
scripts/dispatch_fallback.pyscript40.3 KB
scripts/dispatch_flow.pyscript58.7 KB
scripts/dispatch_ground_truth.pyscript43.5 KB
scripts/dispatch_registry.pyscript113.7 KB
scripts/entry.pyscript1.7 KB
scripts/env_vars.pyscript580 B
scripts/fast_modes.pyscript2.5 KB
scripts/fixtures/grok-api-responses.jsonconfig907 B
scripts/fixtures/reference-accounts.jsonconfig26.9 KB
scripts/grok_bot_paths.pyscript1005 B
scripts/host_herdr.pyscript16.8 KB
scripts/host_placement.pyscript9.4 KB
scripts/host_policy.pyscript10.1 KB
scripts/launch_failures.pyscript5.9 KB
scripts/launch_values.pyscript12.3 KB
scripts/ledger_snapshot.pyscript11.1 KB
scripts/live_models.pyscript21.1 KB
scripts/model_latch.pyscript7.6 KB
scripts/model_resolution.pyscript18.0 KB
scripts/override_store.pyscript2.2 KB
scripts/plan_state_residue.pyscript5.0 KB
scripts/provider_inventory.pyscript128.2 KB
scripts/provider_retry.pyscript34.6 KB
scripts/public_data.pyscript59.2 KB
scripts/quota_economy.pyscript38.0 KB
scripts/quota_exhaustion.pyscript5.9 KB
scripts/quota_overrides.pyscript25.6 KB
scripts/quota_pools.pyscript29.8 KB
scripts/reference_provenance.pyscript32.3 KB
scripts/released_names.pyscript3.8 KB
scripts/roll.pyscript106.3 KB
scripts/route_judge.pyscript83.4 KB
scripts/route_simulation.pyscript26.3 KB
scripts/router_test_support.pyscript6.7 KB
scripts/run_grok_bot.pyscript18.8 KB
scripts/scorer_client.pyscript55.2 KB
scripts/stage_help.pyscript5.8 KB
scripts/state_upgrade.pyscript24.0 KB
scripts/subscription_cli.pyscript3.6 KB
scripts/task_intake.pyscript33.6 KB
scripts/test_account_identity.pyscript7.1 KB
scripts/test_account_state.pyscript63.3 KB
scripts/test_accounts_override.pyscript30.1 KB
scripts/test_allocator.pyscript94.2 KB
scripts/test_antigravity_plan.pyscript13.2 KB
scripts/test_applicable_quota.pyscript9.1 KB
scripts/test_auto_bundles.pyscript10.8 KB
scripts/test_billing_routing_policy.pyscript9.9 KB
scripts/test_cadence_count.pyscript32.2 KB
scripts/test_calibration_units.pyscript27.0 KB
scripts/test_capability_catalog.pyscript5.0 KB
scripts/test_decision_ledger.pyscript8.5 KB
scripts/test_demo_plan.pyscript3.4 KB
scripts/test_derived_state.pyscript21.6 KB
scripts/test_dispatch.pyscript322.3 KB
scripts/test_dispatch_answers.pyscript14.8 KB
scripts/test_dispatch_fallback.pyscript53.2 KB
scripts/test_entry.pyscript1.6 KB
scripts/test_fast_modes.pyscript9.9 KB
scripts/test_five_axis.pyscript290.1 KB
scripts/test_five_axis_economy.pyscript105.0 KB
scripts/test_fleet_parity.pyscript15.6 KB
scripts/test_grok_bot.pyscript47.7 KB
scripts/test_ground_truth_recording.pyscript68.8 KB
scripts/test_herdr.pyscript14.1 KB
scripts/test_host_policy.pyscript24.6 KB
scripts/test_launch_values.pyscript8.0 KB
scripts/test_metered_usd.pyscript60.4 KB
scripts/test_model_resolution.pyscript9.2 KB
scripts/test_named_route_facts.pyscript28.6 KB
scripts/test_native_hosts.pyscript6.0 KB
scripts/test_new_user_fleet.pyscript3.3 KB
scripts/test_no_hardcode_classification.pyscript75.1 KB
scripts/test_no_legacy_scoring.pyscript6.5 KB
scripts/test_override_store.pyscript2.3 KB
scripts/test_plan_says_why.pyscript44.9 KB
scripts/test_provider_inventory.pyscript83.2 KB
scripts/test_provider_names.pyscript126.0 KB
scripts/test_provider_pools.pyscript14.2 KB
scripts/test_public_data.pyscript93.5 KB
scripts/test_quota_exhaustion.pyscript5.6 KB
scripts/test_rate_limit_windows.pyscript6.3 KB
scripts/test_record_says_why.pyscript26.5 KB
scripts/test_reference_provenance.pyscript16.7 KB
scripts/test_refresh_entry.pyscript110.7 KB
scripts/test_released_names.pyscript4.1 KB
scripts/test_reset_priority.pyscript4.8 KB
scripts/test_roll_answers.pyscript44.7 KB
scripts/test_roll_notifications.pyscript10.4 KB
scripts/test_route_judge.pyscript99.8 KB
scripts/test_route_simulation.pyscript7.0 KB
scripts/test_routing_parity.pyscript32.3 KB
scripts/test_routing_review.pyscript25.1 KB
scripts/test_setup_discovery_parity.pyscript9.5 KB
scripts/test_stage_help.pyscript2.0 KB
scripts/test_state_upgrade.pyscript13.8 KB
scripts/test_turn_refusal.pyscript16.7 KB
scripts/test_usage_cache.pyscript4.9 KB
scripts/test_usage_collector.pyscript21.4 KB
scripts/test_usage_core_claude_accounts.pyscript1.8 KB
scripts/test_usage_core_grok_cli_billing.pyscript15.6 KB
scripts/test_usage_core_magpie.pyscript5.4 KB
scripts/test_usage_core_magpie_pool.pyscript10.8 KB
scripts/test_usage_core_safety.pyscript24.4 KB
scripts/test_user_scores.pyscript102.3 KB
scripts/test_venice_usage.pyscript1.3 KB
scripts/test_window_scope.pyscript5.5 KB
scripts/turn_refusal.pyscript10.7 KB
scripts/usage_cache.pyscript4.7 KB
scripts/usage_collector.pyscript7.4 KB
scripts/usage_core.pyscript142.0 KB
scripts/usage_magpie.pyscript10.6 KB
scripts/usage_reading.pyscript17.1 KB
scripts/user_scores.pyscript72.8 KB
scripts/venice_usage.pyscript2.6 KB
scripts/window_scope.pyscript3.2 KB
scripts/worker_context.pyscript8.9 KB
scripts/worker_sessions.pyscript10.9 KB

scripts/live_models.py

View on GitHub
"""Live Paseo provider model lists cached briefly before ranking and launch.

Contract:
- Before ranking (and in provider discovery), candidate Paseo providers are queried through the Paseo dispatch bridge
  (`operation: 'provider_models'`, which calls `client.listProviderModels(provider)`).
- Readings are cached in `<state_dir>/paseo-live-models.json` (and in memory) with a 60-second TTL (`TTL_SECONDS = 60`).
  Why 60s: a single `roll` runs `plan` and `prepare` (and batch `roll` runs multiple briefs back-to-back), so 60s avoids
  repeating bridge calls within a roll while still picking up upstream provider catalog changes within one minute.
- Model-id matching is strictly structural: exact model `id` and Paseo `aliases` (with structural `<provider>/<id>`
  prefix normalization), never substring or keyword rules.
- When a provider's live list is readable (`ok: True`) and omits a bundle's launch model, the bundle is excluded with
  `"provider no longer offers <model>"` and surfaced in `plan`/`roll` warnings and tray account cards.
- When a provider's live list cannot be read (`ok: False`, e.g. Paseo down or provider disabled), no bundle is excluded
  on that basis; `"model list unavailable"` is surfaced in warnings and tray account cards, falling back to existing
  routing and the `model_latch` / `provider_retry` holds.
- Which providers are Paseo's is Paseo's own provider snapshot, not a name list here: every candidate bundle's provider
  is asked, and one the snapshot does not list comes back `status: unknown_provider` (e.g. a LiteLLM proxy account),
  which gives neither a warning nor an exclusion.
- Only `roll`/`plan` (ranking) refresh the cache. The tray only reads it and refreshes it off the Tk thread.
- A refresh merges into the file under its lock; `invalidate()` stamps the provider so a refresh whose fetch began
  before the invalidation does not write the evicted list back.
"""
from __future__ import annotations

import copy
from datetime import datetime, timedelta, timezone
import json
import os
from pathlib import Path
import override_store

FILE = 'paseo-live-models.json'
# 60s TTL: covers `plan` -> `prepare` -> `claim` and batch rolls without adding bridge latency per step, while
# refreshing within a minute when a provider's live catalog changes.
TTL_SECONDS = 60
# A bridge round trip takes ~0.5 s here; a hung Paseo must not hold a roll long, and an unread list never excludes.
FETCH_TIMEOUT_SECONDS = 3
# The bridge's status for a provider Paseo's snapshot does not list (not a Paseo provider): no warning, no exclusion.
UNKNOWN_PROVIDER = 'unknown_provider'

_MEM_CACHE: dict[str, dict] = {}


def ttl_seconds() -> int:
    raw = os.environ.get('AGENTCOMPASS_LIVE_MODELS_TTL_SECONDS', '').strip()
    if raw:
        try:
            return max(1, int(raw))
        except ValueError:
            pass
    return TTL_SECONDS


def state_dir() -> Path:
    return Path(os.environ.get('ROUTER_STATE_DIR') or Path.home() / '.agent-compass')


def store_path(base_dir: Path | None = None) -> Path:
    override = os.environ.get('AGENTCOMPASS_LIVE_MODELS', '').strip()
    if override and override.lower() not in ('off', '0', 'false', 'on', '1', 'true'):
        return Path(override)
    return (base_dir or state_dir()) / FILE


def _parse_time(value) -> datetime | None:
    if not value:
        return None
    if isinstance(value, datetime):
        return value if value.tzinfo else value.replace(tzinfo=timezone.utc)
    try:
        return datetime.fromisoformat(str(value).replace('Z', '+00:00'))
    except (TypeError, ValueError):
        return None


def launch_model(bundle: dict | None) -> str:
    if not isinstance(bundle, dict):
        return ''
    val = bundle.get('launch_model') or bundle.get('model') or ''
    return val.strip() if isinstance(val, str) else ''


def bundle_provider(bundle: dict | None, account: str | None = None) -> str:
    if not isinstance(bundle, dict):
        return (account or '').strip()
    val = bundle.get('provider') or bundle.get('account') or account or ''
    return val.strip() if isinstance(val, str) else ''


def is_paseo_bundle(bundle: dict | None, account: str | None = None, spec: dict | None = None) -> bool:
    """A bundle whose provider is asked. Whether Paseo knows that provider is the bridge's answer, not decided here."""
    return isinstance(bundle, dict) and bool(bundle_provider(bundle, account))


def is_unknown_provider(entry: dict | None) -> bool:
    return isinstance(entry, dict) and entry.get('status') == UNKNOWN_PROVIDER


def candidate_providers(accounts: dict | None, allowed=None, named=()) -> list[str]:
    """Sorted Paseo provider ids referenced by active candidate accounts. An account in `named` (a named route or an
    explicit resume names it) counts its unchecked bundles too: whether the provider still offers a model is a fact
    the checkbox does not change."""
    if not isinstance(accounts, dict):
        return []
    acc_map = accounts.get('accounts')
    if not isinstance(acc_map, dict):
        return []
    found: set[str] = set()
    for acct, spec in acc_map.items():
        if not isinstance(spec, dict) or spec.get('enabled') is False:
            continue
        if allowed is not None and not allowed(acct):
            continue
        if spec.get('discovery_status') in ('not_installed', 'missing_credentials', 'disabled'):
            continue
        if spec.get('verified') is False:
            continue
        bundles = spec.get('bundles')
        if not isinstance(bundles, dict):
            continue
        for bundle in bundles.values():
            if not isinstance(bundle, dict) or not (_bundle_enabled(bundle) or acct in named):
                continue
            if bundle.get('discovery_unavailable'):
                continue
            if not is_paseo_bundle(bundle, acct, spec):
                continue
            prov = bundle_provider(bundle, acct)
            if prov:
                found.add(prov)
    return sorted(found)


def _structural_ids(provider: str, value) -> tuple[str, ...]:
    if not isinstance(value, str):
        return ()
    item = value.strip()
    if not item:
        return ()
    prov = provider.strip() if isinstance(provider, str) else ''
    prefix = f'{prov}/' if prov else ''
    if prefix and item.startswith(prefix):
        bare = item[len(prefix):].strip()
        return (item, bare) if bare else (item,)
    if prefix:
        return (item, f'{prefix}{item}')
    return (item,)


def offered_model_ids(provider: str, provider_entry: dict | None) -> frozenset[str]:
    """Structural set of exact `id` and Paseo `aliases` values offered by `provider_entry`."""
    if not isinstance(provider_entry, dict) or provider_entry.get('ok') is not True:
        return frozenset()
    models = provider_entry.get('models')
    if not isinstance(models, list):
        return frozenset()
    offered: set[str] = set()
    for item in models:
        if isinstance(item, str):
            offered.update(_structural_ids(provider, item))
        elif isinstance(item, dict):
            offered.update(_structural_ids(provider, item.get('id')))
            for alias_id in item.get('aliases') or ():
                offered.update(_structural_ids(provider, alias_id))
    return frozenset(offered)


def offers_model(provider: str, model_id: str, provider_entry: dict | None) -> bool:
    """True iff `model_id` structurally matches an exact `id` or Paseo `aliases` entry."""
    candidates = set(_structural_ids(provider, model_id))
    if not candidates:
        return False
    return bool(candidates & offered_model_ids(provider, provider_entry))


def _default_fetch_from_paseo(providers: list[str], cwd: str | None = None, timeout: int = FETCH_TIMEOUT_SECONDS) -> dict:
    import dispatch_flow
    payload: dict = {'operation': 'provider_models', 'providers': list(providers), 'timeout_seconds': timeout}
    if cwd:
        payload['cwd'] = cwd
    return dispatch_flow.host_call(payload)


fetch_from_paseo = _default_fetch_from_paseo


def enabled() -> bool:
    if fetch_from_paseo is not _default_fetch_from_paseo:
        return True
    flag = os.environ.get('AGENTCOMPASS_LIVE_MODELS', '').strip().lower()
    if flag in ('off', '0', 'false'):
        return False
    return True


def _bundle_enabled(bundle: dict) -> bool:
    """A bundle the user unchecked is `disabled: True` at runtime (`enabled: False` in raw specs); a
    disabled-by-default bundle still launches when named, so it keeps its live check."""
    if bundle.get('enabled') is False:
        return False
    return not (bundle.get('disabled') and not bundle.get('disabled_by_default'))


def _read_store(path: Path) -> dict:
    mem = _MEM_CACHE.get(str(path))
    try:
        stat = path.stat()
    except OSError:
        _MEM_CACHE.pop(str(path), None)
        return {'providers': {}}
    if mem and mem.get('_mtime_ns') == stat.st_mtime_ns:
        return copy.deepcopy(mem['doc'])
    try:
        raw = json.loads(path.read_text(encoding='utf-8-sig'))
    except (OSError, ValueError):
        return {'providers': {}}
    if not isinstance(raw, dict) or not isinstance(raw.get('providers'), dict):
        return {'providers': {}}
    _MEM_CACHE[str(path)] = {'_mtime_ns': stat.st_mtime_ns, 'doc': copy.deepcopy(raw)}
    return raw


def _write_store(path: Path, doc: dict) -> None:
    """Atomic replacement; the caller holds `override_store.locked(path)` across its read-modify-write."""
    path.parent.mkdir(parents=True, exist_ok=True)
    override_store.write(path, doc)
    try:
        stat = path.stat()
        _MEM_CACHE[str(path)] = {'_mtime_ns': stat.st_mtime_ns, 'doc': copy.deepcopy(doc)}
    except OSError:
        _MEM_CACHE.pop(str(path), None)


def _entry_fresh(entry: dict | None, now: datetime, ttl: int) -> bool:
    if not isinstance(entry, dict) or 'ok' not in entry:
        return False
    fetched = _parse_time(entry.get('fetched_at'))
    if fetched is None:
        return False
    return (now - fetched) < timedelta(seconds=ttl)


def _normalize_entry(raw_entry: dict | None, fetched_at_iso: str, fallback_error: str = 'model_list_unavailable') -> dict:
    if not isinstance(raw_entry, dict):
        return {
            'ok': False,
            'status': 'unavailable',
            'error': fallback_error,
            'fetched_at': fetched_at_iso,
            'models': [],
        }
    if raw_entry.get('ok') is True and isinstance(raw_entry.get('models'), list):
        models = []
        for item in raw_entry['models']:
            if isinstance(item, str) and item.strip():
                models.append({'id': item.strip()})
            elif isinstance(item, dict) and isinstance(item.get('id'), str) and item['id'].strip():
                normalized = {'id': item['id'].strip()}
                aliases = [a.strip() for a in (item.get('aliases') or ()) if isinstance(a, str) and a.strip()]
                if aliases:
                    normalized['aliases'] = aliases
                if isinstance(item.get('label'), str) and item['label'].strip():
                    normalized['label'] = item['label'].strip()
                models.append(normalized)
        return {
            'ok': True,
            'status': str(raw_entry.get('status') or 'ready'),
            'fetched_at': str(raw_entry.get('fetched_at') or fetched_at_iso),
            'models': models,
        }
    return {
        'ok': False,
        'status': str(raw_entry.get('status') or 'unavailable'),
        'error': str(raw_entry.get('error') or fallback_error),
        'fetched_at': str(raw_entry.get('fetched_at') or fetched_at_iso),
        'models': [],
    }


def read_cached(*, base_dir: Path | None = None, now: datetime | None = None, allow_stale: bool = False) -> dict:
    """Read cached live-model entries without querying Paseo."""
    path = store_path(base_dir)
    if not path.exists():
        return {'providers': {}}
    doc = _read_store(path)
    if allow_stale:
        return doc
    now = now or datetime.now(timezone.utc)
    ttl = ttl_seconds()
    fresh = {
        prov: entry
        for prov, entry in (doc.get('providers') or {}).items()
        if _entry_fresh(entry, now, ttl)
    }
    return {'updated_at': doc.get('updated_at'), 'ttl_seconds': ttl, 'providers': fresh}


def load_or_refresh(
    providers: list[str] | None = None,
    *,
    accounts: dict | None = None,
    allowed=None,
    named=(),
    base_dir: Path | None = None,
    now: datetime | None = None,
    force: bool = False,
    fetch=None,
) -> dict:
    """Return live model lists for `providers` (or candidate providers in `accounts`), refreshing stale entries."""
    if not enabled() and fetch is None:
        return {'providers': {}}
    now = now or datetime.now(timezone.utc)
    ttl = ttl_seconds()
    path = store_path(base_dir)
    doc = _read_store(path)
    stored_providers = doc.get('providers') if isinstance(doc.get('providers'), dict) else {}
    target_providers = list(dict.fromkeys(
        providers if providers is not None else candidate_providers(accounts, allowed=allowed, named=named)
    ))
    if not target_providers:
        return {'updated_at': doc.get('updated_at'), 'ttl_seconds': ttl, 'providers': dict(stored_providers)}
    missing = [
        prov for prov in target_providers
        if force or not _entry_fresh(stored_providers.get(prov), now, ttl)
    ]
    if not missing:
        return {
            'updated_at': doc.get('updated_at'),
            'ttl_seconds': ttl,
            'providers': {prov: stored_providers[prov] for prov in target_providers if prov in stored_providers},
        }
    fetcher = fetch or fetch_from_paseo
    ts = now.isoformat()
    started = datetime.now(timezone.utc)  # wall clock, as invalidate() stamps it
    try:
        reply = fetcher(missing)
    except Exception:
        reply = {'ok': False, 'error': 'host_connection_failed'}
    fetched: dict[str, dict] = {}
    if isinstance(reply, dict) and reply.get('ok') is True and isinstance(reply.get('providers'), dict):
        raw_map = reply['providers']
        for prov in missing:
            raw_entry = raw_map.get(prov)
            if isinstance(raw_entry, dict):
                raw_entry = {**raw_entry, 'fetched_at': ts}
            fetched[prov] = _normalize_entry(raw_entry, ts)
    else:
        err_code = str((reply or {}).get('error') or 'model_list_unavailable') if isinstance(reply, dict) else 'model_list_unavailable'
        for prov in missing:
            fetched[prov] = _normalize_entry(None, ts, fallback_error=err_code)
    # The fetch ran outside the lock (it can take seconds). Re-read under the lock and merge only what this call read,
    # so a concurrent refresh of other providers survives, and leave out a provider invalidated after this fetch began.
    merged = {**stored_providers, **fetched}
    try:
        with override_store.locked(path):
            _MEM_CACHE.pop(str(path), None)
            current = _read_store(path)
            on_disk = dict(current['providers'])
            invalidated = current.get('invalidated') if isinstance(current.get('invalidated'), dict) else {}
            for prov, entry in fetched.items():
                stamps = [t for t in (_parse_time(invalidated.get(prov)), _parse_time(invalidated.get('*'))) if t is not None]
                evicted = max(stamps) if stamps else None
                if evicted is None or evicted <= started:
                    on_disk[prov] = entry
            out_doc = {'updated_at': ts, 'ttl_seconds': ttl, 'providers': on_disk}
            if invalidated:
                out_doc['invalidated'] = invalidated
            _write_store(path, out_doc)
        # This call still answers with what it read; the file keeps the newer state.
        merged = {**on_disk, **fetched}
    except (OSError, TimeoutError):
        pass
    return {
        'updated_at': ts,
        'ttl_seconds': ttl,
        'providers': {prov: merged[prov] for prov in target_providers if prov in merged},
    }


def invalidate(provider: str | None = None, *, base_dir: Path | None = None) -> None:
    """Evict `provider` (or all providers when None) from the live-models cache."""
    path = store_path(base_dir)
    _MEM_CACHE.pop(str(path), None)
    try:
        with override_store.locked(path):
            _MEM_CACHE.pop(str(path), None)
            doc = _read_store(path)
            providers = doc['providers']
            invalidated = doc.get('invalidated') if isinstance(doc.get('invalidated'), dict) else {}
            stamp = datetime.now(timezone.utc).isoformat()
            # Stamp even when nothing is cached yet, so a refresh already in flight cannot write the evicted list back.
            for prov in (list(providers) + ['*'] if provider is None else [provider]):
                providers.pop(prov, None)
                invalidated[prov] = stamp
            doc['invalidated'] = invalidated
            _write_store(path, doc)
    except (OSError, TimeoutError):
        pass


def reason(bundle: dict | None, live_doc: dict | None, account: str | None = None, spec: dict | None = None) -> str | None:
    """Exclusion text if the bundle's provider live list was read and omits its launch model, else None."""
    if not isinstance(bundle, dict) or not isinstance(live_doc, dict):
        return None
    if not is_paseo_bundle(bundle, account, spec):
        return None
    providers = live_doc.get('providers')
    if not isinstance(providers, dict):
        return None
    prov = bundle_provider(bundle, account)
    entry = providers.get(prov)
    if not isinstance(entry, dict) or entry.get('ok') is not True:
        # Unreadable live list (Paseo down, provider disabled): never exclude on that basis.
        return None
    mod = launch_model(bundle)
    if mod and not offers_model(prov, mod, entry):
        return f'provider no longer offers {mod}'
    return None


def unavailable_detail(entry: dict | None) -> str | None:
    """Human-readable unavailability text when a provider's live model list could not be read."""
    if not isinstance(entry, dict) or entry.get('ok') is not False or is_unknown_provider(entry):
        return None
    err_code = str(entry.get('error') or entry.get('status') or 'unavailable').strip()
    if err_code and err_code not in ('model_list_unavailable', 'unavailable'):
        return f'model list unavailable ({err_code})'
    return 'model list unavailable'


def warnings(live_doc: dict | None, accounts: dict | None = None, allowed=None, covered=()) -> list[str]:
    """Warnings for `plan`/`roll` output: excluded unoffered models and unreadable live model lists.

    `covered` holds `account/model` keys another warning already names (a `model_latch` latch from the same refusal),
    so one incident gives one line."""
    if not isinstance(live_doc, dict):
        return []
    providers = live_doc.get('providers')
    if not isinstance(providers, dict) or not providers:
        return []
    out: list[str] = []
    seen_warnings: set[str] = set()

    def add(line: str) -> None:
        if line not in seen_warnings:
            seen_warnings.add(line)
            out.append(line)

    acc_map = (accounts or {}).get('accounts') if isinstance(accounts, dict) else None
    if isinstance(acc_map, dict):
        for acct, spec in sorted(acc_map.items()):
            if not isinstance(spec, dict) or spec.get('enabled') is False:
                continue
            if allowed is not None and not allowed(acct):
                continue
            if spec.get('discovery_status') in ('not_installed', 'missing_credentials', 'disabled'):
                continue
            if spec.get('verified') is False:
                continue
            bundles = spec.get('bundles')
            if not isinstance(bundles, dict):
                continue
            unoffered_mods: list[str] = []
            for bid, bundle in bundles.items():
                if not isinstance(bundle, dict) or not _bundle_enabled(bundle):
                    continue
                if bundle.get('discovery_unavailable'):
                    continue
                if not is_paseo_bundle(bundle, acct, spec):
                    continue
                prov = bundle_provider(bundle, acct)
                entry = providers.get(prov)
                if not isinstance(entry, dict):
                    continue
                if entry.get('ok') is False:
                    detail = unavailable_detail(entry)
                    if detail:
                        label = f'{acct} ({prov})' if prov != acct else acct
                        add(f'{label}: {detail}')
                elif entry.get('ok') is True:
                    mod = launch_model(bundle)
                    if (mod and not offers_model(prov, mod, entry) and mod not in unoffered_mods
                            and f'{acct}/{mod}' not in covered):
                        unoffered_mods.append(mod)
            if len(unoffered_mods) == 1:
                mod = unoffered_mods[0]
                add(f'{acct}/{mod}: provider no longer offers {mod}; excluded from dispatch')
            elif len(unoffered_mods) > 1:
                clauses = '; '.join(f'provider no longer offers {m}' for m in unoffered_mods)
                add(f'{acct}: {clauses}; only these models are excluded from dispatch')
        return out

    for prov, entry in sorted(providers.items()):
        detail = unavailable_detail(entry)
        if detail:
            add(f'{prov}: {detail}')
    return out
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall