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/roll.py
View on GitHub"""roll: one command from a written task brief to a routed, launched worker.
The classifier reads the original brief; the worker receives it unchanged plus the communication contract.
Classification, allocation, the ledger record, dispatch preparation and launch happen here.
"""
import argparse
import hashlib
import json
import os
from pathlib import Path
import re
import shutil
import subprocess
import sys
import time
import uuid
import dispatch_fallback
import dispatch_flow
import entry
import dispatch_registry as registry
import host_placement
import host_policy
import launch_values
import provider_inventory
import caller_input
import public_data
import scorer_client
import subscription_cli
import turn_refusal
import usage_reading
import worker_context
import worker_sessions
from worker_context import NATIVE_HOSTS, harness_session, require_parent_id, resolve_parent
# Launcher families a configured Paseo provider may use: the dispatch adapter's own table, so a ready Grok/ACP
# definition is launched by Paseo instead of falling through to the CLI.
PASEO_LAUNCHER_FAMILIES = tuple(registry.PASEO_LAUNCHER_MODES)
SKILLS = Path(__file__).resolve().parents[2]
DOT_RUNNER = SKILLS / 'dot-subagent' / 'scripts' / 'run_dot_task.py'
CONSULT_BRIDGE = SKILLS / 'chatgpt-pro-consult' / 'scripts' / 'consult_bridge.py'
STATE_DIR = Path(os.environ.get('ROUTER_STATE_DIR') or Path.home() / '.agent-compass').expanduser()
CLI_RUNS_DIR = STATE_DIR / 'cli-workers'
WORKER_PROMPTS_DIR = STATE_DIR / 'worker-prompts'
RESULTS_DIR = STATE_DIR / 'roll-results'
WORKER_COMMUNICATION = SKILLS / 'agent-compass' / 'references' / 'worker-communication.md'
# Without Paseo, each CLI family runs one routed bundle unattended with full tool access, as Paseo would launch it:
# executable and flags for (model, effort, cwd). agy takes its prompt only as the argument after --print; the
# others read it from stdin; grok reads neither (headless ignores stdin) and takes --prompt-file.
CLI_RUNS = {
'claude': ('claude', lambda model, effort, cwd, fast=False: ['-p', '--model', model, *(['--effort', effort] if effort else []),
'--permission-mode', 'bypassPermissions',
'--settings', json.dumps({'fastMode': bool(fast)})]),
'codex': ('codex', lambda model, effort, cwd, fast=False: ['exec', '-m', model,
*(['-c', 'model_reasoning_effort=' + launch_values.toml_string(effort)] if effort else []),
'-c', 'features.fast_mode=' + str(bool(fast)).lower(),
'-c', 'service_tier="priority"' if fast else 'service_tier="default"',
'--dangerously-bypass-approvals-and-sandbox',
'--skip-git-repo-check', '-C', cwd, '-']),
'pi': ('pi', lambda model, effort, cwd, fast=False: ['-p', '--model', model if '/' in model else f'openai-codex/{model}', *(['--thinking', effort] if effort else [])]),
'antigravity-resilient': ('agy', lambda model, effort, cwd, fast=False: ['--dangerously-skip-permissions', '--model', model,
'--add-dir', cwd, '--print']),
'grok': ('grok', lambda model, effort, cwd, fast=False: ['--always-approve', '-m', model,
*(['--reasoning-effort', effort] if effort else []), '--cwd', cwd]),
'opencode': ('opencode', lambda model, effort, cwd, fast=False: [
'run', '-m', model if '/' in model else f'opencode/{model}',
*(['--variant', effort] if effort else []), '--dir', cwd]),
}
PROMPT_ARGUMENT = ('antigravity-resilient', 'opencode')
PROMPT_FILE = ('grok',)
# The caller's own session and subscription; a CLI worker gets its provider's, never these.
# The parent's session identity never reaches a CLI worker: the worker's own host sets its own.
HOST_SESSION_ENV = ('CLAUDE', 'CODEX_', 'PASEO_AGENT', *worker_context.OWN_SESSION_ID_VARS)
def title_of(text):
for line in text.splitlines():
line = line.strip().lstrip('#').strip()
if line:
return line[:60]
return 'task'
def read_task_text(args):
"""The assignment exactly as given: --brief file, --task text, or --task - for stdin (no command-line length limit)."""
if args.brief is not None:
return caller_input.read_bytes(args, args.brief).decode('utf-8-sig') # bytes, so CRLF is not rewritten
if args.task == '-':
return caller_input.stdin_bytes(args).decode('utf-8-sig')
return args.task
def build_task(args, text, parent, said=None):
"""The task `roll` routes. `said` (a list) receives what the caller's own flags decided that the caller would not
otherwise read: the assumptions of the answer."""
# Same brief, same parent -> same task_id, so a repeated roll cannot open a second live dispatch.
hours = getattr(args, 'hours', None)
if hours is not None and not (isinstance(hours, (int, float)) and not isinstance(hours, bool) and hours > 0 and hours != float('inf')):
raise ValueError('--hours must be a positive number of expected active hours.')
task = {'objective': text, # the classifier and the worker both get the whole text
'task_id': args.task_id or 'roll-' + hashlib.sha256(text.encode()).hexdigest()[:16],
# Where a new worker runs: an account's cwd_regex is about that directory (host_placement.worker_directory).
# A worker roll resumes runs in its own, which _run puts here once the registry names the worker
# (resumed_directory).
'cwd': host_placement.worker_directory(getattr(args, 'workspace', None))}
if hours is None:
# No extra model call: the allocator budgets the classifier's own expected_hours.
task['hours_source'] = 'classifier_estimate'
else:
task['expected_hours'] = float(hours)
if parent:
task['parent_agent_id'] = parent
if getattr(args, 'brief', None) is not None:
try:
task['brief_path'] = str(Path(args.brief).resolve())
except OSError:
task['brief_path'] = str(args.brief)
if getattr(args, 'local_only', None) is not None:
local_only_reason = str(args.local_only).strip()
if not local_only_reason:
raise ValueError('--local-only requires a non-empty reason.')
task['needs'] = {'local_only': True, 'local_only_reason': local_only_reason, 'local_only_by': '--local-only'}
elif getattr(args, 'workspace', None):
ws = host_placement.canonical_dir(args.workspace)
if ws:
task['needs'] = {'local_only': True, 'local_only_reason': f'inferred from --workspace {ws}',
'local_only_by': '--workspace'}
if said is not None:
said.append(f'--workspace {ws} places this work on this machine, so it is local-only: remote runners '
'(which work on a computer of their own) were not considered. Roll without --workspace if a '
'remote runner may take it.')
if getattr(args, 'file', None) or getattr(args, 'apply_to', None):
task.setdefault('needs', {})['file_transfer'] = True
if getattr(args, 'fast', False):
task.setdefault('needs', {})['fast'] = True
can_wait = getattr(args, 'can_wait_hours', None)
if can_wait is not None:
if not (isinstance(can_wait, (int, float)) and not isinstance(can_wait, bool) and can_wait >= 0
and can_wait != float('inf') and can_wait == can_wait):
raise ValueError('--can-wait-hours must be a non-negative number of hours.')
# One flag, two readers: the allocator's limit on a later start (five-axis wait logic), and how long a transient
# provider failure may be waited out before AgentCompass relaunches the brief on the next candidate
# (dispatch_fallback).
task['can_wait_hours'] = float(can_wait)
return task
def hours_assumption(args, decision):
"""Where the budgeted hours came from, in words that are true for every case; never a figure it does not have.
None when the caller gave --hours: their own figure is not an assumption."""
if getattr(args, 'hours', None) is not None:
return None
est = decision.get('hours_estimate') or {}
origin = {'classifier_estimate': 'the classifier estimate',
'caller_profile': "the caller's task profile (its expected_hours)"}.get(est.get('source'))
if origin and isinstance(est.get('hours'), (int, float)) and not isinstance(est.get('hours'), bool):
return (f"--hours not given: budgeted {est['hours']:g}h from {origin}; "
'an estimate, not a measurement. Pass --hours for a large or unusually small task.')
return ('--hours not given and no classifier estimate: no hours were budgeted, and none were invented. '
'Pass --hours, or roll again when the classifier answers.')
def is_readonly_review_profile(profile):
"""True when the classified profile describes a read-only review or audit that writes no repo code."""
if not isinstance(profile, dict):
return False
if 'read_only_review' in profile:
return bool(profile.get('read_only_review'))
return bool(profile.get('work_kind') == 'code_audit')
def independent_reviewers(workers):
"""Workers that may take a review: only those that have never written code in their history. A worker that
implemented or fixed the work would be reviewing itself, whatever brief overlap or chain points at it."""
out = []
for w in workers:
profiles = w.get('profiles') or ([w['profile']] if isinstance(w.get('profile'), dict) else [])
if profiles and not all(is_readonly_review_profile(p) for p in profiles):
continue
if isinstance(w.get('read_only_review'), bool):
if w['read_only_review'] is True:
out.append(w)
elif profiles:
out.append(w)
return out
def _resolve_worker_bundle(worker, accounts=None):
"""Return a copy of `worker['bundle']` with `bundle_id` resolved, or None if unresolvable."""
if not isinstance(worker, dict):
return None
raw = worker.get('bundle')
bundle = dict(raw) if isinstance(raw, dict) else {}
bid = bundle.get('bundle_id') or bundle.get('id') or worker.get('bundle_id')
if bid:
bundle['bundle_id'] = bid
bundle.setdefault('id', bid)
if not bundle.get('account'):
return None
if not (bundle.get('bundle_id') or bundle.get('id')):
if accounts is None:
import account_fleet
accounts = account_fleet.load_accounts()
resolved = registry.resolve_bundle(bundle, accounts, False)
if not resolved:
return None
bundle = {**bundle, **resolved}
return bundle
def named_route_conflict(args, bundle, accounts=None):
"""`roll --resume <id>` with model flags: None when every flag given names the worker's own route (they add nothing:
the turn is the explicit resume), else the error text. --resume names the worker, and its route is the worker's
own; a different named route contradicts it, so neither is chosen for the caller. Fast mode is part of the route:
--fast on a worker that runs without it is such a contradiction (the entry cannot tell an absent --fast from a plain
mode asked for, so only a given --fast is compared)."""
import account_fleet
import model_resolution
if accounts is None:
accounts = account_fleet.load_accounts()
if args.model not in (None, ''):
model_resolution.check_model_pin(args.model, '--model')
same_owner = args.account in (None, bundle.get('account')) and args.provider in (None, bundle.get('provider'))
pool = account_fleet.pin_pool(
accounts,
account=args.account if same_owner else bundle.get('account'),
provider=args.provider if same_owner else bundle.get('provider'),
extra=(bundle,),
)
as_read = account_fleet.effective_pin(args.model, pool, accounts) if args.model else None
model, named_effort = model_resolution.split_model_effort(as_read) if as_read else (None, None)
if model and not named_effort:
providers = account_fleet.bundle_providers(bundle, accounts) if '/' not in model else ()
named_effort = account_fleet.resolve_model(model, accounts, providers)['effort']
effort = args.effort or named_effort
# Each flag the caller gave that names another route than the worker's own; the error names only these.
conflicting = [flag for flag, differs in (
('--provider', args.provider and args.provider != bundle.get('provider')),
('--account', args.account and args.account != bundle.get('account')),
('--model', model and not account_fleet.pin_names_bundle(args.model, bundle, accounts, pool=pool)),
('--effort' if args.effort else '--model', effort and effort != bundle.get('effort')),
('--fast', getattr(args, 'fast', False) and not bundle.get('fast'))) if differs]
if not conflicting:
return None
own = f"{bundle.get('account')}/{bundle.get('model')}:{bundle.get('effort')}{', fast' if bundle.get('fast') else ''}"
flags = ' and '.join(dict.fromkeys(conflicting))
return (f"--resume names the worker and its route is the worker's own ({own}); drop {flags}, or roll "
'without --resume to launch the named route.')
GATE_CHECK_FAILED = 'the check itself failed: '
def gate_refusal_text(explicit_id, reason):
"""The refusal of a turn to the worker the caller named, in words that blame the worker only for a fact about it."""
if reason.startswith(GATE_CHECK_FAILED):
return (f'Nothing was launched: the quota and gate check for worker {explicit_id!r} could not be completed '
f'({reason[len(GATE_CHECK_FAILED):]}). That is a fault of the request or of the local data, not a state of '
'the worker: fix it and roll --resume again.')
return (f'Nothing was launched: worker {explicit_id!r} cannot take a new turn ({reason}). '
'Omit --resume to start a fresh worker.')
def _worker_gate_refusal(worker, usage_cache_path=None, accounts=None):
"""Gate-enforced refusal for continuing `worker`, or None when permitted. Fails closed if unresolvable."""
if accounts is None:
import account_fleet
accounts = account_fleet.load_accounts()
bundle = _resolve_worker_bundle(worker, accounts)
if bundle is None or not (bundle.get('bundle_id') or bundle.get('id')):
return 'worker bundle could not be resolved'
try:
return turn_refusal.gate_refusal(
worker['agent_id'],
usage_cache_path=usage_cache_path,
bundle=bundle,
dispatch_id=worker.get('dispatch_id'),
accounts=accounts,
)
except ValueError as exc:
# `worker_not_resolvable` is a fact about the worker (turn_refusal); any other ValueError is a fault of the request
# or of the local data met while checking it, and says nothing about the worker.
text = str(exc) or 'worker_not_resolvable'
return text if text == 'worker_not_resolvable' else GATE_CHECK_FAILED + text
def worker_cwd_spec(worker, accounts):
"""The account a resumed worker's turn runs on, as candidate_eval reads its cwd_regex, and that account's spec."""
import accounts_override
bundle = _resolve_worker_bundle(worker, accounts)
if bundle is None:
return None, {}
account = accounts_override.preference_account(bundle, bundle['account'], accounts)
return account, accounts['accounts'].get(account) or {}
def resumed_directory(task, workspace, worker, said):
"""Put the directory the explicitly resumed `worker` runs in into `task['cwd']` (host_placement.worker_directory),
or return the refusal when it is not known and the worker's account has a cwd_regex: that is the user's own
boundary, which neither a named route nor a named worker reaches past (as _auto_resumable refuses the same state).
Unknown on an unrestricted account, nothing is lifted: the task says so (`cwd_unread`) and so does `said`."""
own = host_placement.worker_directory(workspace, worker)
if own:
task['cwd'] = own
return None
import account_fleet
account, spec = worker_cwd_spec(worker, account_fleet.load_accounts())
agent_id = worker.get('agent_id')
if spec.get('cwd_regex'):
return (f'Nothing was launched: the directory of worker {agent_id!r} is not known on this machine (neither its '
f'Paseo record nor its dispatches name one), and account {account} is restricted to directories matching '
f"its cwd_regex {spec['cwd_regex']!r} (the user's own account setting on this machine), which neither a "
'named route nor a named worker reaches past. Omit --resume to start a fresh worker.')
task.pop('cwd', None)
task['cwd_unread'] = True
said.append(f'The directory of worker {agent_id!r} is not known on this machine (neither its Paseo record nor its '
f'dispatches name one); account {account} has no cwd_regex, so no directory was matched for this turn: '
'the worker resumes in its own directory.')
return None
def _auto_resumable(worker, policy, usage_cache_path=None, accounts=None):
"""Whether roll may resume `worker` without being told to. Resuming is then the router's choice, so the two
preference switches apply as they do to a plan: the account takes part in automatic routing on this host
(`host_policy.account_allowed`) and the worker's model is not unchecked in model management. The gate must admit
the turn too. The plan matched the account's `cwd_regex` against the directory a new worker would get, and the
worker resumed instead runs in its own (host_placement.worker_directory), which the restriction must admit too: one
that cannot be read is not resumed automatically. An explicit `--resume` is the caller's choice and reads only the
gate (`_worker_gate_refusal`); its plan is matched against the worker's own directory (resumed_directory)."""
import account_fleet
if accounts is None:
accounts = account_fleet.load_accounts()
bundle = _resolve_worker_bundle(worker, accounts)
if bundle is None or not host_policy.account_allowed(policy, bundle.get('account')):
return False
_, cwd_spec = worker_cwd_spec(worker, accounts)
if cwd_spec.get('cwd_regex'):
own = host_placement.worker_directory(None, worker)
if not own or not account_fleet.account_cwd_allowed(cwd_spec, own):
return False
rows = [r for r in account_fleet.bundle_rows(accounts, bundle.get('bundle_id') or bundle.get('id'))
if r['account'] == bundle.get('account')]
if host_policy.disabled_cause(bundle['account'], rows, accounts):
return False
return not _worker_gate_refusal(worker, usage_cache_path=usage_cache_path, accounts=accounts)
def workspace_mismatch_text(agent_id, own_dir, requested):
return (f'Nothing was launched: worker {agent_id!r} works in {own_dir}, and --workspace names {requested}; a '
'worker is resumed only in its own directory, and no other worker was started in its place. Drop '
f'--workspace to resume it where it works, or roll without --resume to start a worker in {requested}.')
def _not_reusable_text(explicit_id, parent, excluded):
"""What a caller reads when the worker it names is not one its parent can resume: the reason the registry gives."""
refusal = (registry.Refusal('an earlier attempt of this roll already tried it',
'It failed this roll: roll without --resume to start a fresh worker.')
if explicit_id in excluded
else registry.reuse_refusal(parent, explicit_id)
or registry.Refusal('it is not an idle worker of this parent', 'Roll without --resume to start a fresh worker.'))
return (f'Nothing was launched: worker {explicit_id!r} cannot be resumed by parent {parent!r}: {refusal.reason}. '
f'{refusal.remedy}')
def _resume_refusal(out, explicit_id, error, next_text, code=2):
return dict(out, launched=False, dispatch_mode='paseo', caller_action='roll_fresh_worker',
error=error, agent_id=explicit_id, next=next_text), code
def match_reusable_worker(args, task, text=None, parent=None, workers=None):
"""Select an idle Paseo worker of `parent` for structured continuation:
(1) explicit `--resume <agent_id>`, (2) explicit `task['chain']`, (3) exact `task_id` or `brief_path` equality,
or (4) same canonical `--workspace`."""
del text
explicit_id = (getattr(args, 'resume', None) or '').strip()
if explicit_id and getattr(args, 'new_worker', False):
return None
if not parent or getattr(args, 'new_worker', False):
return None
excluded = set(getattr(args, '_exclude_agents', None) or ())
workers = [w for w in (registry.reusable_workers(parent, named=explicit_id or None) if workers is None else workers)
if w.get('agent_id') not in excluded]
if explicit_id:
return next((w for w in workers if w.get('agent_id') == explicit_id), None)
if not workers or not isinstance(task, dict):
return None
raw_chain = task.get('chain')
chain = raw_chain if isinstance(raw_chain, dict) else None
chain_agent_id = ''
chain_id = (task.get('chain_id') or (raw_chain if isinstance(raw_chain, str) else '') or '').strip()
if chain:
chain_worker = chain.get('worker') if isinstance(chain.get('worker'), dict) else {}
chain_agent_id = (chain_worker.get('agent_id') or '').strip()
chain_id = (chain.get('id') or chain_id or '').strip()
if chain_agent_id:
matched = next((w for w in workers if w.get('agent_id') == chain_agent_id), None)
if matched is not None:
return matched
if chain_id:
eligible = [((not w.get('worn', False), w.get('updated_at') or ''), w)
for w in workers
if w.get('chain_id') == chain_id or chain_id in (w.get('chain_ids') or ())]
if eligible:
return max(eligible, key=lambda item: item[0])[1]
task_id = task.get('task_id')
brief_path = task.get('brief_path')
if brief_path or getattr(args, 'task_id', None) or task_id:
eligible = []
for w in workers:
if (task_id and task_id in (w.get('task_ids') or ())) or (brief_path and brief_path in (w.get('brief_paths') or ())):
eligible.append(((not w.get('worn', False), w.get('updated_at') or ''), w))
if eligible:
return max(eligible, key=lambda item: item[0])[1]
workspace = host_placement.canonical_dir(getattr(args, 'workspace', None) or task.get('workspace'))
if workspace:
eligible = []
for w in workers:
w_ws = host_placement.canonical_dir(w.get('workspace'))
w_cwd = host_placement.canonical_dir(w.get('cwd'))
if workspace in (w_ws, w_cwd):
eligible.append(((not w.get('worn', False), w.get('updated_at') or ''), w))
if eligible:
return max(eligible, key=lambda item: item[0])[1]
return None
def _bundle_matches_worker(bundle, worker, same_model=None):
"""`same_model` compares resolved keys, so one model under two spellings is still this worker's."""
if not isinstance(bundle, dict) or not isinstance(worker, dict) or worker.get('worn'):
return False
w_bundle = worker.get('bundle') or {}
if bool(bundle.get('fast')) != bool(w_bundle.get('fast')):
return False
b_id = bundle.get('bundle_id') or bundle.get('id')
if b_id and worker.get('bundle_id') == b_id and not str(b_id).startswith('user_override_'):
return True
if not all(bundle.get(k) and bundle.get(k) == w_bundle.get(k) for k in ('provider', 'account', 'effort')):
return False
theirs, ours = w_bundle.get('model'), bundle.get('model')
return bool(ours) and (ours == theirs or bool(same_model and theirs and same_model(ours, theirs)))
def model_comparison(fleet):
"""Do two names run the same model? A spelling does, a family guess at its target does not."""
import account_fleet
return lambda a, b: account_fleet.row_key(a, fleet) == account_fleet.row_key(b, fleet)
def summary(decision):
bundle = decision.get('selected_bundle') or {}
out = {'choice': decision.get('choice'),
'bundle': {k: bundle[k] for k in ('provider', 'harness', 'account', 'model', 'effort', 'modeId', 'launch_model', 'fast', 'fast_billing') if bundle.get(k)},
'reason': ((decision.get('decision') or {}).get('reason') or '')[:300] or None,
'alerts': [a['message'] for a in decision.get('alerts') or [] if a.get('severity') == 'warn'],
**({'warnings': warnings} if (warnings := decision.get('warnings') or (decision.get('decision') or {}).get('warnings')) else {})}
return out
NAMED_ROUTE_FLAGS = ('provider', 'account', 'model', 'effort') # the flags that name a route (`--effort` is optional)
def named_route_given(args):
"""The flags the caller gave that name a route. A named route is a user override: `record_constraint` needs
`--provider`, `--account`, `--model` and `--basis` (the user's own words) for it."""
return [flag for flag in NAMED_ROUTE_FLAGS if getattr(args, flag, None)]
def named_route_refusal(args, require=False):
"""The one owner of what a named route needs (`route_judge.record_constraint` reads it). Why the flags the caller gave
do not make one, in one answer: what it needs, which of those were given and which are missing, and the other way out;
None when they do make one. With no route flag given it is None, unless `require`: the caller is recording a route.
A route named to `roll` is the user's own naming and nothing else: beside route flags, a `--constraint` other than
`user_override` (a project rule) is refused, since only `record` reads one and holds it to this machine's switches."""
given = named_route_given(args)
if not given and not require:
return None
constraint = getattr(args, 'constraint', None)
if given and not require and constraint not in (None, 'user_override'):
return (f"A route named to roll is the user's own naming, with their words in --basis; --constraint {constraint} "
f'is not that. Record a project rule with `record --constraint {constraint}` (held to this machine\'s '
'automatic-routing switches: host policy, the model checkbox and the dispatch cadence), or drop '
'--constraint when the user named this route in this request.')
basis = bool((getattr(args, 'basis', None) or '').strip())
missing = [f'--{flag}' for flag in ('provider', 'account', 'model') if flag not in given]
if not basis:
missing.append('--basis')
if not missing:
return None
gave = [f'--{flag}' for flag in given] + (['--basis'] if basis else [])
way_out = (f'drop {", ".join(f"--{flag}" for flag in given)}{" and --basis" if basis else ""} and let the router choose'
if given or basis else 'leave the route to the router')
return ('A named route needs --provider, --account, --model and --basis (the user\'s own words); --effort is optional. '
f'This request gave {", ".join(gave) or "none of them"} and is missing {", ".join(missing)}. Add the missing '
f'flags, or {way_out}.')
def ignored_flag_notes(args, decision, explicit_id):
"""What the caller gave that did not take effect, each in a sentence (never dropped in silence). Files are handled at
the launch (`files_not_sent`), where the provider is known."""
notes = []
bundle = decision.get('selected_bundle') or {}
if getattr(args, 'basis', None) and not named_route_given(args) and not explicit_id:
notes.append('--basis names no route by itself and was ignored: it only quotes the user for --provider, --account, '
'--model or --effort.')
if getattr(args, 'fast', False) and bundle and not bundle.get('fast'):
notes.append('--fast was not applied (it is a preference): '
+ ((decision.get('decision') or {}).get('fast_not_applied') or 'the chosen route runs in its plain mode') + '.')
return notes
def files_not_sent(out, args, provider):
"""--file / --apply-to name files for a remote runner; only Dot receives them. Any other route gets neither a copy nor
a mention of them."""
if provider == 'dot' or not (getattr(args, 'file', None) or getattr(args, 'apply_to', None)):
return out
return dict(out, warnings=[*out.get('warnings', []),
f'--file/--apply-to files were not sent: only Dot receives them, and the {provider} route gets neither '
'a copy nor a mention of them. Put what the worker needs from them in the brief.'])
def none_next(decision):
"""What a caller reads when no worker fits: when the plan found a candidate held back only by quota, which one, which
window and for how long, and the ways out; else where the closest candidates and their exclusions are."""
reset = (decision.get('decision') or {}).get('next_reset')
if reset:
return (f"Nothing can start now: {reset['bundle']} is held back by {reset['account']}'s {reset['window']} quota, which "
f"returns in {reset['hours']}h (at {reset['at']}). Wait that long and roll again, or do the task yourself, "
'or ask the user.')
settings = (decision.get('decision') or {}).get('local_settings')
if settings:
way = ("To use one on the user's word, name it with --provider, --account, --model and --basis (the user's own "
'words): a named route reaches past allowed_accounts and the model-management checkbox.'
if settings['named_route_reaches'] else
"An account's cwd_regex holds for a named route too.")
return ("No worker fits: only the user's own settings on this machine keep the closest candidates out ("
+ '; '.join(settings['exclusions']) + f"). They are the user's choice, not a fault. {way} Otherwise do the "
'task yourself or ask the user.')
return ('No worker fits this brief (route.reason lists the closest candidates and why each is excluded); do it yourself '
'or ask the user.')
def user_decision_next(decision):
"""What a caller reads when the router leaves the choice to the user: the plan's own reason, and the ways out that fit
the fact (a blocked chain owner, or a wait longer than --can-wait-hours allows)."""
plan = decision.get('decision') or {}
reason = plan.get('reason') or 'no reason was recorded'
wait = plan.get('wait_hours')
if plan.get('resume_blocked_by'):
wait_text = f'wait about {wait}h and roll again (keeps the one owner)' if wait is not None else 'wait and roll again (keeps the one owner)'
return (f'The router needs a user decision: {reason} Ask the user: {wait_text}, or roll with --new-worker to start a '
'fresh worker on another route now (handoff and drift risk).')
if wait is not None:
return (f'The router needs a user decision: {reason} Ask the user: wait {wait}h and roll again, allow a longer wait '
f'with --can-wait-hours {wait}, name a route (--provider --account --model --basis), or do the task yourself.')
return f'The router needs a user decision: {reason} Show this to the user.'
def defer_next(decision, wait):
plan = decision.get('decision') or {}
bundle = decision.get('selected_bundle') or {}
wait_for = plan.get('wait_for') or {}
window = (f"{wait_for['account']}'s {wait_for['window']} window" if wait_for.get('account') and wait_for.get('window')
else 'its quota window')
return (f"Defer {bundle.get('bundle_id') or bundle.get('id') or decision.get('choice')} for {wait}h until {window} "
'resets; do not launch now. To launch sooner roll again without --can-wait-hours (the best model that can start '
'now), name a route with --provider --account --model --basis, or do the task yourself.')
def paseo_choice(provider, parent_host, args):
"""`(use_paseo, why_not)`: whether this launch goes through Paseo, and the first condition that says no. Dot, ChatGPT
web and Grok Bot return before a Paseo launch and never grow a completion watcher; reachability is not asked for
them, so a remote roll does not dial the daemon."""
if provider in ('dot', 'chatgpt-web', 'grok-bot'):
return False, None
if parent_host in ('herdr', *NATIVE_HOSTS):
return False, f'the parent runs on {parent_host}, not on Paseo'
if not can_launch_via_paseo(provider):
return False, f'no Paseo launcher fits the provider {provider!r}'
if not (os.environ.get('PASEO_AGENT_ID', '').strip() or getattr(args, 'parent_id', None)):
return False, 'there is no Paseo parent: neither PASEO_AGENT_ID nor --parent-id is set'
if not (os.environ.get('PASEO_AGENT_ID', '').strip() or dispatch_flow.paseo_reachable()):
return False, 'the Paseo daemon is not reachable'
return True, None
def without_paseo(out, why):
return dict(out, warnings=[*out.get('warnings', []),
f'Paseo was not used: {why}. This worker runs through its own CLI, and nothing calls back.'])
def python(script, *argv):
return [sys.executable, '-X', 'utf8', str(script), *argv]
_INJECTED_FOOTER_RE = re.compile(
r'\n+---\n+(?:# Worker(?:-to-parent communication contract| 通信与汇报契约)\b[\s\S]*|'
r'Parent session agent ID: `[^`\n]+`\.\s*(?:Parent host:[^\n]*\n?)?)\Z'
)
def strip_injected_contract(text):
"""Strip any previously injected worker communication contract/footer so re-rolling or pre-pasted briefs do not duplicate it."""
if not isinstance(text, str):
return ''
cleaned = _INJECTED_FOOTER_RE.sub('', text)
cleaned = re.sub(
r'(?:\r?\n)+(?:---\r?\n+)?Parent session agent ID: `[^`\n]+`\.(?:\r?\nParent host: `[^`\n]+`\. Parent message address: `[^`\n]+`\.)?\s*\Z',
'',
cleaned,
)
return cleaned
def recipient_footer(parent, host='paseo', address=None):
parent = require_parent_id(parent)
return (f'Parent session agent ID: `{parent}`.\n'
f'Parent host: `{host}`. Parent message address: `{address or parent}`.')
def communication_contract(watched=False):
"""The shared rules plus the one channel this dispatch uses. The markdown is the only copy of the rule."""
text = WORKER_COMMUNICATION.read_text(encoding='utf-8')
watched_heading = '## 有完成监视'
unwatched_heading = '## 无完成监视'
watched_at = text.find('\n' + watched_heading)
unwatched_at = text.find('\n' + unwatched_heading)
if watched_at < 0 or unwatched_at < watched_at:
raise ValueError('worker communication contract is missing a channel section')
shared = text[:watched_at].rstrip() + '\n'
section = text[watched_at:unwatched_at] if watched else text[unwatched_at:]
return shared + '\n' + section.strip() + '\n'
def prepare_worker_prompt(text, parent, host='paseo', address=None, watched=False):
"""One channel for this launch; retain the source brief and a durable native-fallback prompt."""
base = strip_injected_contract(text)
recipient = recipient_footer(parent, host, address)
prompt = base + '\n\n---\n\n' + communication_contract(watched) + '\n' + recipient + '\n'
if host == 'herdr':
prompt += ('\nHerdr core return channel: send questions and [Worker final report] with the argument vector '
f'`hc send {parent} <message>`; check the send result. Finish this turn after reporting. '
'Your final reply alone is not a parent message. Do not use Paseo or user-dialog tools.\n')
WORKER_PROMPTS_DIR.mkdir(parents=True, exist_ok=True)
path = WORKER_PROMPTS_DIR / f'{uuid.uuid4()}.md'
path.write_bytes(prompt.encode('utf-8')) # no newline translation of the caller's text
return prompt, path
def prepare_resume_prompt(text, parent, host='paseo', address=None):
"""Resumed turns already received worker-communication.md in turn 1; send only the brief and parent address footer."""
base = strip_injected_contract(text)
recipient = recipient_footer(parent, host, address)
return base + '\n\n---\n\n' + recipient + '\n'
def dot(args, out, prompt_file, *, task=None, decision=None):
files = [str(f) for f in args.file]
target_cwd = str(args.apply_to or Path.cwd()) if files else None
apply_to = ['--apply-to', target_cwd] if target_cwd else []
command = python(DOT_RUNNER, 'run', '--prompt-file', str(prompt_file),
*[x for f in files for x in ('--file', f)], *apply_to, '--no-wait')
public_data.effect('dot worker launch') # marked before the runner starts: a launch is never repeated
proc = subprocess.run(command, capture_output=True, text=True, encoding='utf-8', errors='replace',
timeout=180)
found = re.search(r'task_id=(\S+)', proc.stderr)
launched = bool(found) or proc.returncode == 0
if launched and found and isinstance(decision, dict) and decision.get('decision_id'):
try:
registry.record_external_launch(
'dot',
found.group(1),
decision['decision_id'],
decision.get('selected_bundle') or {'provider': 'dot', 'account': 'dot', 'model': 'dot'},
parent_id=out.get('parent_id'),
task_id=(task or {}).get('task_id'),
profile=decision.get('task_profile') or (task or {}).get('profile'),
brief_path=(task or {}).get('brief_path'),
cwd=target_cwd,
)
except OSError:
pass
result = dict(out, launched=launched, dispatch_mode='dot',
caller_action='already_launched_do_not_respawn' if launched else 'check_error',
worker={'provider': 'dot', 'task_id': found.group(1) if found else None, 'exit': proc.returncode,
'reply': None, 'stderr': proc.stderr[-1500:] or None})
if not launched:
result.update(error=f'dot_runner_exit_{proc.returncode}', next=dot_failure_next(proc.returncode))
if launched:
result['next'] = ('Worker is ALREADY launched on Dot by roll. Do NOT call create_agent, Agent, '
'spawn_agent, or invoke_subagent; use continuation_argv or read worker.reply.')
if found:
result['continuation_argv'] = entry.argv('dot', 'status', '--task-id', found.group(1), '--wait', '120', *apply_to)
return result, 0 if launched and proc.returncode in (0, 3) else 1
# What the Dot runner's exit codes mean, by the runner's own documentation (skills/dot-subagent/SKILL.md, Outcomes; its
# EXIT_* constants): 0 completed or submitted, 1 failed, 2 usage or configuration, 3 still open.
DOT_EXIT_MEANING = {
1: 'the runner reports the task, or its call to dot2api, as failed',
2: 'the runner refused its arguments or could not read its configuration',
3: 'the runner reports the task as still open but printed no task id',
}
def dot_failure_next(code):
"""What a caller reads when the Dot runner started nothing: its exit code, what the runner means by it and where its
output is. The runner's own output is not repeated here: it can carry what the service answered, and a filter cannot
tell which lines are safe to show."""
meaning = DOT_EXIT_MEANING.get(code, 'the runner ended abnormally')
return (f'Nothing was launched on Dot: the runner exited {code} ({meaning}) without a task id, so there is no task to '
'observe. Its output is kept in the file `details` names (worker.stderr). Run the doctor command of the '
'dot-subagent skill (scripts/dot-subagent.cmd doctor) to check that dot2api is deployed and the credential is '
'accepted, then roll the brief again.')
def consult(args, out, prompt_file, *, task=None, decision=None):
base = args.brief if args.brief is not None else prompt_file
target = base.with_name(f'{base.stem}-consult-{time.strftime("%Y%m%d-%H%M%S")}')
given = ['--prompt', str(prompt_file), '--out', str(target)]
command = entry.argv('chatgpt-web', *given)
if isinstance(decision, dict) and decision.get('decision_id'):
# The one command that sends this consultation is handed over here and roll sees no later step, so the registry
# records the launch now: the account's dispatch cadence counts it (dispatch_registry.launch_record).
try:
registry.record_external_launch(
'chatgpt-web',
decision['decision_id'],
decision['decision_id'],
decision.get('selected_bundle') or {},
parent_id=out.get('parent_id'),
task_id=(task or {}).get('task_id'),
profile=decision.get('task_profile') or (task or {}).get('profile'),
brief_path=(task or {}).get('brief_path'),
cwd=None,
)
except OSError:
pass
# A browser consultation blocks for up to 30 minutes; hand over the one command instead of backgrounding it.
return dict(out, launched=False, dispatch_mode='chatgpt-web', caller_action='run_next_argv', next_argv=command,
next='Run next_argv (blocks until the answer is in <out>/response.md).'), 0
def grok_bot(args, out, prompt_file, task, bundle, *, decision=None):
"""Same external-runner receipt/continuation surface as Dot; no Paseo adapter."""
import run_grok_bot as runner
if args.file or args.apply_to or args.local_only or getattr(args, 'workspace', None):
raise ValueError('grok-bot runs remotely and accepts text only; local-only/file-transfer options are unsupported.')
if bundle.get('model') != 'grok-bot' or bundle.get('account') != 'grok-bot' or bundle.get('effort'):
raise ValueError('Use --provider grok-bot --account grok-bot --model grok-bot without an effort; upstream owns model selection.')
try:
public_data.effect('grok-bot worker launch') # marked before the runner starts: a launch is never repeated
receipt = runner.submit(prompt_file.read_text(encoding='utf-8'), out['parent_id'], task['task_id'])
except (runner.TransportError, OSError, ValueError) as exc:
return dict(out, launched=False, dispatch_mode='grok-bot', caller_action='check_error', error=str(exc)), 1
delivery = receipt['delivery']
completed = receipt['state'] == 'completed'
if receipt.get('task_id') and receipt.get('state') != 'failed' and isinstance(decision, dict) and decision.get('decision_id'):
try:
registry.record_external_launch(
'grok-bot',
receipt['task_id'],
decision['decision_id'],
bundle,
parent_id=out.get('parent_id'),
task_id=task.get('task_id'),
profile=decision.get('task_profile') or task.get('profile'),
brief_path=task.get('brief_path'),
cwd=None,
completed=completed,
)
except OSError:
pass
result = dict(out, launched=True if completed or delivery == 'accepted' else False if delivery == 'rejected' else None,
dispatch_mode='grok-bot', completed=completed, worker=receipt,
caller_action='completed' if completed else 'already_launched_do_not_respawn' if delivery == 'accepted' else
'check_delivery_do_not_resend' if delivery == 'unknown' else 'check_error')
if receipt['state'] not in ('completed', 'failed'):
result['continuation_argv'] = entry.argv('grok-bot', 'status', '--task-id', receipt['task_id'], '--wait', '30')
result['next'] = 'Read continuation_argv; never repeat an uncertain send. Relay needs_input to the parent; resolve cards in the official app.'
return result, 1 if receipt['state'] == 'failed' else 0
def settle_claim(claim_row, res, refusal):
"""A host claim after its start: stamped launched when the worker started, or may have (Herdr's uncertain send,
`launched` None); canceled with `refusal` when nothing started (`launched` False)."""
if res.get('launched') is False:
registry.settle_host_claim(claim_row['dispatch_id'], 'canceled', refusal)
else:
registry.host_claim_launched(claim_row['dispatch_id'])
def task_access(args, read_only_review=None):
"""--access wins, then the classifier's access / read_only_review, and anything else writes: a wrong block is loud
and has a way out, a wrong exemption silently lets a second writer in."""
explicit = getattr(args, 'access', None)
if explicit:
return 'read_only' if explicit == 'read-only' else 'write'
if isinstance(read_only_review, dict):
classified = read_only_review.get('access')
if classified in ('read-only', 'read_only'):
return 'read_only'
if classified == 'write':
return 'write'
read_only_review = read_only_review.get('read_only_review')
if read_only_review in ('read-only', 'read_only'):
return 'read_only'
if read_only_review == 'write':
return 'write'
return 'read_only' if read_only_review is True else 'write'
def same_cwd_warning(out, cwd, parent):
"""Without `--workspace`, parallel workers commonly start in one checkout and create their own worktrees, so
other unsettled writers in `cwd` are reported as a warning and block nothing."""
others = registry.writers_at(cwd, caller=parent)
if not others:
return out
named = '; '.join(f"{h.get('state')} dispatch {h.get('dispatch_id')} ({h.get('title')})" for h in others)
note = f'{cwd} already has unsettled writer dispatches and this worker will also write there: {named}.'
return dict(out, assumptions=[*out.get('assumptions', []), note], warnings=[*out.get('warnings', []), note])
def workspace_blocked(out, workspace, holders, dispatch_mode='paseo', resumable_ids=None):
named = '; '.join(f"{h.get('state')} dispatch {h.get('dispatch_id')} (agent {h.get('agent_id') or 'not created yet'})" for h in holders)
idle_resume = [h['agent_id'] for h in holders if h.get('agent_id') and h.get('agent_id') in (resumable_ids or ())]
if idle_resume:
resume_hint = ' or '.join(f'--resume {aid}' for aid in idle_resume)
action_hint = f'Resume the idle worker with {resume_hint}, or create a separate worktree for parallel work.'
else:
action_hint = 'Wait for it to finish, then roll this brief again, or create a separate worktree for parallel work.'
return dict(out, launched=False, dispatch_mode=dispatch_mode, caller_action='resolve_workspace_writer',
error='workspace_has_active_writer', blocked_by=holders,
next=f'Nothing was launched: workspace {workspace} already has a writer: {named}. {action_hint} '
'If this brief only reads, roll it with --access read-only.'), 2
def placement_refused(out, dispatch_mode, placed):
return dict(out, launched=False, dispatch_mode=dispatch_mode, caller_action=placed['caller_action'],
error=placed['error'], next=placed['next']), 1
def paseo(args, out, decision, task, text, parent, usage, judge=None):
dispatch_flow.reconcile()
decision_profile = (
decision.get('task_profile')
or ((decision.get('decision') or {}).get('task') or {}).get('profile')
or task.get('profile')
)
is_ro_review = is_readonly_review_profile(decision_profile)
access = task_access(args, decision_profile if isinstance(decision_profile, dict) else None)
workspace = host_placement.canonical_dir(getattr(args, 'workspace', None))
probe = None
holders = []
if workspace:
if access == 'write':
holders, unavailable, probe = dispatch_flow.workspace_holders(workspace, parent)
if probe and probe.get('placeable') is False:
return placement_refused(out, 'paseo', host_placement.place('paseo', workspace, paseo_probe=probe))
if unavailable:
out = dict(out, assumptions=[*out.get('assumptions', []),
f'Running agents in workspace {workspace} could not be read ({unavailable}); only recorded dispatches were checked.'])
else:
# A reader holds no claim on the directory: only the placement is read (the holders are not its conflict).
_, unavailable, probe = dispatch_flow.workspace_holders(workspace, parent)
if probe and probe.get('placeable') is False:
return placement_refused(out, 'paseo', host_placement.place('paseo', workspace, paseo_probe=probe))
if unavailable:
out = dict(out, assumptions=[*out.get('assumptions', []),
f'Paseo could not be read for workspace {workspace} ({unavailable}); the '
'placement there was not verified, and the worker is started with that cwd.'])
resume_agent_id = None
resumed_worker = None
resume_bundle = None
explicit_id = (getattr(args, 'resume', None) or '').strip()
if explicit_id and getattr(args, 'new_worker', False):
return _resume_refusal(out, explicit_id, 'conflicting_flags',
'Cannot combine --resume and --new-worker; pass one or the other.', code=1)
excluded = set(getattr(args, '_exclude_agents', None) or ())
all_reusable = [w for w in registry.reusable_workers(parent, named=explicit_id or None)
if w.get('agent_id') not in excluded]
import account_fleet
fleet = account_fleet.load_accounts()
same_model = model_comparison(fleet)
usage_cache_path = getattr(args, 'usage_cache', None)
if explicit_id:
explicit_worker = next((w for w in all_reusable if w.get('agent_id') == explicit_id), None)
if explicit_worker is None:
return _resume_refusal(
out, explicit_id, 'resume_worker_unavailable', _not_reusable_text(explicit_id, parent, excluded),
)
if is_ro_review and not independent_reviewers([explicit_worker]):
return _resume_refusal(
out, explicit_id, 'resume_writer_for_review',
f'Nothing was launched: worker {explicit_id!r} previously wrote or modified code and cannot be resumed '
'for an independent read-only review. Omit --resume to start a fresh reviewer.',
)
if explicit_worker.get('worn') or (decision.get('decision') or {}).get('action') == 'rotate':
return _resume_refusal(
out, explicit_id, 'resume_worker_worn',
f'Nothing was launched: worker {explicit_id!r} reached the context rotation limit and cannot be resumed. '
'Write a handoff brief and omit --resume to start a fresh worker.',
)
if gate_reason := _worker_gate_refusal(explicit_worker, usage_cache_path=usage_cache_path, accounts=fleet):
return _resume_refusal(out, explicit_id, 'resume_worker_gated', gate_refusal_text(explicit_id, gate_reason))
selected_bundle = decision.get('selected_bundle') or {}
if not _bundle_matches_worker(selected_bundle, explicit_worker, same_model):
routed_id = selected_bundle.get('bundle_id') or selected_bundle.get('id')
worker_bid = explicit_worker.get('bundle_id')
warn = (f'Resuming worker {explicit_id!r} on its existing bundle {worker_bid!r} as requested (--resume); '
f'the router would otherwise have chosen {routed_id!r}.')
out = dict(out, warnings=[*out.get('warnings', ()), warn])
resume_agent_id, resumed_worker = explicit_id, explicit_worker
resume_bundle = _resolve_worker_bundle(explicit_worker, fleet)
elif not getattr(args, 'new_worker', False) and (decision.get('decision') or {}).get('action') != 'rotate':
selected_bundle = decision.get('selected_bundle') or {}
policy = host_policy.load_policy()
compatible = [w for w in all_reusable
if _bundle_matches_worker(selected_bundle, w, same_model)
and _auto_resumable(w, policy, usage_cache_path=usage_cache_path, accounts=fleet)]
if is_ro_review:
compatible = independent_reviewers(compatible)
chain_worker_id = (((task.get('chain') or {}).get('worker') or {}).get('agent_id')
if isinstance(task.get('chain'), dict) else None)
chained = next((w for w in compatible if chain_worker_id and w['agent_id'] == chain_worker_id), None)
resumed_worker = chained or (compatible and match_reusable_worker(args, task, text, parent, workers=compatible)) or None
resume_agent_id = resumed_worker['agent_id'] if resumed_worker else None
if workspace and access == 'write':
remaining_holders = [h for h in holders if not (resume_agent_id and h.get('agent_id') == resume_agent_id)]
if remaining_holders:
resumable_ids = {
w['agent_id'] for w in all_reusable
if not w.get('worn') and not _worker_gate_refusal(w, usage_cache_path=usage_cache_path, accounts=fleet)
}
return workspace_blocked(out, workspace, remaining_holders, dispatch_mode='paseo', resumable_ids=resumable_ids)
# A resumed worker without --workspace stays where it lives, whatever the parent's directory (None: not read).
default_cwd = host_placement.worker_directory(None, resumed_worker)
placed = host_placement.place('paseo', workspace, default_cwd=default_cwd, paseo_probe=probe)
if not placed['ok']:
return placement_refused(out, 'paseo', placed)
landing = placed['cwd']
if not workspace and landing and access == 'write':
out = same_cwd_warning(out, landing, parent)
prompt_for_launch = (prepare_resume_prompt(text, parent, out.get('parent_host') or 'paseo', out.get('parent_address'))
if resume_agent_id else text)
launch = {'title': args.title or title_of(text), 'initialPrompt': prompt_for_launch, **placed['launch']}
try:
row = registry.prepare(decision['decision_id'], task, launch, usage,
resume_agent_id=resume_agent_id, fallback_prompt=text if resume_agent_id else None,
access=access,
new_worker=bool(getattr(args, 'new_worker', False)),
workspace=workspace, cwd=landing,
resume_bundle=resume_bundle,
explicit_resume=bool(explicit_id))
except registry.WorkspaceBusy as busy:
return workspace_blocked(out, busy.workspace, busy.holders, dispatch_mode='paseo')
except registry.ResumedWorkerBusy as busy:
return _resume_refusal(
out, busy.agent_id, 'resume_worker_unavailable',
f'Nothing was launched: worker {busy.agent_id!r} already has an active dispatch and is not idle. '
'Wait for that dispatch to finish (its next_argv, or `agentcompass dispatch --dispatch-action reconcile`), '
'then roll --resume again.',
)
except registry.CapacityChanged as refused:
if explicit_id:
return _resume_refusal(out, explicit_id, 'resume_worker_gated', gate_refusal_text(explicit_id, str(refused)))
if not dispatch_fallback.enabled() or judge is None:
raise
# The routed bundle could no longer start (e.g. its live model list dropped it): the next candidate does.
fresh = dict(launch, initialPrompt=text)
outcome = dispatch_fallback.after_refusal(decision['decision_id'], fresh, refused, access=access,
workspace=workspace, cwd=landing, judge=judge)
return fallback_result(out, outcome, decision, parent, args)
except ValueError as refused:
if not explicit_id:
raise
# A blocked result with the refusal's own text, never an uncaught exception. What refused is the request or the
# local data (an expired decision, a configuration row that is gone, a missing profile), not a state of the worker.
return _resume_refusal(
out, explicit_id, 'resume_worker_unavailable',
f'Nothing was launched: the turn for worker {explicit_id!r} could not be prepared: {refused}. That is a fault '
'of the request or of the local data, not a state of the worker: fix it and roll --resume again.',
)
receipt = dispatch_flow.launch(row['dispatch_id'], parent, watch_seconds=0)
if explicit_id and receipt.get('state') in ('failed', 'create_failed'):
# The named worker did not take the turn (the host refused the resume) or failed on it: nothing was started in
# its place, and nothing will be (dispatch_flow, dispatch_fallback `worker_named`).
cause = receipt.get('cause') or receipt.get('error') or receipt.get('state')
detail = receipt.get('refusal_detail') or {}
worker_out = dict(out, worker=dict(receipt, provider=decision['selected_bundle']['provider']))
if receipt.get('error') == 'worker_workspace_mismatch':
return _resume_refusal(worker_out, explicit_id, 'resume_workspace_mismatch', workspace_mismatch_text(
explicit_id, detail.get('worker') or 'an unknown directory', detail.get('requested') or landing))
differs = (f": the worker has {detail.get('worker')}, this turn asked for {detail.get('requested')}"
if detail else '')
condition = receipt.get('refusal_condition')
return _resume_refusal(
worker_out, explicit_id, 'resume_worker_unavailable',
f"Worker {explicit_id!r} did not take this turn ({cause}{' / ' + condition if condition else ''}{differs}); "
'no other worker was started in its place. '
+ (receipt.get('next_action') or dispatch_flow.resume_refusal_next(cause, condition)))
if (receipt.get('state') == 'create_failed' or (receipt.get('state') == 'failed' and receipt.get('agent_id'))) \
and dispatch_fallback.enabled() and judge is not None:
# Paseo confirms no worker runs this brief any more (none was created, or it ended in error while roll watched):
# AgentCompass retries or relaunches it on the next candidate instead of asking the parent. The bridge's watcher
# may see the same failure; whichever claims it first relaunches and the other reads that outcome.
return fallback_result(out, dispatch_fallback.handle(row['dispatch_id'], judge=judge), decision, parent, args)
if (
receipt.get('state') == 'failed'
and receipt.get('error') == 'parent_agent_not_found'
and not os.environ.get('PASEO_AGENT_ID', '').strip()
and judge is not None
):
try:
claim_row = registry.record_host_claim(
'cli', decision, task, decision['selected_bundle'],
label=args.title or title_of(text),
usage=usage, access=access, workspace=workspace, cwd=landing,
)
except registry.WorkspaceBusy as busy:
return workspace_blocked(out, busy.workspace, busy.holders, dispatch_mode='cli')
# The Paseo parent was not on the host, so this launch has no completion watcher. Rebuild the unwatched contract.
text, prompt_file = prepare_worker_prompt(text, parent, 'cli', out.get('parent_address'))
out['worker_prompt_file'] = str(prompt_file)
res, code = cli(args, without_paseo(out, 'Paseo does not know the parent agent (parent_agent_not_found)'),
decision['selected_bundle'], text)
settle_claim(claim_row, res, 'cli_not_launched')
return res, code
failed = receipt.get('state') in ('failed', 'create_failed')
# launched_at records the single-use claim, before create is sent. Only a
# validated host observation binds agent_id/observed_at to this dispatch.
confirmed = bool(receipt.get('agent_id') and receipt.get('observed_at'))
ended_before_send = (receipt.get('state') in ('canceled', 'expired') and not receipt.get('launched_at'))
removed = receipt.get('state') == 'canceled' and bool(receipt.get('next_action'))
uncertain = not failed and not confirmed and not ended_before_send and not removed
if uncertain:
receipt = dict(receipt)
receipt.setdefault('continuation_argv', entry.argv(
'launch', '--dispatch-id', row['dispatch_id'], '--parent-id', parent, '--watch-seconds', '120'))
return dict(out, launched=None, dispatch_mode='paseo', caller_action='check_delivery_do_not_resend',
next=receipt.get('next_action') or
'Paseo delivery is unconfirmed. Run worker.continuation_argv to observe this same dispatch; '
'do not roll again or issue another create request.',
worker=dict(receipt, provider=decision['selected_bundle']['provider'])), 0
if ended_before_send:
return dict(out, launched=False, dispatch_mode='paseo', caller_action='check_error',
next=f"Dispatch {receipt['state']} before a launch was sent; inspect its receipt before scheduling new work.",
worker=dict(receipt, provider=decision['selected_bundle']['provider'])), 2
if removed:
return dict(out, launched=False, dispatch_mode='paseo', caller_action='check_error', next=receipt['next_action'],
worker=dict(receipt, provider=decision['selected_bundle']['provider'])), 2
if receipt.get('state') == 'create_failed':
action = 'check_error' if receipt.get('next_action') == dispatch_flow.REQUEST_CREATE_FAILED_NEXT else 'roll_again_safe'
return dict(out, launched=False, dispatch_mode='paseo', caller_action=action, next=receipt['next_action'],
worker=dict(receipt, provider=decision['selected_bundle']['provider'])), 1
notification = receipt.get('completion_notification') or {}
notice = ('A completion notification will be sent to the parent on finish/error/permission, and that notice '
'contains the worker\'s final reply. Finish any independent work and end your turn to wait for it; '
'do not sleep or poll (paseo ls, get_agent_status, or result files) in a shell command. '
'The bounded watcher PID, deadline and durable receipt are in worker.completion_notification. '
'Use worker.continuation_argv to recover observation if that watcher stops.') \
if notification.get('status') == 'watching' else \
('The completion notification has been delivered to the parent; read that notification instead of waiting or polling.'
if notification.get('status') == 'delivered' else
'No active completion notification is confirmed. The caller must collect the result using '
'worker.continuation_argv or get_agent_activity; do not wait for an unsolicited callback.')
return dict(out, launched=not failed, dispatch_mode='paseo',
caller_action='already_launched_do_not_respawn' if not failed else 'check_error',
next=('Worker is ALREADY launched in Paseo by roll. Do NOT call create_agent, Agent, '
'spawn_agent, or invoke_subagent again. ' + notice) if not failed else
('Paseo launch failed: ' + (receipt.get('error') or 'worker failed') + '. ' +
('Repair the local notifier dependencies/state directory, then roll the brief again.'
if receipt.get('error') == 'notification_start_failed' else receipt.get('next_action') or notice)),
worker=dict(receipt, provider=decision['selected_bundle']['provider'])), \
1 if failed else 0
def fallback_result(out, outcome, decision, parent, args):
"""roll's answer once dispatch_fallback has relaunched the brief or found nothing left to start it on."""
attempts = outcome.get('lines') or []
if outcome.get('action') == 'relaunched':
dispatch_id = outcome['dispatch_id']
receipt = dispatch_flow.public_chain(registry.inspect(dispatch_id))
receipt.update({k: v for k, v in (outcome.get('receipt') or {}).items()
if k in ('completion_notification', 'error', 'cause', 'observe_error')})
bundle = registry.inspect(dispatch_id)['bundle']
route = dict(out.get('route') or {}, bundle={k: bundle[k] for k in (
'provider', 'harness', 'account', 'model', 'effort', 'modeId', 'launch_model', 'fast') if bundle.get(k)})
out = dict(out, route=route, attempts=attempts)
worker = dict(receipt, provider=bundle['provider'], attempts=attempts)
if receipt.get('state') in ('launching', 'expired') and not receipt.get('agent_id'):
worker.setdefault('continuation_argv', entry.argv(
'launch', '--dispatch-id', dispatch_id, '--parent-id', parent, '--watch-seconds', '120'))
return dict(out, launched=None, dispatch_mode='paseo', caller_action='check_delivery_do_not_resend',
next=receipt.get('next_action') or 'Paseo delivery of the relaunch is unconfirmed. Run '
'worker.continuation_argv to observe it; do not roll again.', worker=worker), 0
notification = receipt.get('completion_notification') or {}
notif_status = notification.get('status')
if notif_status == 'watching':
notif_text = ('A completion notification will be sent to the parent; finish any independent work and '
'end your turn to wait for it instead of sleeping or polling in a shell command.')
elif notif_status == 'delivered':
notif_text = ('The completion notification has been delivered to the parent; read that notification '
'instead of waiting or polling.')
else:
notif_text = 'No completion notification is confirmed: run worker.continuation_argv to collect the result.'
return dict(out, launched=True, dispatch_mode='paseo', caller_action='already_launched_do_not_respawn',
next=('The routed model failed to start, so AgentCompass relaunched the brief on the next candidate '
f'({bundle.get("model")} on {bundle.get("account")}). Do NOT call create_agent, Agent, '
'spawn_agent, or invoke_subagent again. ' + notif_text),
worker=worker), 0
if outcome.get('action') == 'final' and outcome.get('result') in ('blocked', 'owner_named'):
return dict(out, launched=False, dispatch_mode='paseo', caller_action='tell_user', error='no_candidate_left'
if outcome['result'] == 'blocked' else 'owner_named_model_failed', attempts=attempts,
next=outcome.get('text'),
worker={'provider': (decision.get('selected_bundle') or {}).get('provider'),
'dispatch_id': outcome.get('root_dispatch_id'), 'attempts': attempts,
'next_action': outcome.get('text')}), 2
if outcome.get('action') in ('pending', 'scheduled'):
# pending: the bridge's watcher claimed this failure first and is relaunching the brief. scheduled: a transient
# failure whose same-model retry starts at retry_at, from the watcher or the next observation.
root = outcome.get('root_dispatch_id')
scheduled = outcome['action'] == 'scheduled'
text = (dispatch_flow.FALLBACK_SCHEDULED_NEXT.format(retry_at=outcome.get('retry_at')) if scheduled
else dispatch_flow.FALLBACK_RUNNING_NEXT.format(where='its watcher is starting the next attempt'))
return dict(out, launched=None, dispatch_mode='paseo', caller_action='check_delivery_do_not_resend',
attempts=attempts, **({'retry_at': outcome.get('retry_at')} if scheduled else {}), next=text,
worker={'dispatch_id': root, 'attempts': attempts, 'next_action': text,
**({'retry_at': outcome.get('retry_at')} if scheduled else {}),
'continuation_argv': entry.argv(
'launch', '--dispatch-id', root, '--parent-id', parent, '--watch-seconds', '120')}), 0
# Declined (not a failure AgentCompass relaunches) or unsettled: the last attempt's own receipt says what to do.
last = next((a.get('dispatch_id') for a in reversed(outcome.get('attempts') or []) if a.get('dispatch_id')), None)
last_row = registry.inspect(last) if last else None
receipt = dispatch_flow.public_chain(last_row) if last_row else {}
cause = dispatch_flow.failure_cause(last_row) if last_row else None
return dict(out, launched=False, dispatch_mode='paseo', caller_action='check_error', attempts=attempts,
error=cause or receipt.get('state') or outcome.get('action'),
next=receipt.get('next_action') or outcome.get('text') or 'The relaunch could not be prepared; tell the user.',
worker=dict(receipt, provider=(decision.get('selected_bundle') or {}).get('provider'),
attempts=attempts)), 1
def _router_override_proxy_spec(provider):
state_dir = Path(os.environ.get('ROUTER_STATE_DIR') or Path.home() / '.agent-compass')
override_env = os.environ.get('AGENTCOMPASS_ACCOUNTS_OVERRIDE')
override_path = Path(override_env).expanduser() if override_env else state_dir / 'accounts-override.json'
import accounts_override
doc = accounts_override.load_override(override_path) or {}
accounts = doc.get('accounts') if isinstance(doc, dict) else None
spec = accounts.get(provider) if isinstance(accounts, dict) else None
if not isinstance(spec, dict):
return None
if str(spec.get('billing') or '').strip().lower() != 'metered':
return None
endpoint = str(spec.get('endpoint') or '').strip()
key = str(spec.get('api_key') or '').strip()
if endpoint and key:
return spec
return None
native_next = host_placement.native_next
def can_launch_via_paseo(provider):
family = provider_inventory.launcher_family(provider)
providers = (dispatch_flow.paseo_config().get('agents') or {}).get('providers')
if provider == family or (isinstance(providers, dict) and provider in providers):
return family in PASEO_LAUNCHER_FAMILIES
if _router_override_proxy_spec(provider) is not None:
return False
return family in ('claude', 'codex')
def account_home(provider):
"""The home discovery resolved for an extra Claude/Codex account, else the conventional ~/.<provider>."""
row = (provider_inventory.current().get('accounts') or {}).get(provider) or {}
return str(row.get('home') or Path.home() / f'.{provider}')
def provider_definition(provider, bundle=None):
"""Paseo's definition of a provider: the CLI family it extends and the env it sets, e.g. a second Claude account
-> claude with CLAUDE_CONFIG_DIR. An account without a Paseo entry uses its discovered family/home."""
orig_provider = str(provider or '')
providers = (dispatch_flow.paseo_config().get('agents') or {}).get('providers')
providers = providers if isinstance(providers, dict) else {}
env = {}
for _ in range(len(providers) + 1):
spec = providers.get(provider) if isinstance(providers.get(provider), dict) else {}
env = {**(spec.get('env') or {}), **env}
if not spec.get('extends'):
break
provider = spec['extends']
if provider not in CLI_RUNS:
proxy_spec = _router_override_proxy_spec(orig_provider)
if isinstance(proxy_spec, dict):
harness = str((bundle or {}).get('harness') or '').strip().lower()
family = harness if harness in CLI_RUNS else ''
if not family and (bundle or {}).get('model'):
import account_fleet
accounts_doc = account_fleet.load_accounts()
canon = account_fleet.canonical((bundle or {}).get('model'), accounts_doc)
api_family = str(account_fleet.row_spec(accounts_doc, canon).get('api_family') or '').strip().lower()
if api_family in CLI_RUNS:
family = api_family
if not family:
family = str(proxy_spec.get('family') or proxy_spec.get('extends') or 'codex').strip().lower()
ep = str(proxy_spec.get('endpoint') or '').strip().rstrip('/')
key = str(proxy_spec.get('api_key') or '').strip()
if ep and key:
if family == 'claude':
provider = 'claude'
env.setdefault('ANTHROPIC_BASE_URL', ep)
env.setdefault('ANTHROPIC_API_KEY', key)
else:
provider = family if family in CLI_RUNS else 'codex'
base = ep if ep.endswith('/v1') else f'{ep}/v1'
env.setdefault('OPENAI_BASE_URL', base)
env.setdefault('OPENAI_API_KEY', key)
if provider not in CLI_RUNS:
family = provider_inventory.account_family(orig_provider)
if family in CLI_RUNS:
provider = family
if provider not in CLI_RUNS and provider_inventory.launcher_family(orig_provider) == 'grok':
provider = 'grok' # a ready Grok ACP definition extends acp, but its CLI is Grok Build
if provider == 'claude' and orig_provider != 'claude' and 'CLAUDE_CONFIG_DIR' not in env and 'ANTHROPIC_BASE_URL' not in env:
env['CLAUDE_CONFIG_DIR'] = account_home(orig_provider)
elif provider == 'codex' and orig_provider != 'codex' and 'CODEX_HOME' not in env and 'OPENAI_BASE_URL' not in env:
env['CODEX_HOME'] = account_home(orig_provider)
return provider, env
def cli_command(family, provider):
if family == 'grok':
# The executable the provider's Paseo definition names (its sibling grok when it names agent) is the one to run;
# a configured command is never swapped for another install. Discovery applies only when none is configured.
providers = (dispatch_flow.paseo_config().get('agents') or {}).get('providers')
providers = providers if isinstance(providers, dict) else {}
for _ in range(len(providers) + 1):
spec = providers.get(provider) if isinstance(providers.get(provider), dict) else {}
command = spec.get('command')
if isinstance(command, list) and command and isinstance(command[0], str):
name = command[0]
configured = Path(name)
if configured.stem.lower() not in ('grok', 'agent'):
raise RuntimeError(f'The command configured for {provider!r} is not a Grok executable: {name}')
if configured.name == name: # bare name: Paseo resolves it through PATH, never the worker's cwd
resolved = shutil.which(name)
configured = Path(resolved) if resolved else None
found = configured and next((c for c in (configured.with_name('grok' + configured.suffix), configured)
if c.is_file()), None)
if found is None:
raise RuntimeError(f'The Grok executable configured for {provider!r} is missing: {name}')
return subscription_cli.direct_prefix(found)
if not spec.get('extends'):
break
provider = spec['extends']
return subscription_cli.cli_prefix(CLI_RUNS[family][0])
def cli(args, out, bundle, text):
"""No Paseo here: run the routed bundle through its own CLI, on the account its provider definition selects."""
workspace = host_placement.canonical_dir(getattr(args, 'workspace', None))
placed = host_placement.place('cli', workspace, default_cwd=host_placement.parent_cwd())
cwd = placed['cwd']
family, provider_env = provider_definition(bundle['provider'], bundle=bundle)
ws_note = f' in directory `{workspace}`' if workspace else ''
native = f'; start it natively{ws_note} with exactly route.bundle and the contents of worker_prompt_file as its prompt.'
if family not in CLI_RUNS:
return dict(out, launched=False, dispatch_mode='native', caller_action='launch_with_native_host_tool',
next=f'No Paseo daemon and no CLI here for {bundle["provider"]!r}' + native), 0
# A value that cannot be one argument refuses this launch here, before anything is written for it.
model = launch_values.argument('model', bundle.get('launch_model') or bundle['model'])
effort = bundle.get('effort') and launch_values.argument('effort', bundle['effort'])
if bundle.get('fast'):
from fast_modes import validate
import account_fleet
accounts = account_fleet.load_accounts()
c_model = account_fleet.canonical(bundle['model'], accounts)
validate(family, c_model, account_fleet.row_spec(accounts, c_model))
executable, flags = CLI_RUNS[family]
env = {k: v for k, v in subscription_cli.subscription_env().items() if not k.startswith(HOST_SESSION_ENV)}
env.update(provider_env)
env.update(AGENTCOMPASS_WORKER='1', ROUTER_PARENT_AGENT_ID=out['parent_id'],
ROUTER_PARENT_HOST=out['parent_host'], ROUTER_PARENT_ADDRESS=out['parent_address'])
run = CLI_RUNS_DIR / f'{time.strftime("%Y%m%d-%H%M%S")}-{launch_values.path_part(bundle["provider"])}-{os.getpid()}'
run.mkdir(parents=True, exist_ok=True)
(run / 'brief.md').write_bytes(text.encode('utf-8'))
options = {'creationflags': subprocess.CREATE_NO_WINDOW | subprocess.CREATE_NEW_PROCESS_GROUP} \
if os.name == 'nt' else {'start_new_session': True}
prompt_argument = family in PROMPT_ARGUMENT
try:
argv = [*cli_command(family, bundle['provider']),
*flags(model, effort, cwd, bool(bundle.get('fast')))]
if family in PROMPT_FILE:
argv += ['--prompt-file', str(run / 'brief.md')]
with open(run / 'brief.md', 'rb') as brief, open(run / 'output.txt', 'wb') as stdout, \
open(run / 'stderr.txt', 'wb') as stderr:
public_data.effect('cli worker launch')
process = subprocess.Popen(argv + [text] if prompt_argument else argv, cwd=cwd, env=env,
stdin=subprocess.DEVNULL if prompt_argument or family in PROMPT_FILE else brief,
stdout=stdout, stderr=stderr, **options)
except (RuntimeError, OSError, launch_values.UnreadableLauncher) as exc:
return dict(out, launched=False, dispatch_mode='native', caller_action='launch_with_native_host_tool',
next=f'The {executable} CLI could not start ({exc})' + native), 1
worker = {'provider': bundle['provider'], 'cli': executable, 'pid': process.pid,
'output': str(run / 'output.txt'), 'stderr': str(run / 'stderr.txt'), 'exit': None}
return dict(out, launched=True, dispatch_mode='cli', caller_action='already_launched_do_not_respawn',
worker=worker,
next='No automatic completion notification is installed for this CLI worker. '
f'The worker runs as PID {process.pid}; the caller must watch worker.output and worker.stderr. You own this process: '
'wait for it, or stop it before you finish.'), 0
def status_of(result, code):
"""One plain state from the existing launch fields. Uncertain delivery is pending, never not_launched."""
mode, action = result.get('dispatch_mode'), result.get('caller_action')
if result.get('launched') is True:
return 'launched'
if result.get('launched') is None or action in ('check_delivery_do_not_resend', 'run_next_argv'):
return 'pending'
if mode == 'scorer_unavailable' or result.get('error') == 'scorer_unavailable':
return 'blocked'
if mode in ('self', 'split'):
return mode
if mode == 'native' and code == 0:
return 'native'
if mode == 'dry_run':
return 'dry_run'
return 'error' if code == 1 else 'blocked'
def launched_next(result, worker, argv):
"""The one accurate sentence for a started worker: who tells the caller it finished depends on the launch surface."""
mode, exit_code = result.get('dispatch_mode'), worker.get('exit')
if mode == 'herdr' and worker.get('state') in ('completed', 'failed', 'needs_input', 'cleaned'):
return f"Herdr operation is {worker['state']}; run next_argv to inspect the existing receipt. Nothing new was launched."
if mode == 'cli':
if exit_code is None:
return (f"Worker is running as PID {worker.get('pid')} and nothing calls back: watch worker_output until it exits, "
'or stop it before you finish.')
return 'Worker finished; read worker_output.' if exit_code == 0 else f'Worker exited with code {exit_code}; read worker_output and worker_stderr.'
notif_status = (worker.get('completion_notification') or {}).get('status')
if notif_status == 'watching':
return ('Worker launched; do not launch another. Its completion arrives as a notification: '
'finish any independent work and end your turn to wait for it; do not sleep or poll '
'(paseo ls, get_agent_status, or result files) in a shell command.')
if notif_status == 'delivered':
return ('Worker launched; do not launch another. Its completion notification has been delivered; '
'read that notification instead of waiting or polling.')
if argv:
return 'Worker launched; do not launch another. No completion notification is confirmed: run next_argv to collect the result.'
return result.get('next') or 'Worker launched; do not launch another.'
def compact(result, status, detail_path):
"""The default --task answer: state, worker, reason and the single next action; everything else is on disk."""
worker = result.get('worker') or {}
bundle = (result.get('route') or {}).get('bundle') or {}
argv = worker.get('continuation_argv') or result.get('continuation_argv') or result.get('next_argv')
nxt = {'self': 'Do this task yourself in the current session; do not spawn a subagent.',
'dry_run': 'Nothing was recorded or launched.'}.get(status) or result.get('next')
if status == 'launched':
nxt = launched_next(result, worker, argv)
elif status == 'pending' and argv:
nxt = worker.get('next_action') or 'Run next_argv to observe the same operation; do not roll again.'
elif status == 'native':
ws_clause = f" in directory `{result['workspace']}`" if result.get('workspace') else ''
nxt = (f'Launch one native worker{ws_clause} with exactly route_bundle (its modeId is the permission mode) and the full contents of '
'worker_prompt_file as its prompt; if the host cannot reproduce that provider/account/model/effort, tell the '
'user instead of substituting.')
worker_summary = {k: bundle.get(k) for k in ('provider', 'account', 'model', 'effort') if bundle.get(k)}
if worker.get('agent_id'):
worker_summary['agent_id'] = worker['agent_id']
if worker_summary and worker.get('resumed'):
worker_summary['resumed'] = True
is_scorer_unavail = result.get('error') == 'scorer_unavailable' or result.get('dispatch_mode') == 'scorer_unavailable'
reason_val = 'scorer_unavailable' if is_scorer_unavail else (((result.get('route') or {}).get('reason') or '')[:160] or None)
out = {'status': status, 'worker': worker_summary or None,
'reason': reason_val, 'next_action': nxt}
if is_scorer_unavail:
out['error'] = 'scorer_unavailable'
cause = result.get('cause') or ((result.get('route') or {}).get('reason')) or result.get('reason') or 'scorer_unavailable'
else:
cause = result.get('error') or worker.get('cause') or worker.get('error') or worker.get('read_error')
if cause and status in ('error', 'blocked', 'pending'):
out['cause'] = str(cause)[:300]
route_warnings = (result.get('route') or {}).get('warnings') or []
if route_warnings:
# The first four, and how many more the details file holds: none is dropped without a word.
more = len(route_warnings) - 4
if detail_path is None: # a dry run writes no details file: nothing holds the rest, so nothing is cut
out['warnings'] = list(route_warnings)
else:
out['warnings'] = route_warnings[:4] + ([f"{more} more {'warning is' if more == 1 else 'warnings are'} in "
f'route.warnings of the details file ({detail_path}).'] if more > 0 else [])
if argv and (status == 'pending' or (status == 'launched' and 'next_argv' in (nxt or ''))):
out['next_argv'] = argv
if status == 'launched' and result.get('dispatch_mode') == 'cli':
out['worker_output'], out['worker_stderr'] = worker.get('output'), worker.get('stderr')
if status == 'native':
out['route_bundle'], out['worker_prompt_file'] = bundle, result.get('worker_prompt_file')
if status == 'split':
out['task_count'] = result.get('task_count')
if result.get('start_after_hours') is not None:
out['start_after_hours'] = result['start_after_hours']
if result.get('caller_action') == 'wait_for_reset':
out['caller_action'] = 'wait_for_reset'
if result.get('retry_at'):
out['retry_at'] = result['retry_at']
if result.get('workspace'):
out['workspace'] = result['workspace']
if result.get('blocked_by'):
out['blocked_by'] = result['blocked_by']
if result.get('attempts'):
out['attempts'] = result['attempts']
if result.get('assumptions'):
out['assumptions'] = result['assumptions']
if result.get('warnings'):
out['warnings'] = [*out.get('warnings', []), *result['warnings']]
if result.get('continuation'):
out['continuation'] = result['continuation']
out['details'] = detail_path
return {k: v for k, v in out.items() if v is not None}
# Flags that describe one brief; a batch takes only the shared ones and each brief is rolled as written.
BATCH_ONLY_ALONE = ('task_id', 'title', 'hours', 'can_wait_hours', 'local_only', 'keep_whole', 'file', 'apply_to', 'provider', 'account',
'model', 'effort', 'basis', 'resume')
def run_batch(args, judge):
"""Several one-line briefs: classified at the same time, then routed and launched one after another so each
allocation sees the reservations of the ones before it."""
briefs = list(args.brief)
if len({str(Path(b).resolve()) for b in briefs}) != len(briefs):
raise ValueError('The same --brief was given twice.')
alone = [f"--{name.replace('_', '-')}" for name in BATCH_ONLY_ALONE if getattr(args, name, None) not in (None, False, [], 0)]
if alone:
raise ValueError('Several --brief files take only shared flags; roll a brief on its own for ' + ', '.join(alone) + '.')
try:
host_placement.validate_workspace(getattr(args, 'workspace', None))
except host_placement.InvalidWorkspace as exc:
return ({'status': 'error', 'error': 'invalid_workspace_directory', 'cause': 'invalid_workspace_directory',
'workspace': getattr(args, 'workspace', None),
'next_action': f'Nothing was launched: {exc}'}, 1)
each = [argparse.Namespace(**{**vars(args), 'brief': Path(b)}) for b in briefs]
if not args.dry_run:
scorer_client.prefetch_scores([build_task(one, read_task_text(one), None) for one in each], args.score_timeout)
results, codes = [], []
batch_used_agents = set()
for index, one in enumerate(each):
one._exclude_agents = set(batch_used_agents)
try:
result, code = run(one, judge)
except KeyboardInterrupt:
# What the batch has goes out before the interrupt does: a worker launched before it is in this answer.
print(json.dumps({'status': 'batch', 'results': results, 'interrupted': str(one.brief),
'not_started': [str(rest.brief) for rest in each[index + 1:]],
'next_action': (f'Interrupted during brief {one.brief}: whether it launched is not known; '
'roll it again (a task that already has a dispatch comes back as that worker, '
'pending), and roll the briefs in not_started.')},
ensure_ascii=False, default=str), flush=True)
raise
except Exception as exc:
# OSError, ValueError, RuntimeError: a refusal or a failure of this brief alone, and the batch goes on.
unexpected = not isinstance(exc, (OSError, ValueError, RuntimeError))
if unexpected and not results and public_data.is_data_error(exc):
raise # nothing done yet: the run falls back to the shipped reference set as a whole (with_fallback)
failed = judge.failure_answer(exc, 'roll') # its error class and text, nothing of a host's free text
result, code = {'status': 'error', 'error_type': failed['error_type'], 'cause': failed['cause'],
'next_action': 'Fix the cause, then roll this brief again on its own.'}, 1
if unexpected:
# The briefs after it are not started, and the ones before keep their results.
not_started = [str(rest.brief) for rest in each[index + 1:]]
results.append({'brief': str(one.brief), **result})
return {'status': 'batch', 'results': results, 'not_started': not_started,
'next_action': (f'Brief {one.brief} failed with an unexpected error (its result says which), and '
f'{len(not_started)} brief(s) after it were not started (not_started). Handle each '
'result on its own; fix the cause, then roll the failed brief and the ones not '
'started again.')}, 1
used_id = (result.get('worker') or {}).get('agent_id') if isinstance(result, dict) else None
if isinstance(used_id, str) and used_id:
batch_used_agents.add(used_id)
results.append({'brief': str(one.brief), **result})
codes.append(code)
code = 0 if not any(codes) else (1 if 1 in codes else 2)
return {'status': 'batch', 'results': results,
'next_action': 'Handle each result on its own: its status and next_action say what to do for that brief.'}, code
def run(args, judge):
"""Compact result (status, next action, pointers) for `--task` and `--brief` alike; `--verbose` prints the full result, which is on disk either way."""
result, code = _run(args, judge)
status = status_of(result, code)
result = dict(result, status=status)
agent_id = (result.get('worker') or {}).get('agent_id')
if agent_id:
result['continuation'] = worker_sessions.continuation_verdict(agent_id)
# The file on disk and --verbose carry the same cause and next action as the compact answer.
summary = compact(result, status, None)
result.update({k: summary[k] for k in ('cause', 'next_action') if summary.get(k) and k not in result})
if getattr(args, 'verbose', False):
return result, code
if status == 'dry_run':
return compact(result, status, None), code
path = None
try:
RESULTS_DIR.mkdir(parents=True, exist_ok=True)
path = RESULTS_DIR / f'{int(time.time())}-{uuid.uuid4().hex[:8]}.json'
path.write_text(json.dumps(result, ensure_ascii=False, indent=2, default=str), encoding='utf-8')
except OSError:
return result, code # nowhere durable to put the detail: give the caller all of it
return compact(result, status, str(path)), code
def _run(args, judge):
"""judge is the route_judge module (classify_pinned, record_constraint, record_resume, plan_stage,
scorer_unavailable_result)."""
text = read_task_text(args)
if not text.strip():
raise ValueError('The task is empty.')
if getattr(args, 'model', None) not in (None, ''):
import model_resolution
model_resolution.check_model_pin(args.model, '--model')
try:
canonical_ws = host_placement.validate_workspace(getattr(args, 'workspace', None))
except host_placement.InvalidWorkspace as exc:
return ({
'stage': 'roll',
'launched': False,
'dispatch_mode': 'none',
'caller_action': 'check_error',
'error': 'invalid_workspace_directory',
'workspace': getattr(args, 'workspace', None),
'next': f'Nothing was launched: {exc}',
}, 1)
explicit_id = (getattr(args, 'resume', None) or '').strip()
if explicit_id and getattr(args, 'new_worker', False):
return _resume_refusal({'stage': 'roll'}, explicit_id, 'conflicting_flags',
'Cannot combine --resume and --new-worker; pass one or the other.', code=1)
if explicit_id and args.dry_run:
# A named worker's turn is decided by its own state in the registry (idle, worn, gated, its directory), which a
# dry run does not read.
return _resume_refusal({'stage': 'roll'}, explicit_id, 'conflicting_flags',
'Nothing was planned: a dry run reads no dispatch state, so it cannot say what a turn of '
f'worker {explicit_id!r} would get. Roll --resume without --dry-run to continue that worker, '
'or --dry-run without --resume to see the route a fresh worker would get.', code=1)
# Resolve before classification/ledger writes: never launch an orphan as a fallback.
if args.dry_run and not (os.environ.get('PASEO_AGENT_ID', '').strip() or args.parent_id):
parent, parent_host, parent_address = None, None, None
else:
parent, parent_host, parent_address = resolve_parent(args)
said = []
task = build_task(args, text, parent, said)
task.update(parent_host=parent_host, parent_address=parent_address)
host_session = harness_session(parent) if parent else ''
if host_session:
task['host_session_id'] = host_session
if parent and not args.dry_run:
pending_rows = [r for r in registry.pending() if r.get('parent_id') == parent]
if pending_rows:
launchers = (provider_inventory.current().get('launchers') or {})
can_reconcile = any(
(r.get('task_id') == task['task_id'])
or (launchers.get((r.get('bundle') or {}).get('provider')) or {}).get('status') != 'disabled'
for r in pending_rows
)
if can_reconcile:
for r in pending_rows:
dispatch_flow.reconcile(r['dispatch_id'])
pending_rows = [r for r in registry.pending() if r.get('parent_id') == parent]
# The same task already dispatched by this parent: hand back that worker, without classifying or launching again.
for row in pending_rows:
if not getattr(args, 'new_worker', False) and (row['parent_id'], row['task_id']) == (parent, task['task_id']):
argv = entry.argv('launch', '--dispatch-id', row['dispatch_id'], '--parent-id', parent, '--watch-seconds', '120')
return dict(stage='roll', parent_id=parent, launched=None, dispatch_mode='paseo',
caller_action='run_next_argv', worker=dict(dispatch_flow.public_chain(row), continuation_argv=argv),
next='This task already has a dispatch (state ' + row['state'] + '): run next_argv to observe it; '
'it will not create a second worker.'), 0
excluded = set(getattr(args, '_exclude_agents', None) or ())
usage_cache_path = getattr(args, 'usage_cache', None)
all_reusable = [w for w in registry.reusable_workers(parent, named=explicit_id or None)
if w.get('agent_id') not in excluded]
base_out = {'stage': 'roll', 'parent_id': parent, 'parent_host': parent_host, 'parent_address': parent_address,
**({'workspace': canonical_ws} if canonical_ws else {})}
if explicit_id:
explicit_worker = next((w for w in all_reusable if w.get('agent_id') == explicit_id), None)
if explicit_worker is None:
return _resume_refusal(
base_out, explicit_id, 'resume_worker_unavailable',
_not_reusable_text(explicit_id, parent, excluded),
)
if explicit_worker.get('worn'):
return _resume_refusal(
base_out, explicit_id, 'resume_worker_worn',
f'Nothing was launched: worker {explicit_id!r} reached the context rotation limit and cannot be resumed. '
'Write a handoff brief and omit --resume to start a fresh worker.',
)
if gate_reason := _worker_gate_refusal(explicit_worker, usage_cache_path=usage_cache_path):
return _resume_refusal(base_out, explicit_id, 'resume_worker_gated',
gate_refusal_text(explicit_id, gate_reason))
own_dir = host_placement.canonical_dir(host_placement.worker_directory(None, explicit_worker))
if canonical_ws and own_dir and own_dir != canonical_ws:
# A worker does not move: the host resumes it only in its own directory (the bridge's
# `worker_workspace_mismatch`), and a new worker in --workspace would not hold its context.
return _resume_refusal(base_out, explicit_id, 'resume_workspace_mismatch', workspace_mismatch_text(
explicit_id, own_dir, canonical_ws))
if refused := resumed_directory(task, canonical_ws, explicit_worker, said):
return _resume_refusal(base_out, explicit_id, 'resume_worker_directory_unknown', refused)
if named_route_given(args) or getattr(args, 'fast', False):
conflict = named_route_conflict(args, _resolve_worker_bundle(explicit_worker) or {})
if conflict:
raise ValueError(conflict)
matched_worker = explicit_worker
elif not getattr(args, 'new_worker', False):
policy = host_policy.load_policy()
eligible = [w for w in all_reusable
if not w.get('worn') and _auto_resumable(w, policy, usage_cache_path=usage_cache_path)]
matched_worker = match_reusable_worker(args, task, text, parent, workers=eligible)
else:
matched_worker = None
if matched_worker and matched_worker.get('bundle_id'):
task['chain'] = {
'id': matched_worker['chain_id'],
'coupling': 'medium',
'worker': {
'agent_id': matched_worker['agent_id'],
'bundle': matched_worker['bundle_id'],
'read_only_review': matched_worker.get('read_only_review'),
**matched_worker['session_state'],
},
}
with provider_inventory.snapshot():
if explicit_id:
# The caller named the worker: its route is the worker's own bundle, not what an automatic plan of this
# task would choose (which excludes, for one, an account out of automatic routing). Model flags that name
# that same route add nothing (named_route_conflict refused any other).
classified = judge.classify_pinned(task, args)
decision = (classified['result'] if 'result' in classified else
judge.record_resume(args, task, classified, _resolve_worker_bundle(matched_worker), explicit_id))
elif named_route_given(args):
if refusal := named_route_refusal(args):
raise ValueError(refusal)
args.constraint = 'user_override'
# Only the model is pinned: the task is classified exactly as an automatic roll's, and the pinned bundle
# is priced and reserved from that profile.
classified = judge.classify_pinned(task, args)
decision = classified['result'] if 'result' in classified else judge.record_constraint(args, task, classified)
else:
args.stage = 'roll'
decision, _ = judge.plan_stage({'task': task}, args)
if (getattr(args, 'no_score', False) and not getattr(args, 'dry_run', False)
and not isinstance(task.get('profile'), dict)
and decision.get('error') != 'no_ready_account'):
decision = judge.scorer_unavailable_result(
task,
{
'source': 'scorer_unavailable',
'model': None,
'fallback_reason': 'no_score_without_profile',
'fallback_detail': 'roll --no-score requires a complete caller-supplied task.profile.',
},
time.monotonic(),
)
out = {'stage': 'roll', 'route': summary(decision), 'parent_id': parent,
'parent_host': parent_host, 'parent_address': parent_address,
**({'workspace': canonical_ws} if canonical_ws else {})}
if (notes := ignored_flag_notes(args, decision, explicit_id)):
out['warnings'] = notes
if decision.get('choice') == 'split':
out['route']['reason'] = decision.get('reason')
return dict(out, launched=False, dispatch_mode='split', caller_action='roll_each_line',
task_count=decision['task_count'], next=decision['next']), 2
if (hours := hours_assumption(args, decision)) is not None:
said.insert(0, hours)
if said:
out['assumptions'] = said
if decision.get('error') == 'scorer_unavailable':
out['route']['reason'] = decision.get('reason') or 'scorer_unavailable'
return dict(out, launched=False, dispatch_mode='scorer_unavailable',
caller_action='parent_autonomous_choice', error='scorer_unavailable',
reason='scorer_unavailable', cause=decision.get('reason'),
scorer=decision.get('scorer'), next=decision.get('next')), 2
if (decision.get('task_profile') or {}).get('urgency') == 'high' and not (decision.get('task_profile') or {}).get('wants_fast'):
out.setdefault('assumptions', []).append(
'The task profile notes high urgency without wants_fast: fast mode uses task_profile.wants_fast or --fast, '
'and is enabled only when quota allows.')
if args.dry_run:
return dict(out, launched=False, dispatch_mode='dry_run', caller_action='none',
next='Dry run: nothing recorded or launched.'), 0
bundle = decision.get('selected_bundle') or {}
provider = bundle.get('provider')
if decision.get('choice') == 'self':
return dict(out, launched=False, dispatch_mode='self', caller_action='execute_self',
next='Execute this task directly in the current session; do not spawn a subagent.'), 2
if decision.get('choice') in (None, 'none') or not bundle:
return dict(out, launched=False, dispatch_mode='none', caller_action='execute_self_or_ask_user',
next=decision.get('next') or none_next(decision)), 2
if (decision.get('decision') or {}).get('needs_user_decision') and not (explicit_id and bundle):
return dict(out, launched=False, dispatch_mode='none', caller_action='ask_user',
next=user_decision_next(decision)), 2
if (decision.get('decision') or {}).get('action') == 'defer':
wait = (decision.get('decision') or {}).get('start_after_hours') or (decision.get('decision') or {}).get('wait_hours')
return dict(out, launched=False, dispatch_mode='defer', caller_action='wait_for_reset',
start_after_hours=wait, next=defer_next(decision, wait)), 2
if provider in host_placement.REMOTE_SURFACES:
placed = host_placement.place(provider, canonical_ws)
if not placed['ok']:
return placement_refused(out, provider, placed)
out = files_not_sent(out, args, provider)
use_paseo, no_paseo_because = paseo_choice(provider, parent_host, args)
text, prompt_file = prepare_worker_prompt(text, parent, parent_host, parent_address, watched=bool(use_paseo))
out['worker_prompt_file'] = str(prompt_file)
if provider == 'dot':
return dot(args, out, prompt_file, task=task, decision=decision)
if provider == 'chatgpt-web':
return consult(args, out, prompt_file, task=task, decision=decision)
if provider == 'grok-bot':
return grok_bot(args, out, prompt_file, task, bundle, decision=decision)
decision_profile = (
decision.get('task_profile')
or ((decision.get('decision') or {}).get('task') or {}).get('profile')
or task.get('profile')
)
access = task_access(args, decision_profile if isinstance(decision_profile, dict) else None)
if use_paseo:
return paseo(args, out, decision, task, text, parent, usage_reading.usage_snapshot(args.usage_cache), judge=judge)
surface = 'herdr' if parent_host == 'herdr' else parent_host if parent_host in NATIVE_HOSTS else 'cli'
placed = host_placement.place(surface, canonical_ws, default_cwd=host_placement.parent_cwd(),
bundle=bundle, address=parent_address)
if not placed['ok']:
return placement_refused(out, surface, placed)
landing = placed['cwd']
if not canonical_ws and landing and access == 'write':
out = same_cwd_warning(out, landing, parent)
usage = usage_reading.usage_snapshot(getattr(args, 'usage_cache', None))
try:
claim_row = registry.record_host_claim(
surface, decision, task, bundle,
label=getattr(args, 'title', None) or title_of(text),
usage=usage, access=access,
workspace=canonical_ws, cwd=landing,
)
except registry.WorkspaceBusy as busy:
return workspace_blocked(out, busy.workspace, busy.holders,
dispatch_mode='native' if surface in NATIVE_HOSTS else surface)
if surface == 'herdr':
import host_herdr
res, code = host_herdr.launch(out, bundle, prompt_file, task['task_id'],
cwd=landing, dispatch_id=claim_row['dispatch_id'])
settle_claim(claim_row, res, 'herdr_preflight_failed')
return res, code
if surface in NATIVE_HOSTS:
return dict(out, launched=False, dispatch_mode='native', caller_action='launch_with_native_host_tool',
**({'dispatch_id': claim_row['dispatch_id']} if canonical_ws else {}),
next=placed['next']), 0
res, code = cli(args, without_paseo(out, no_paseo_because) if no_paseo_because else out, bundle, text)
settle_claim(claim_row, res, 'cli_not_launched')
return res, code
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 |