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/route_simulation.py

View on GitHub
"""Usage-aware routing distribution simulation and ledger replay.

Usage reaches the allocator the way `roll` feeds it: a collector cache document goes through
usage_reading.usage_snapshot (remaining percent before reset, freshness, pools), then allocator.plan,
which merges discovery and quota sources itself. Synthetic usage states are written as cache
documents, never as hand-made allocator input, so the simulation cannot drift from routing.

Modes:
  machine  this machine as routing sees it: accounts-override checkboxes and the host policy apply.
  fresh    a fresh install: public data plus discovered accounts; no personal choices, no host policy.

Read-only: the CLI copies the small state files routing reads (accounts-override, host policy, capacity,
overrides, public data) into a throwaway state dir, so discovery bookkeeping and host-policy enrollment
land there; the live usage cache and the ledger are only read. The usage reading is made with an empty
discovery inventory, so the Claude session-limit overlay (which may persist rate-limit files) is skipped.

  python route_simulation.py grid [--mode machine|fresh|both] [--state NAME ...] [--json out.json]
  python route_simulation.py replay [--last N] [--json out.json]
"""
import argparse
import copy
import json
import os
import shutil
import sys
import tempfile
from collections import Counter, defaultdict
from datetime import datetime, timedelta, timezone
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))
import accounts_override  # noqa: E402
import allocator  # noqa: E402
import account_fleet
import auto_bundles
import axis_scores
import quota_economy
import task_intake
import host_policy  # noqa: E402
import provider_inventory  # noqa: E402
import decision_ledger  # noqa: E402
import usage_cache  # noqa: E402
import usage_reading  # noqa: E402

SHORT_HOURS = 24
AMPLE_USED, SCARCE_USED, SHORT_SCARCE_USED = 10.0, 95.0, 98.0
# Tight: a fifth left with most of the window to run, so a cheap model's burn still fits where a strong one's does not.
LEVELS = {'scarce': ((SCARCE_USED, 0.7), (SHORT_SCARCE_USED, None)), 'tight': ((80.0, 0.6), (85.0, None))}
STALE_AGE = timedelta(days=3)

# Scenario data: (family, window ids or None for all, or 'short' for windows under SHORT_HOURS).
STATES = {
    'live': None,
    'ample': [],
    'claude scarce': [('claude', None)],
    'codex scarce': [('codex', None)],
    'antigravity gemini scarce': [('antigravity', ('gemini-weekly', 'gemini-5h'))],
    'antigravity 3p scarce': [('antigravity', ('3p-weekly', '3p-5h'))],
    'grok scarce': [('grok', None)],
    'claude+codex scarce': [('claude', None), ('codex', None)],
    'claude+antigravity scarce': [('claude', None), ('antigravity', None)],
    'claude+codex+antigravity scarce': [('claude', None), ('codex', None), ('antigravity', None)],
    '5h-only scarce': [(None, 'short')],
    'unknown/stale': 'stale',
    'claude tight': [('claude', None, 'tight')],
    'codex tight': [('codex', None, 'tight')],
    'antigravity tight': [('antigravity', None, 'tight')],
}


# --- accounts -------------------------------------------------------------------------------------
# Fresh-install account sets: synthetic discovery snapshots (what provider_inventory.discover would report) for users
# unlike this machine. Each entry is {account: (family, plan)}; `pools` gives a Magpie pool's login count per account.
ACCOUNT_SETS = {
    'claude pro': {'accounts': {'claude': ('claude', 'pro')}},
    'claude max5': {'accounts': {'claude': ('claude', 'max5')}},
    'codex plus': {'accounts': {'codex': ('codex', 'plus')}},
    'codex pro': {'accounts': {'codex': ('codex', 'pro')}},
    'antigravity pro': {'accounts': {'antigravity': ('antigravity', 'pro')}},
    'claude pro + codex plus': {'accounts': {'claude': ('claude', 'pro'), 'codex': ('codex', 'plus')}},
    'magpie pool (3x claude pro)': {'accounts': {'claude': ('claude', 'pro')}, 'pools': {'claude': 3}},
    'opencode free': {'accounts': {'opencode': ('opencode', 'free')}},
}
LAUNCHERS = {'antigravity': 'antigravity-resilient'}


def advertised(doc, family):
    """What a family's CLI is simulated to advertise: the catalog's launch surface for that harness, the same data routing
    dispatches from, so a scenario covers exactly the models a user of that CLI could be routed to. In order:
    1. the launch ids of the family account's bundles on its harness;
    2. the other models the harness launches (`dispatch_efforts[<launcher>]`);
    3. the harness's own published ids the catalog maps to rows (`aliases` keys prefixed `<launcher>/`, e.g. OpenCode's
       `opencode/<id>` free models).
    A model the catalog does not declare for the harness is not simulated there; declaring it (a bundle, an effort row or
    an alias) is a data edit that reaches routing and the simulation alike. Discovery turns these ids into auto bundles."""
    launcher = LAUNCHERS.get(family, family)
    bundles = [b for b in (((doc.get('accounts') or {}).get(family) or {}).get('bundles') or {}).values()
               if b.get('provider', family) in (family, launcher)]
    bundled = {auto_bundles.split_effort(b.get('model'), doc)[0] for b in bundles}
    ids = [*(b.get('launch_model') or b.get('model') for b in bundles),
           *(m for m in (doc.get('dispatch_efforts') or {}).get(launcher) or {} if m not in bundled),
           *(alias for alias in doc.get('aliases') or {} if alias.startswith(f'{launcher}/'))]
    return list(dict.fromkeys(m for m in ids if m))


def account_set_snapshot(name):
    """A discovery snapshot holding only the set's accounts, each ready on a subscription."""
    rows, launchers = {}, {}
    doc = account_fleet.fleet_document()
    for account, (family, plan) in ACCOUNT_SETS[name]['accounts'].items():
        row = {'family': family, 'status': 'ready', 'plan': plan, 'billing': 'subscription', 'sources': ['native'],
               'identity': f'sim-{account}', 'quota_account': account, 'models': advertised(doc, family)}
        if family in LAUNCHERS:
            row['provider'] = LAUNCHERS[family]
            launchers[LAUNCHERS[family]] = {'family': LAUNCHERS[family], 'status': 'ready'}
        rows[account] = row
        launchers[family] = {'family': family, 'status': 'ready'}
    return {'accounts': rows, 'launchers': launchers}


def accounts_for(mode, account_set=None):
    if mode == 'machine':
        return machine_accounts(), {}
    if account_set is None:
        return fresh_accounts(), {}
    return fresh_accounts(inventory=account_set_snapshot(account_set)), dict(ACCOUNT_SETS[account_set].get('pools') or {})


def machine_accounts():
    """The document routing uses on this machine (account_fleet.load_accounts)."""
    return account_fleet.load_accounts()


def fresh_accounts(document=None, inventory=None):
    """Public data plus discovery, as load_accounts builds it, minus personal overrides and machine measurements."""
    doc = document if document is not None else account_fleet.fleet_document()
    accounts = accounts_override.normalize(copy.deepcopy(doc))
    accounts = provider_inventory.apply(accounts, inventory, live=False)
    provider_inventory.apply_shared_quota(accounts)
    return accounts_override.normalize(accounts)


def host_policy_for(mode, accounts, account_set=None):
    """machine: the host policy routing loads. fresh: a new install admits what discovery found, so every account here,
    or only the set's accounts for a synthetic account set."""
    if mode == 'machine':
        return None
    names = ACCOUNT_SETS[account_set]['accounts'] if account_set else (accounts.get('accounts') or {})
    return {'allowed_accounts': list(names)}


def family_of(name, accounts):
    return provider_inventory.account_family(name, accounts, accounts.get('_discovery') or {})


# --- usage ----------------------------------------------------------------------------------------
def snapshot(document, accounts, now):
    """usage_reading.usage_snapshot over one cache document (the roll pipeline)."""
    with tempfile.TemporaryDirectory() as folder:
        path = Path(folder) / usage_cache.CACHE_FILE
        path.write_text(json.dumps(document), encoding='utf-8')
        return usage_reading.usage_snapshot(path, None, now, quota_sources=provider_inventory.quota_sources(accounts),
                                            inventory={'accounts': {}})


def metered_accounts(accounts):
    """Accounts with their own quota windows (pooled followers mirror their source)."""
    followers = provider_inventory.quota_sources(accounts)
    return {name: spec for name, spec in (accounts.get('accounts') or {}).items()
            if isinstance(spec.get('windows'), dict) and spec['windows'] and name not in followers}


def synthetic_document(accounts, now, scenario, pools=None):
    """Collector cache rows for every windowed account: ample everywhere except the scenario's scarce windows.
    `pools` gives a Magpie pool's login count; the collector reports it per window as `accounts`."""
    providers = {}
    stale = scenario == 'stale'
    for name, spec in metered_accounts(accounts).items():
        family = family_of(name, accounts)
        windows = []
        for wid, wspec in spec['windows'].items():
            hours = float(wspec.get('hours') or 168)
            short = hours < SHORT_HOURS
            level = None if stale else next(
                ((rule[2] if len(rule) > 2 else 'scarce') for rule in scenario
                 if (rule[0] is None or rule[0] == family)
                 and (rule[1] is None or (rule[1] == 'short' and short) or (isinstance(rule[1], tuple) and wid in rule[1]))),
                None)
            if level:
                (long_used, long_left), (short_used, _) = LEVELS[level]
                used, reset = (short_used, 3.0) if short else (long_used, hours * long_left)
            else:
                used, reset = AMPLE_USED, hours * 0.5
            row = {'id': wid, 'used_pct': used, 'resets_at': (now + timedelta(hours=reset)).isoformat()}
            if (pools or {}).get(name, 1) > 1:
                row['accounts'] = pools[name]
            windows.append(row)
        fetched = now - STALE_AGE if stale else now
        providers[name] = {'fetched_at': fetched.isoformat(), 'stale': stale, 'available': True, 'windows': windows}
    return {'providers': providers}


LIVE_PATHS = None    # set by the CLI sandbox to the real cache copies before the state dir moves


def live_document():
    """The collector cache as `roll` reads it."""
    for path in LIVE_PATHS or usage_cache.read_paths():
        try:
            return usage_cache.read_document(path)
        except (OSError, ValueError, UnicodeError):
            continue
    return {'providers': {}}


def pool_counts(document):
    """{provider: {window id: accounts}} for the pooled windows of a cache document."""
    return {name: {w.get('id'): w['accounts'] for w in row.get('windows') or []
                   if isinstance(w, dict) and isinstance(w.get('accounts'), int) and w['accounts'] > 1}
            for name, row in (document.get('providers') or {}).items() if isinstance(row, dict)}


def ledger_document(compact, pools=None):
    """A ledger record's compact usage as the cache document it was read from (fetched_at, stale, windows).

    Records since 2026-11-04 keep a pooled window's `accounts`. Older ones dropped it; for those `pools` (the live cache's
    pool counts, `pool_counts(live_document())`) fills it in, on the assumption that a pool's size rarely changes."""
    providers = {}
    for name, row in (compact or {}).items():
        if isinstance(row, dict) and row.get('fetched_at'):
            windows = []
            for w in row.get('windows') or []:
                if not isinstance(w, dict):
                    continue
                known = ((pools or {}).get(name) or {}).get(w.get('id'))
                windows.append(dict(w, accounts=known) if 'accounts' not in w and known else w)
            providers[name] = {'fetched_at': row['fetched_at'], 'stale': row.get('status') == 'stale', 'available': True,
                               'windows': windows}
    return {'providers': providers}


def usage_for(state, accounts, now, pools=None):
    scenario = STATES[state]
    if scenario is None:
        return snapshot(live_document(), accounts, now)
    return snapshot(synthetic_document(accounts, now, scenario, pools), accounts, now)


# --- grid -----------------------------------------------------------------------------------------
def demand_task(demand, local, hours=2.0):
    """A task whose classifier profile asks `demand` (one point of the category demand space) of the four categories.
    The grid sweeps the whole space; `primary_level` follows the strongest category demand so the profile is complete."""
    peak = max(1, min(3, max(demand.values(), default=1)))
    return {'objective': 'demand ' + ' '.join(f'{a}={demand[a]}' for a in axis_scores.FIVE_AXES), 'expected_hours': hours,
            'needs': {'local_only': local},
            'profile': {'work_kind': 'code_implementation', 'primary_level': peak,
                        'secondary_kind': 'none', 'secondary_level': 0,
                        'needs_visual': demand['tool_operation'] >= axis_scores.IMAGE_INPUT_LEVEL,
                        'needs_gui': False, 'local_only': local, 'wants_fast': False,
                        'read_only_review': False, 'access': 'write', 'expected_hours': hours,
                        'multi_task': False, 'task_count': '1',
                        'axis_demand': dict(demand)}}


def grid_tasks(accounts=None):
    return [demand_task(point, local) for point in quota_economy.FIVE_AXIS_DEMAND_GRID for local in (True, False)]


def label(bundle):
    """A model as the account serves it: the same model on two subscriptions draws on different quota."""
    return f"{bundle['model']}@{bundle['account']}" if bundle.get('model') else 'none'


def run_state(accounts, usage, now, tasks, host_policy_config, *, mode='machine'):
    wins_bundle, wins_model = Counter(), Counter()
    seen = defaultdict(lambda: {'eligible': 0, 'gaps': [], 'excluded': Counter()})
    read_local = (mode == 'machine')
    for task in tasks:
        decision = allocator.plan(task, usage, now, accounts=copy.deepcopy(accounts), overrides=[], records=[],
                                  host_policy_config=host_policy_config, read_local_state=read_local)
        selected = decision.get('selected_bundle') or {}
        wins_bundle[decision.get('choice') or 'none'] += 1
        wins_model[label(selected)] += 1
        top = next((c['score'] for c in decision['ranking'] if c['score'] is not None), None)
        for c in decision['ranking']:
            row = seen[c['id']]
            if c['excluded']:
                row['excluded'].update(c['excluded'])
            elif c['score'] is not None and top is not None:
                row['eligible'] += 1
                row['gaps'].append(top - c['score'])
    return wins_bundle, wins_model, seen


def _fresh_state_env():
    """Context manager running fresh-mode evaluation against an empty temporary state dir (never ~/.agent-compass)."""
    import contextlib

    @contextlib.contextmanager
    def _ctx():
        with tempfile.TemporaryDirectory(prefix='route-sim-fresh-') as empty_root:
            target = Path(empty_root) / '.agent-compass'
            target.mkdir(parents=True)
            keys = ('ROUTER_STATE_DIR', 'ROUTER_HOST_POLICY', 'ROUTER_CAPACITY',
                    'ROUTER_OVERRIDES', 'AGENTCOMPASS_ACCOUNTS_OVERRIDE', 'ROUTER_USER_SCORES')
            saved = {k: os.environ.get(k) for k in keys}
            os.environ.update(
                ROUTER_STATE_DIR=str(target),
                ROUTER_HOST_POLICY=str(target / 'host-policy.json'),
                ROUTER_CAPACITY=str(target / 'capacity.json'),
                ROUTER_OVERRIDES=str(target / 'router-overrides.json'),
                AGENTCOMPASS_ACCOUNTS_OVERRIDE=str(target / 'accounts-override.json'),
                ROUTER_USER_SCORES=str(target / 'user-scores.json'),
            )
            try:
                yield
            finally:
                for k, v in saved.items():
                    if v is None:
                        os.environ.pop(k, None)
                    else:
                        os.environ[k] = v

    return _ctx()


def grid(mode, states=None, now=None, account_set=None):
    import contextlib
    now = now or datetime.now(timezone.utc)
    ctx = _fresh_state_env() if mode == 'fresh' else contextlib.nullcontext()
    with ctx:
        accounts, pools = accounts_for(mode, account_set)
        policy = host_policy_for(mode, accounts, account_set)
        tasks = grid_tasks(accounts)
        flat = account_fleet.bundles(accounts)
        enabled = {bid: b for bid, b in flat.items() if not b.get('disabled')}
        report = {'mode': mode, 'account_set': account_set or ('this machine' if mode == 'machine' else 'discovered here'),
                  'tasks_per_state': len(tasks), 'states': {}}
        totals = Counter()
        seen_all = defaultdict(lambda: {'eligible': 0, 'gaps': [], 'excluded': Counter()})
        for state in states or STATES:
            usage = usage_for(state, accounts, now, pools)
            bundle_wins, model_wins, seen = run_state(accounts, usage, now, tasks, policy, mode=mode)
            totals.update(model_wins)
            for bid, row in seen.items():
                seen_all[bid]['eligible'] += row['eligible']
                seen_all[bid]['gaps'] += row['gaps']
                seen_all[bid]['excluded'].update(row['excluded'])
            report['states'][state] = {'bundles': dict(bundle_wins.most_common()), 'models': dict(model_wins.most_common())}
        models = sorted({label(b) for b in enabled.values()})
        nowhere = {}
        for model in models:
            if totals.get(model):
                continue
            ids = [bid for bid, b in enabled.items() if label(b) == model]
            why = {}
            for bid in ids:
                row = seen_all.get(bid)
                if row is None:
                    why[bid] = 'never a candidate (no route applies)'
                    continue
                gaps = sorted(row['gaps'])
                why[bid] = {'eligible_in': row['eligible'], 'median_gap_to_top': round(gaps[len(gaps) // 2], 4) if gaps else None,
                            'top_exclusions': row['excluded'].most_common(3)}
            nowhere[model] = why
        report['wins_nowhere'] = nowhere
        return report


def explain(mode, state, task, bundle_ids=(), top=5, now=None, account_set=None):
    """One task under one usage state: the top of the ranking plus the named bundles, with score components."""
    import contextlib
    now = now or datetime.now(timezone.utc)
    ctx = _fresh_state_env() if mode == 'fresh' else contextlib.nullcontext()
    with ctx:
        accounts, pools = accounts_for(mode, account_set)
        policy = host_policy_for(mode, accounts, account_set)
        decision = allocator.plan(task, usage_for(state, accounts, now, pools), now, accounts=accounts, overrides=[], records=[],
                                  host_policy_config=policy, read_local_state=(mode == 'machine'))
    keep = [c for c in decision['ranking'] if c['score'] is not None][:top]
    keep += [c for c in decision['ranking'] if c['id'] in bundle_ids and c not in keep]
    return [{'id': c['id'], 'score': c['score'], 'excluded': c['excluded'], 'components': c['components']} for c in keep]


# --- replay ---------------------------------------------------------------------------------------
def ledger_records(path=None, last=None):
    path = Path(path) if path else decision_ledger.ledger_path()
    rows = []
    with path.open(encoding='utf-8') as stream:
        for line in stream:
            try:
                row = json.loads(line)
            except ValueError:
                continue
            snap = row.get('decision_snapshot')
            if (row.get('stage') == 'plan' and isinstance(snap, dict) and isinstance(snap.get('task'), dict)
                    and isinstance(row.get('usage'), dict) and not row.get('constraint')):
                rows.append(row)
    return rows[-last:] if last else rows


def replay_task(row):
    task = dict(row['decision_snapshot']['task'])
    if row.get('hours'):
        task.setdefault('hours', row['hours'])
    return task


def replay(last=None, path=None, accounts=None, warnings=None):
    """Re-plan each ledger decision with the usage it saw, read through the roll pipeline at its own time.

    Rows recorded in an older profile shape are skipped (never mapped), with their count reported in `warnings`.
    """
    accounts = accounts or machine_accounts()
    pools = pool_counts(live_document())
    out = []
    skipped = 0
    for row in ledger_records(path, last):
        task = replay_task(row)
        try:
            task_intake.validate_profile(task.get('profile') if isinstance(task.get('profile'), dict) else {})
        except ValueError:
            skipped += 1
            continue
        now = datetime.fromisoformat(row['at'])
        usage = snapshot(ledger_document(row['usage'], pools), accounts, now)
        decision = allocator.plan(task, usage, now, accounts=copy.deepcopy(accounts), overrides=[], records=[])
        selected = decision.get('selected_bundle') or {}
        out.append({'at': row['at'], 'kind': row.get('kind'), 'difficulty': row.get('difficulty'),
                    'ledger_choice': row.get('choice'), 'choice': decision.get('choice'), 'model': selected.get('model')})
    if skipped and isinstance(warnings, list):
        warnings.append(f'skipped {skipped} older-shape ledger row(s)')
    return out


STATE_COPY_MAX_BYTES = 1 << 20
STATE_COPY_DIRS = ('public-data', 'grok-bot')    # routing reads the published reference set and the Grok Bot config


def sandbox_state(folder, *, include_local=True):
    """Point routing state at a copy of the real state dir's small files (or an empty dir when include_local=False)."""
    source = Path(os.environ.get('ROUTER_STATE_DIR') or Path.home() / '.agent-compass').expanduser()
    live = [str(p) for p in usage_cache.read_paths()] if include_local else []
    ledger = decision_ledger.ledger_path()
    target = Path(folder) / '.agent-compass'
    target.mkdir(parents=True)
    if include_local:
        for path in source.glob('*.json'):
            if path.is_file() and path.stat().st_size <= STATE_COPY_MAX_BYTES:
                shutil.copy2(path, target / path.name)
        for sub in STATE_COPY_DIRS:
            if (source / sub).is_dir():
                shutil.copytree(source / sub, target / sub, ignore=shutil.ignore_patterns('*.lock', 'tasks'))
        policy_path, _ = host_policy.policy_path()
        if policy_path.is_file():
            shutil.copy2(policy_path, target / 'host-policy.json')
    os.environ.update(ROUTER_STATE_DIR=str(target), ROUTER_HOST_POLICY=str(target / 'host-policy.json'),
                      ROUTER_CAPACITY=str(target / 'capacity.json'), ROUTER_OVERRIDES=str(target / 'router-overrides.json'),
                      AGENTCOMPASS_ACCOUNTS_OVERRIDE=str(target / 'accounts-override.json'),
                      ROUTER_USER_SCORES=str(target / 'user-scores.json'))
    return live, ledger


def main(argv=None):
    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    sub = parser.add_subparsers(dest='command', required=True)
    g = sub.add_parser('grid')
    g.add_argument('--mode', choices=('machine', 'fresh', 'both'), default='both')
    g.add_argument('--state', action='append', choices=list(STATES))
    g.add_argument('--accounts', action='append', choices=list(ACCOUNT_SETS),
                   help='fresh mode with a synthetic account set instead of the accounts discovered here (repeatable)')
    g.add_argument('--json')
    e = sub.add_parser('explain')
    e.add_argument('--mode', choices=('machine', 'fresh'), default='fresh')
    e.add_argument('--state', choices=list(STATES), default='ample')
    for axis in axis_scores.FIVE_AXES:
        e.add_argument('--' + axis.replace('_', '-'), type=int, choices=range(4), default=0, help=f'demand level 0-3 on {axis}')
    e.add_argument('--local', action='store_true')
    e.add_argument('--bundle', action='append', default=[])
    e.add_argument('--top', type=int, default=5)
    e.add_argument('--accounts', choices=list(ACCOUNT_SETS))
    e.add_argument('--json')
    r = sub.add_parser('replay')
    r.add_argument('--last', type=int)
    r.add_argument('--ledger')
    r.add_argument('--json')
    args = parser.parse_args(argv)
    global LIVE_PATHS
    fresh_only = (
        (args.command == 'grid' and (args.mode == 'fresh' or bool(args.accounts)))
        or (args.command == 'explain' and (args.mode == 'fresh' or bool(args.accounts)))
    )
    folder = tempfile.mkdtemp(prefix='route-simulation-')
    try:
        LIVE_PATHS, ledger = sandbox_state(folder, include_local=not fresh_only)
        return run(args, getattr(args, 'ledger', None) or ledger)
    finally:
        shutil.rmtree(folder, ignore_errors=True)


def run(args, ledger):
    if args.command == 'grid':
        modes = ('machine', 'fresh') if args.mode == 'both' else (args.mode,)
        if args.accounts:
            result = [grid('fresh', args.state, account_set=name) for name in args.accounts]
        else:
            result = [grid(mode, args.state) for mode in modes]
        for report in result:
            print(f"== {report['mode']} / {report['account_set']} ({report['tasks_per_state']} tasks per state)")
            for state, row in report['states'].items():
                print(f'  {state:28s} {row["models"]}')
            print(f"  wins nowhere: {sorted(report['wins_nowhere'])}")
    elif args.command == 'explain':
        task = demand_task({axis: getattr(args, axis) for axis in axis_scores.FIVE_AXES}, args.local)
        result = explain('fresh' if args.accounts else args.mode, args.state, task, args.bundle, args.top,
                         account_set=args.accounts)
        for row in result:
            print(row['id'], row['score'], row['excluded'] or '', {k: v for k, v in row['components'].items() if v})
    else:
        replay_warnings = []
        result = replay(args.last, ledger, warnings=replay_warnings)
        note = f" ({'; '.join(replay_warnings)})" if replay_warnings else ''
        print(f'{len(result)}{note}', Counter(r['choice'] for r in result).most_common())
    if args.json:
        Path(args.json).write_text(json.dumps(result, indent=1, ensure_ascii=False, default=str), encoding='utf-8')
    return 0


if __name__ == '__main__':
    raise SystemExit(main())
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