akiiwa-games/AgentCompass / skills/agent-compass
agent-compass
FlaggedChoose 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.
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)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |