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

View on GitHub
"""Deterministic worker allocation: capability gates, task fit across the four capability categories
(`creativity`, `coding`, `aesthetics`, `tool_operation`), continuity with a coupled chain's existing worker,
and the opportunity cost of the quota the work would use.

Scores are panel standard deviations (`z = (x - x_anchor) / sd_panel`, the accounts.json `calibration_panel` anchor at High = 0) from
`references/five-axis-scores.json`. In `five_axis_fit`, each demanded category's zero point is its level-1 target `t1`
(the panel's weakest model), level 2 targets the panel median `t2`, and level 3 targets the panel's best `t3`:
`fit = sum_a w_a * (min(z_a, c_a) - t1_a) / sum_a w_a`, the cap `c_a` being the target at levels 1 and 2 and the
category's ceiling (the best measured model) at level 3 (scores below `t1_a` may go below zero, and economy outside
alternatives require positive fit above zero). The formula is defined in `docs/technical-reference.md` section 1. Every number that drives a choice
lives in `references/accounts.json` or `references/five-axis-scores.json` and is returned in the per-candidate breakdown.
"""

import math
from datetime import datetime, timedelta, timezone
from pathlib import Path
import sys

# Also support the path-loaded allocator and python -I entrypoints.
sys.path.insert(0, str(Path(__file__).resolve().parent))
import account_state
import host_policy
import live_models
import model_latch
import provider_retry
import provider_inventory
import accounts_override
import account_fleet
import axis_scores
import candidate_eval
import candidate_ranking
import quota_economy
import quota_overrides
import quota_pools
import task_intake
import user_scores
import worker_sessions


def advised_hours(hours):
    """A wait the caller is told to wait or to allow (`--can-wait-hours`): `hours` rounded up to a tenth, so that waiting that
    long finds the window reset and allowing it passes the `available_in_hours > can_wait` check. Rounding to nearest could
    advise 4.0 for a 4.04h wait, which asks again."""
    advised = math.ceil(hours * 10) / 10
    while advised < hours:
        advised += 0.1
    return round(advised, 1)


def named_pin_block(task, candidates):
    """Why what the user named cannot run, one line per row; [] when the task names nothing."""
    if not (task.get('constraint_model') or task.get('constraint_bundle') or task.get('constraint_effort') or task.get('pinned_bundle')):
        return []
    off_pin = ('explicit model constraint', 'explicit effort constraint')
    pinned = task.get('pinned_bundle')
    rows = [c for c in candidates if (pinned and candidate_ranking.candidate_for_bundle([c], pinned, task.get('force_fast')) is c)
            or (not pinned and not any(r in off_pin for r in c['excluded']))]
    raw = task.get('constraint_raw_model')
    spelled, colon_eff = task_intake.split_model_effort(raw) if raw else (task.get('constraint_model'), None)
    eff = task.get('constraint_effort')
    eff_part = None if (eff and not colon_eff and spelled and spelled.lower().endswith('-' + eff)) else eff
    named = (task.get('pinned_bundle') or (task.get('constraint_bundle') if not raw else None)
             or ':'.join(x for x in (spelled, eff_part) if x))
    if not rows:
        return [f'{named}: no configured bundle offers it']
    return [f"{named} via {c['id']}: {'; '.join(c['excluded'])}" for c in rows if c['excluded']]


def plan(raw_task, usage, now=None, unavailable=(), records=None, accounts=None, capabilities=None, overrides=None,
         host_policy_config=None, *, read_local_state=True, named_accounts=(), route=None):
    """`named_accounts`: accounts a named route or an explicit resume names (dispatch_registry.prepare). Their facts are
    read whether or not they take part in automatic routing (candidate_ranking.rank). `route`: the route fields of a
    decision AgentCompass recorded (task_intake.ROUTE_FIELDS); a caller's task never carries them."""
    accounts = accounts_override.normalize(accounts or account_fleet.load_accounts())
    capabilities = capabilities or account_fleet.load_capabilities(accounts=accounts)
    now = now or datetime.now(timezone.utc)
    usage = provider_inventory.merge_usage(usage, accounts, now)
    active_overrides = (quota_overrides.load_overrides(now) if read_local_state else []) if overrides is None else overrides
    usage, accounts, applied = quota_overrides.apply_overrides(active_overrides, usage, accounts, now)
    accounts = axis_scores.five_axis_overlay(accounts, read_local_state=read_local_state)
    policy = accounts['scoring']
    task = task_intake.normalize_task(raw_task, policy, capabilities, accounts, route=route)
    if task['worker'] is None and task['chain_id'] and records:
        for record in reversed(records):
            if record.get('chain') == task['chain_id'] and (record.get('bundle') or {}).get('bundle_id'):
                w = {'bundle': record['bundle']['bundle_id'], 'from_ledger': True}
                wid = record.get('worker_id') or (record.get('worker') or {}).get('agent_id')
                if wid and read_local_state:
                    w['agent_id'] = wid
                    w.update(worker_sessions.session_state(wid))
                task['worker'] = w
                break
    candidates, eligible, system = candidate_ranking.rank(task, usage, policy, accounts, capabilities, now, unavailable, applied, records,
                                        host_policy_config, read_local_state=read_local_state,
                                        named_accounts=named_accounts)
    # Metered last resort: only when no subscription bundle is eligible, re-rank with checked metered bundles admitted.
    if not eligible and any(c['excluded'] == [candidate_eval.METERED_LAST_RESORT] for c in candidates):
        task['metered_fallback'] = True
        candidates, eligible, system = candidate_ranking.rank(task, usage, policy, accounts, capabilities, now, unavailable, applied,
                                            records, host_policy_config, read_local_state=read_local_state,
                                            named_accounts=named_accounts)
    worker_id = (task['worker'] or {}).get('bundle')
    resume = next((c for c in candidates if c['id'] == worker_id), None)
    decision = {'task': {k: task[k] for k in ('kind', 'difficulty', 'hours', 'chain_hours', 'coupling')}, 'system': system,
                'assumptions': assumptions(candidates, accounts)}
    for err in candidate_eval.QUOTA_DATA_ERRORS:
        unread = sorted({c['bundle']['account'] for c in candidates if any(err in str(r) for r in c['excluded'])})
        if unread:
            decision.setdefault('warnings', []).append(
                f"{', '.join(unread)}: {err}; out of automatic routing and no substitute for other accounts")
    aged = {}
    for c in candidates:
        at = c['components'].get('reading_at')
        if at and not c['excluded']:
            aged.setdefault(c['bundle']['account'], at)
    for name, at in sorted(aged.items()):
        decision.setdefault('warnings', []).append(
            f"{name}: priced from its last good usage reading, taken at {at} in the current reset period "
            f"(the latest read failed); a provider hold on a model or pool still wins over this reading")
    if (sync := accounts.get('_host_policy_sync') or {}).get('mode') == 'error':
        decision.setdefault('warnings', []).append(host_policy.sync_failed(sync.get('error')))
    state_policy = (host_policy.load_policy() if read_local_state else {'allowed_accounts': list((accounts.get('accounts') or {}).keys())}) if host_policy_config is None else host_policy_config
    state_warnings = account_state.warnings(accounts.get('_discovery'), accounts['accounts'],
                                            lambda name: host_policy.account_allowed(state_policy, name))
    if state_warnings:
        decision.setdefault('warnings', []).extend(state_warnings)
    live_doc = system.pop('_live_models', None) or (live_models.load_or_refresh(
        accounts=accounts,
        allowed=lambda name: host_policy.account_allowed(state_policy, name),
        now=now,
    ) if read_local_state else {'accounts': {}})
    latches = model_latch.active(now=now) if read_local_state else {}
    latch_warnings = live_models.warnings(
        live_doc,
        accounts,
        lambda name: host_policy.account_allowed(state_policy, name),
        covered=set(latches),
    )
    latch_warnings += model_latch.warnings(latches, lambda name: host_policy.account_allowed(state_policy, name)) if read_local_state else []
    latch_warnings += provider_retry.warnings(provider_retry.active(now=now),
                                              lambda name: host_policy.account_allowed(state_policy, name)) if read_local_state else []
    if latch_warnings:
        # First: the roll answer shows only the first few warnings, and a model that cannot start must be seen.
        decision['warnings'] = [*latch_warnings, *decision.get('warnings', [])]
    decision['task'].update(difficulty_source=task['difficulty_source'], axis_demand=axis_scores.five_axis_demand(task),
                            max_recommended_effort=None)
    if task.get('wants_fast'):
        decision['task']['wants_fast'] = True
    if task.get('read_only_review'):
        decision['task']['read_only_review'] = True
    if task.get('metered_fallback'):
        decision['task']['metered_fallback'] = True
    if task['profile']:
        decision['task'].update(profile=task['profile'], profile_difficulty=task['profile_difficulty'])
    if applied:
        decision['overrides'] = applied
    ranked_candidates = [*eligible, *[c for c in candidates if c['excluded']]]
    result = {'stage': 'plan', 'source': 'deterministic_allocator', 'observed_at': now.isoformat(), 'decision': decision,
              'ranking': ranked_candidates, 'usage': usage}
    if not eligible:
        closest = sorted(
            (c for c in candidates if c['excluded']),
            key=lambda c: (len(c['excluded']), -(c['components']['fit'] if c['components'].get('fit') is not None else float('-inf'))),
        )[:2]
        named_block = named_pin_block(task, candidates)
        decision.update({'action': 'none', 'needs_user_decision': True,
                         'reason': 'No eligible bundle. Closest: ' + ' | '.join(
                             f"{c['id']}: {'; '.join(candidate_eval.said_exclusions(c))}" for c in closest)})
        kinds = [candidate_eval.local_settings(c) for c in closest]
        if closest and all(kinds):
            # Nothing but the user's own settings on this machine keeps the closest candidates out (roll.none_next).
            decision['local_settings'] = {
                'exclusions': [f"{c['id']}: {said}" for c in closest for said in candidate_eval.said_exclusions(c)],
                'named_route_reaches': all(set(k) <= set(candidate_eval.LIFTED_BY_NAMING) for k in kinds)}
        # When a bundle is held back only by quota, say when that quota returns, so the parent can wait.
        waits = sorted((wait[0], wait[1], c['id'], c['bundle']['account']) for c in candidates if c['excluded']
                       and (wait := quota_pools.quota_wait(c, usage)) is not None)
        if waits:
            hours, window, bundle_id, account = waits[0]
            decision['next_reset'] = {'bundle': bundle_id, 'account': account, 'window': window, 'hours': advised_hours(hours),
                                      'at': (now + timedelta(hours=hours)).isoformat()}
            # First: the answer a caller reads is cut short, and this is the fact that says what to do.
            decision['reason'] = (f"{bundle_id} is held back by {account}'s {window} quota, which returns in {advised_hours(hours)}h: "
                                  f"wait, or decide otherwise. {decision['reason']}")
        if named_block:
            # What the user named cannot run. Say why and stop; nothing else stands in for it.
            decision['blocked'] = 'named_model_unavailable'
            decision.setdefault('warnings', []).extend(named_block)
            decision['reason'] = ' | '.join(named_block)
            result['next'] = ('The model the user named cannot run now: ' + '; '.join(named_block)[:300]
                              + '. Tell the user; do not substitute another model.')
        result['choice'] = 'none'
        return result
    can_wait = task['can_wait_hours']
    ready = [c for c in eligible if (c['available_in_hours'] or 0) <= can_wait]
    pool = ready or eligible
    pinned_cand = (
        candidate_ranking.candidate_for_bundle(pool, task['pinned_bundle'], task.get('force_fast'))
        if task.get('pinned_bundle') else None
    )
    top = pinned_cand or pool[0]
    better = eligible[0]
    if better is not top and better['available_in_hours']:
        decision['better_if_waiting'] = {'bundle': better['id'], 'hours': round(better['available_in_hours'], 1),
                                         'score_gain': round(better['score'] - top['score'], 4)}
    forced = pinned_cand is not None
    decision.update({'action': top['action'], 'needs_user_decision': False,
                     'continuity': (f"{task['coupling']}-coupling chain stays with its owner"
                                    if (top is resume and top['action'] == 'resume' and not forced) else None)})
    if top['available_in_hours']:
        decision['wait_for'] = {'bundle': top['id'], 'account': top['bundle']['account'], 'window': top.get('waiting_on'),
                                'hours': advised_hours(top['available_in_hours'])}
    if (top['available_in_hours'] or 0) > can_wait:
        # can_wait_hours is a limit, not a preference: say so instead of quietly starting later than allowed
        after = f" ({top['bundle']['account']}'s {top['waiting_on']} window resets then)" if top.get('waiting_on') else ''
        decision.update({'needs_user_decision': True, 'wait_hours': advised_hours(top['available_in_hours']),
                         'reason': (f"The chain owner {top['id']} can resume in {advised_hours(top['available_in_hours'])}h{after}"
                                    if top is resume and top['action'] == 'resume'
                                    else f"Nothing eligible can start within {can_wait:g}h; the best, {top['id']}, can start in {advised_hours(top['available_in_hours'])}h{after}")
                         + '. Wait, allow a longer wait, or mark it unavailable and replan.'})
    # A worker held only by the old route gives way when the user names something else.
    pin_moved = resume is not None and (
        ('explicit model constraint' in resume['excluded'] or 'explicit effort constraint' in resume['excluded'])
        or bool(task.get('pinned_bundle') and task['pinned_bundle'] != resume['id']))
    if (task['worker'] and not worker_sessions.worker_worn(task['worker'], policy) and task['coupling'] == 'high'
            and resume is not None and resume['excluded'] and not pin_moved):
        decision.update({'needs_user_decision': True, 'drift_risk': 'high',
                         'resume_blocked_by': resume['excluded'],
                         'wait_hours': (advised_hours(resume['wait_until_hours']) if isinstance(resume.get('wait_until_hours'), (int, float))
                                        and math.isfinite(resume['wait_until_hours']) else None),
                         'reason': (f"The chain owner {resume['id']} cannot continue now ({'; '.join(candidate_eval.said_exclusions(resume))})"
                                    + (f"; it can continue in {advised_hours(resume['wait_until_hours'])}h" if isinstance(resume.get('wait_until_hours'), (int, float)) and resume['wait_until_hours'] != float('inf') else '')
                                    + '. Waiting keeps one owner; switching delivers sooner with handoff and drift risk.')})
    # The margin is to the best other model, not to another effort, harness or account of the same model.
    rival = next((c for c in pool if c is not top
                  and account_fleet.row_key(c['bundle']['model'], accounts) != account_fleet.row_key(top['bundle']['model'], accounts)), None)
    margin = round(top['score'] - rival['score'], 4) if rival is not None and not forced else None
    decision['margin'] = margin
    if top.get('data_errors'):
        for note in top.get('notes') or ():
            if str(note).startswith('data error:'):
                w_note = f"{top['id']}: {note}"
                if w_note not in decision.get('warnings', ()):
                    decision.setdefault('warnings', []).append(w_note)
    if top['bundle'].get('fast'):
        decision['fast'] = True
        decision['fast_reason'] = top['components'].get('fast_reason')
    decision.setdefault('reason', explain(top, system))
    # No required ability: the fit and the economy chose this effort.
    chosen = top['bundle'].get('effort')
    decision['task']['max_recommended_effort'] = chosen if chosen in user_scores.EFFORTS else None
    result['choice'] = top['id']
    result['selected_bundle'] = dict(top['bundle'], bundle_id=top.get('base_id') or top['id'], expected_usd=top.get('expected_usd'),
                                     expected_hours=top.get('expected_hours'))
    result['expected_usd'] = top.get('expected_usd')
    result['expected_hours'] = top.get('expected_hours')
    result['decision']['alternatives'] = list(dict.fromkeys(c['id'] for c in pool if c['id'] != top['id']))[:3]
    if top['available_in_hours']:
        decision.update({'action': 'defer', 'start_after_hours': advised_hours(top['available_in_hours'])})
    if task.get('wants_fast') and not top['bundle'].get('fast'):
        decision['fast_not_applied'] = (top.get('fast_not_offered')
                                        or 'fast mode was priced as a candidate of its own and the plain mode ranked higher')
    return result


def assumptions(candidates, accounts):
    notes = []
    for c in candidates:
        if c['excluded']:
            continue
        spec = accounts['accounts'][c['bundle']['account']]
        if quota_pools.parse_time(spec.get('expires_at')) and spec.get('expires_precision') == 'date':
            notes.append(f"{c['bundle']['account']}: expiry is a date only; end of day assumed")
    return sorted(set(notes))


def explain(top, system):
    parts = [f"{top['id']} ({top['action']}) scored {top['score']:.4f}"]
    cap = top.get('capacity')
    if cap:
        rem_usd_str = f" (${cap['remaining_usd']:.2f})" if cap.get('remaining_usd') is not None else ""
        exp_usd_str = f" (~${top['expected_usd']:.2f})" if top.get('expected_usd') is not None else ""
        priced = (f"need probability {cap['need_start']:.2f} -> {cap['need_end']:.2f}, quota price "
                  f"{cap['quota_price']:.5f} fit/USD" if cap.get('priced') else 'a short window: feasibility only, not priced')
        members = round(cap['full'] / 100.0)
        left = (f"{cap['remaining']:.0f}% left" if members == 1
                else f"{cap['remaining']:.0f}% of one account left in a pool of {members} (full = {cap['full']:.0f}%)")
        parts.append(f"{cap['window']}: {left}{rem_usd_str}, work ~{top['expected_pct']}%{exp_usd_str} "
                     f"(chain ~{top['chain_pct']}%), {priced}, "
                     + (f"before its {'expiry' if cap['expires_first'] else 'reset'} in {cap['end_hours']:.0f}h, "
                        if cap.get('end_hours') is not None else 'with no reset, ')
                     + f"opportunity cost {top['components']['opportunity_cost']:.4f}")
    if top['bundle'].get('fast'):
        parts.append(f"fast mode enabled ({top['components'].get('fast_reason') or 'priced as its own candidate'})")
    if top['components'].get('boost'):
        parts.append(f"includes a temporary user-override boost of {top['components']['boost']:+.2f}")
    if top['components'].get('continuity'):
        parts.append(f"continuing its related worker adds {top['components']['continuity']:.2f} (one demand level)")
    if top.get('unscored_named_dispatch'):
        parts.append('unscored named dispatch (fit unmeasured)')
    return '; '.join(parts)
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