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

View on GitHub
"""What stands in the way of a new turn to a worker's account and bundle, composed only from the owners of each condition.

Two readers, two contracts:

- The spawn gate (`setup/router_gate_hook.py`) enforces on a parent's new turn to its own worker, and only there:
  leftover meter text on the account (`host_policy.legacy_cause`), the confirmed-exhaustion latch (`latched`) and a
  quota window the bundle draws that refuses a launch (`window_refusal`), with the worker's own reservation left out
  (`without_own`). A message to an agent the caller does not own is communication, not dispatch, and is not checked.
- The continuation verdict (`worker_sessions.continuation_verdict`, via `worker_refusal`) says `roll` for those same
  conditions and adds advice the gate does not enforce: the worker's last turn ended in a provider failure, the account
  is not ready (`provider_inventory.unavailable_reason`), a provider hold on its account, quota pool or model
  (`provider_retry`), or a model latch (`model_latch`). A parent that sends the follow-up anyway is admitted by the gate
  whenever the enforced conditions pass.

The two preference switches are neither: an account outside host policy's `allowed_accounts` is out of automatic
routing (`host_policy.account_allowed`), and a model unchecked in model management is out of routing, but continuing a
worker that already exists is not the router choosing that account or model. Only `roll`'s automatic resume of an idle
worker, which is the router's choice, reads them (`roll._auto_resumable`).

The verdict's own reads are read-only and bounded: the registry on a read-only connection with a short wait, the exhaustion
latch without clearing it, and the failed turn from the watcher's receipt, so it does not depend on the hold or the
settlement that follows the failure. It records no hold and calls no classifier. It loads the fleet through
`account_fleet.load_accounts`, which may update host policy and holds as it does for every other caller. A worker it cannot
resolve is an error (`unknown`), not an all-clear.
"""

from datetime import datetime, timezone
from pathlib import Path

import account_fleet
import axis_scores
import dispatch_registry as registry
import host_policy
import model_latch
import provider_inventory
import provider_retry
import quota_exhaustion
import quota_pools
import usage_cache
import usage_reading


def usage_row(account, usage_cache_path, home):
    """The account's usage reading from the collector's cache (or ROUTER_USAGE_CACHE), else None."""
    providers = (usage_cache.read(usage_cache_path, home)[0] or {}).get('providers')
    row = providers.get(account) if isinstance(providers, dict) else None
    return row if isinstance(row, dict) else None


def latched_windows(account, windows, usage_cache_path, home, read_only=False):
    """The recorded confirmed failures that stop a launch drawing `windows` (`quota_exhaustion.stopping`)."""
    return quota_exhaustion.stopping(account, usage_row(account, usage_cache_path, home), windows=windows,
                                     read_only=read_only)


def latched(account, windows, usage_cache_path, home, read_only=False):
    """True when a confirmed quota failure latches the whole account or any of `windows` (the ids a launch draws)."""
    return bool(latched_windows(account, windows, usage_cache_path, home, read_only))


def without_own(records, dispatch_id=None, agent_id=None):
    """`records` (active reservations) without the worker's own. A reservation is the worker's own when it names this
    worker's agent id, or names no agent id at all and carries the dispatch id the worker is labelled with. One that
    names a different agent id is never excluded, whatever its dispatch id."""
    def own(record):
        recorded = record.get('agent_id')
        return bool(agent_id and recorded == agent_id) or bool(dispatch_id and not recorded
                                                              and record.get('dispatch_id') == dispatch_id)
    return [r for r in records if not isinstance(r, dict) or not own(r)]


def window_refusal(account, accounts, now, usage_cache_path, records, bundles=None, model=None):
    """(bundle, window id, why) of the first quota window a launch on `account` draws that refuses it now, else None.

    `bundles` are the resolved bundles of the target; without them the launch is probed as `model` on `account` (an
    unknown model draws every window). `records` are the active in-flight reservations, already without the caller's
    own (`without_own`). `accounts` is the loaded fleet; usage is read as routing reads it
    (`usage_reading.usage_snapshot`, then `provider_inventory.merge_usage`).
    """
    usage = usage_reading.usage_snapshot(usage_cache_path, [account], now, inventory=accounts.get('_discovery') or {})
    usage = provider_inventory.merge_usage(usage, accounts, now, names={account})
    probes = [dict(b, id=b.get('bundle_id') or b.get('id')) for b in bundles or ()] or [
        {'account': account, 'model': model or ''}]
    priced = axis_scores.five_axis_overlay(accounts)      # once for every probe
    for probe in probes:
        for wid, why in quota_pools.launch_blockers(probe, priced, usage, now, records=records):
            return probe.get('id') or probe.get('model') or '?', wid, why
    return None


def worker_row(agent_id, stored):
    """The dispatch row of this worker among `stored` rows, else None. The newest row carrying the agent id wins; the
    Paseo record's `router.dispatch_id` label names it when no row carries the agent id yet."""
    mine = [r for r in stored if isinstance(r, dict) and r.get('agent_id') == agent_id]
    if mine:
        return max(mine, key=lambda r: r.get('created_at') or '')
    doc = registry.paseo_agent_record(agent_id)
    labels = doc.get('labels') if isinstance(doc, dict) else None
    labelled = labels.get('router.dispatch_id') if isinstance(labels, dict) else None
    return next((r for r in stored if isinstance(r, dict) and labelled and r.get('dispatch_id') == labelled), None)


def own_failure(row):
    """The provider's message when this worker's last turn ended in a provider failure, `True` when it did without a
    message, else None. Read from the settled row's failure code, or until the row settles from the watcher's receipt:
    it does not wait for the hold the failure records."""
    code, message = row.get('failure_code'), None
    if not code:
        terminal = (registry.watcher_receipt(row['dispatch_id']) or {}).get('terminal')
        terminal = terminal if isinstance(terminal, dict) else {}
        code, message = terminal.get('failure_code'), terminal.get('provider_message')
    if code not in provider_retry.FAILURE_CODES:
        return None
    return message if isinstance(message, str) and message else True


def _legacy_refusal(account, accounts):
    found = host_policy.legacy_cause(account, accounts)
    if found:
        return found[1] + '; `agentcompass setup` clears the leftover meter fields, so roll the follow-up instead'
    return None


def _quota_gate_refusal(agent_id, account, bundle, dispatch_id, stored, accounts, now, home, usage_cache_path=None):
    windows = sorted(quota_pools.bundle_pools(dict(bundle, id=bundle.get('bundle_id') or bundle.get('id')), accounts))
    if latched(account, windows, usage_cache_path, home, read_only=True):
        return f'quota of account {account} was confirmed exhausted'
    records = without_own(registry.held_records(stored, now), dispatch_id, agent_id)
    found = window_refusal(account, accounts, now, usage_cache_path, records, bundles=[bundle])
    if found:
        what, wid, why = found
        return f'quota window {wid} of {account} ({what}) is unavailable ({why})'
    return None


def gate_refusal(agent_id, now=None, home=None, usage_cache_path=None, *, bundle=None, dispatch_id=None, accounts=None):
    """Why the spawn gate refuses a new turn to this worker now, else None.

    Checks only the three gate-enforced conditions: leftover meter text on the account, confirmed quota exhaustion
    latch, and refusing quota window (excluding the worker's own reservation).
    """
    now = now or datetime.now(timezone.utc)
    home = Path(home) if home else Path.home()
    stored = registry.read_dispatches()
    if not isinstance(bundle, dict) or not bundle.get('account') or dispatch_id is None:
        row = worker_row(agent_id, stored)
        if not isinstance(bundle, dict) or not bundle.get('account'):
            bundle = row.get('bundle') if row else None
        if dispatch_id is None and row:
            dispatch_id = row.get('dispatch_id')
    if not isinstance(bundle, dict) or not bundle.get('account'):
        raise ValueError('worker_not_resolvable')
    account = bundle['account']
    accounts = accounts if accounts is not None else account_fleet.load_accounts()
    return (_legacy_refusal(account, accounts)
            or _quota_gate_refusal(agent_id, account, bundle, dispatch_id, stored, accounts, now, home, usage_cache_path))


def worker_refusal(agent_id, now=None, home=None):
    """Why a new turn to this worker is not advised now, in words for its parent; None when nothing refuses it.

    Raises ValueError('worker_not_resolvable') for a worker with no dispatch row of this router: nothing here can say
    its account is free, and the gate would resolve it differently. sqlite3.OperationalError when the registry is
    busy for longer than a moment.
    """
    now = now or datetime.now(timezone.utc)
    home = Path(home) if home else Path.home()
    stored = registry.read_dispatches()
    row = worker_row(agent_id, stored)
    bundle = row.get('bundle') if row else None
    if not isinstance(bundle, dict) or not bundle.get('account'):
        raise ValueError('worker_not_resolvable')
    account, dispatch_id = bundle['account'], row['dispatch_id']
    failure = own_failure(row)
    if failure:
        return ('its last turn ended in a provider failure' + (f' ({failure})' if failure is not True else '')
                + '; whether the provider holds the account is classified separately')
    accounts = account_fleet.load_accounts()
    legacy = _legacy_refusal(account, accounts)
    if legacy:
        return legacy
    unavailable = provider_inventory.unavailable_reason(accounts.get('_discovery') or {}, account, bundle.get('provider'))
    if unavailable:
        return f'account {account} is not ready ({unavailable})'
    held = provider_retry.reason(bundle, provider_retry.active(now=now))
    if held:
        return f'account {account} is held after a provider failure ({held})'
    latch = model_latch.reason(bundle, model_latch.active(now=now))
    if latch:
        return f'model {model_latch.launch_model(bundle)} on {account} is held ({latch})'
    return _quota_gate_refusal(agent_id, account, bundle, dispatch_id, stored, accounts, now, home)
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