Skip to content

akiiwa-games/AgentCompass / skills/agent-compass

agent-compass

Flagged

Choose owner, model and effort, outbound authorization, advisor use, and continuation for delegated work. Reads local usage and effective account policy, profiles the task with the configured System-One scorer, then allocates a compatible worker. Use for independent worker or advisor work; ordinary local execution needs no routing.

FileKindSize
SKILL.mdskill md5.5 KB
agents/openai.yamlconfig427 B
calibration/README.mdmarkdown55.2 KB
calibration/arena_capture.pyscript14.0 KB
calibration/community.pyscript25.2 KB
calibration/five_axis.pyscript196.4 KB
calibration/measurements.pyscript68.4 KB
calibration/refresh.pyscript48.6 KB
calibration/series.pyscript10.2 KB
calibration/sources.pyscript24.1 KB
calibration/tiers.pyscript14.6 KB
grok-bot/.gitignoreother47 B
grok-bot/dependency_patch.pyscript4.5 KB
grok-bot/install_cli.pyscript3.6 KB
grok-bot/test-recovery.mjsscript8.6 KB
grok-bot/test_install_cli.pyscript4.1 KB
grok-bot/upstream.jsonconfig3.4 KB
references/accounts.jsonconfig155.9 KB
references/classifier-cases.jsonconfig21.5 KB
references/dispatch-lifecycle.mdmarkdown28.9 KB
references/dispatch-rules.mdmarkdown11.3 KB
references/effort-matching.mdmarkdown5.1 KB
references/fast-modes.mdmarkdown3.5 KB
references/five-axis-scores.jsonconfig3.1 MB
references/gemini-decisions-api.mdmarkdown2.9 KB
references/grok-bot.mdmarkdown13.0 KB
references/herdr.mdmarkdown5.1 KB
references/jev-api.mdmarkdown1.6 KB
references/level-3-conversion.jsonconfig2.4 KB
references/model-capabilities.jsonconfig3.6 KB
references/model-capabilities.mdmarkdown14.6 KB
references/parent-address-gate.mdmarkdown10.1 KB
references/plan-templates.jsonconfig13.2 KB
references/provider-discovery.mdmarkdown11.5 KB
references/provider-usage.mdmarkdown4.1 KB
references/public-data.jsonconfig816 B
references/public-measurements.jsonconfig1.3 MB
references/roll-reference.mdmarkdown26.7 KB
references/router-internals.mdmarkdown93.7 KB
references/task-classifier.mdmarkdown6.1 KB
references/user-scores.jsonconfig6.8 KB
references/work-kinds.mdmarkdown4.7 KB
references/worker-communication.mdmarkdown2.1 KB
scripts/account_fleet.pyscript32.9 KB
scripts/account_state.pyscript22.2 KB
scripts/accounts_override.pyscript14.8 KB
scripts/allocator.pyscript19.8 KB
scripts/antigravity_plan.pyscript18.7 KB
scripts/antigravity_telemetry.pyscript5.1 KB
scripts/auto_bundles.pyscript31.3 KB
scripts/axis_scores.pyscript40.3 KB
scripts/caller_input.pyscript3.0 KB
scripts/candidate_eval.pyscript54.0 KB
scripts/candidate_ranking.pyscript9.5 KB
scripts/capability_catalog.pyscript8.0 KB
scripts/check_router_contract.pyscript2.8 KB
scripts/conftest.pyscript2.5 KB
scripts/cwd_policy.pyscript1.5 KB
scripts/data_age.pyscript1.5 KB
scripts/decision_ledger.pyscript18.9 KB
scripts/demo_plan.pyscript6.3 KB
scripts/dispatch_fallback.pyscript40.3 KB
scripts/dispatch_flow.pyscript58.7 KB
scripts/dispatch_ground_truth.pyscript43.5 KB
scripts/dispatch_registry.pyscript113.7 KB
scripts/entry.pyscript1.7 KB
scripts/env_vars.pyscript580 B
scripts/fast_modes.pyscript2.5 KB
scripts/fixtures/grok-api-responses.jsonconfig907 B
scripts/fixtures/reference-accounts.jsonconfig26.9 KB
scripts/grok_bot_paths.pyscript1005 B
scripts/host_herdr.pyscript16.8 KB
scripts/host_placement.pyscript9.4 KB
scripts/host_policy.pyscript10.1 KB
scripts/launch_failures.pyscript5.9 KB
scripts/launch_values.pyscript12.3 KB
scripts/ledger_snapshot.pyscript11.1 KB
scripts/live_models.pyscript21.1 KB
scripts/model_latch.pyscript7.6 KB
scripts/model_resolution.pyscript18.0 KB
scripts/override_store.pyscript2.2 KB
scripts/plan_state_residue.pyscript5.0 KB
scripts/provider_inventory.pyscript128.2 KB
scripts/provider_retry.pyscript34.6 KB
scripts/public_data.pyscript59.2 KB
scripts/quota_economy.pyscript38.0 KB
scripts/quota_exhaustion.pyscript5.9 KB
scripts/quota_overrides.pyscript25.6 KB
scripts/quota_pools.pyscript29.8 KB
scripts/reference_provenance.pyscript32.3 KB
scripts/released_names.pyscript3.8 KB
scripts/roll.pyscript106.3 KB
scripts/route_judge.pyscript83.4 KB
scripts/route_simulation.pyscript26.3 KB
scripts/router_test_support.pyscript6.7 KB
scripts/run_grok_bot.pyscript18.8 KB
scripts/scorer_client.pyscript55.2 KB
scripts/stage_help.pyscript5.8 KB
scripts/state_upgrade.pyscript24.0 KB
scripts/subscription_cli.pyscript3.6 KB
scripts/task_intake.pyscript33.6 KB
scripts/test_account_identity.pyscript7.1 KB
scripts/test_account_state.pyscript63.3 KB
scripts/test_accounts_override.pyscript30.1 KB
scripts/test_allocator.pyscript94.2 KB
scripts/test_antigravity_plan.pyscript13.2 KB
scripts/test_applicable_quota.pyscript9.1 KB
scripts/test_auto_bundles.pyscript10.8 KB
scripts/test_billing_routing_policy.pyscript9.9 KB
scripts/test_cadence_count.pyscript32.2 KB
scripts/test_calibration_units.pyscript27.0 KB
scripts/test_capability_catalog.pyscript5.0 KB
scripts/test_decision_ledger.pyscript8.5 KB
scripts/test_demo_plan.pyscript3.4 KB
scripts/test_derived_state.pyscript21.6 KB
scripts/test_dispatch.pyscript322.3 KB
scripts/test_dispatch_answers.pyscript14.8 KB
scripts/test_dispatch_fallback.pyscript53.2 KB
scripts/test_entry.pyscript1.6 KB
scripts/test_fast_modes.pyscript9.9 KB
scripts/test_five_axis.pyscript290.1 KB
scripts/test_five_axis_economy.pyscript105.0 KB
scripts/test_fleet_parity.pyscript15.6 KB
scripts/test_grok_bot.pyscript47.7 KB
scripts/test_ground_truth_recording.pyscript68.8 KB
scripts/test_herdr.pyscript14.1 KB
scripts/test_host_policy.pyscript24.6 KB
scripts/test_launch_values.pyscript8.0 KB
scripts/test_metered_usd.pyscript60.4 KB
scripts/test_model_resolution.pyscript9.2 KB
scripts/test_named_route_facts.pyscript28.6 KB
scripts/test_native_hosts.pyscript6.0 KB
scripts/test_new_user_fleet.pyscript3.3 KB
scripts/test_no_hardcode_classification.pyscript75.1 KB
scripts/test_no_legacy_scoring.pyscript6.5 KB
scripts/test_override_store.pyscript2.3 KB
scripts/test_plan_says_why.pyscript44.9 KB
scripts/test_provider_inventory.pyscript83.2 KB
scripts/test_provider_names.pyscript126.0 KB
scripts/test_provider_pools.pyscript14.2 KB
scripts/test_public_data.pyscript93.5 KB
scripts/test_quota_exhaustion.pyscript5.6 KB
scripts/test_rate_limit_windows.pyscript6.3 KB
scripts/test_record_says_why.pyscript26.5 KB
scripts/test_reference_provenance.pyscript16.7 KB
scripts/test_refresh_entry.pyscript110.7 KB
scripts/test_released_names.pyscript4.1 KB
scripts/test_reset_priority.pyscript4.8 KB
scripts/test_roll_answers.pyscript44.7 KB
scripts/test_roll_notifications.pyscript10.4 KB
scripts/test_route_judge.pyscript99.8 KB
scripts/test_route_simulation.pyscript7.0 KB
scripts/test_routing_parity.pyscript32.3 KB
scripts/test_routing_review.pyscript25.1 KB
scripts/test_setup_discovery_parity.pyscript9.5 KB
scripts/test_stage_help.pyscript2.0 KB
scripts/test_state_upgrade.pyscript13.8 KB
scripts/test_turn_refusal.pyscript16.7 KB
scripts/test_usage_cache.pyscript4.9 KB
scripts/test_usage_collector.pyscript21.4 KB
scripts/test_usage_core_claude_accounts.pyscript1.8 KB
scripts/test_usage_core_grok_cli_billing.pyscript15.6 KB
scripts/test_usage_core_magpie.pyscript5.4 KB
scripts/test_usage_core_magpie_pool.pyscript10.8 KB
scripts/test_usage_core_safety.pyscript24.4 KB
scripts/test_user_scores.pyscript102.3 KB
scripts/test_venice_usage.pyscript1.3 KB
scripts/test_window_scope.pyscript5.5 KB
scripts/turn_refusal.pyscript10.7 KB
scripts/usage_cache.pyscript4.7 KB
scripts/usage_collector.pyscript7.4 KB
scripts/usage_core.pyscript142.0 KB
scripts/usage_magpie.pyscript10.6 KB
scripts/usage_reading.pyscript17.1 KB
scripts/user_scores.pyscript72.8 KB
scripts/venice_usage.pyscript2.6 KB
scripts/window_scope.pyscript3.2 KB
scripts/worker_context.pyscript8.9 KB
scripts/worker_sessions.pyscript10.9 KB

scripts/run_grok_bot.py

View on GitHub
"""Thin Grok Bot runner. Upstream gbot owns authentication and transport."""
from __future__ import annotations

import argparse
import hashlib
import json
import os
from pathlib import Path
import re
import shutil
import signal
import subprocess
import sys
import time

import grok_bot_paths
import override_store

PACKAGE = Path(__file__).resolve().parents[1] / 'grok-bot'
CLI = grok_bot_paths.runtime_dir() / grok_bot_paths.ENTRY
# Cold send: list + EnsureSandBox + retried list + one send, each bounded upstream at 30s.
# Include a possible initial Ensure for an absent descriptor and local startup/decryption overhead.
CLI_TIMEOUT = 210
STATE = Path(os.environ.get('ROUTER_STATE_DIR') or Path.home() / '.agent-compass') / 'grok-bot'


class TransportError(RuntimeError):
    def __init__(self, message, delivery='unknown', diagnostic=None):
        super().__init__(message)
        self.delivery = delivery
        self.diagnostic = diagnostic


def _run_cli(command, *, timeout, env):
    """Own the CLI/flight lifetime, even if an intermediate parent exits first."""
    job = None
    if os.name == 'nt':
        # Use the same pywin32 runtime as the Windows tray. Gate the helper on stdin
        # so it cannot spawn the CLI until assignment to the kill-on-close Job succeeds.
        try:
            import win32job
            import win32api
            import win32event
            job = win32job.CreateJobObject(None, '')
            limits = win32job.QueryInformationJobObject(job, win32job.JobObjectExtendedLimitInformation)
            limits['BasicLimitInformation']['LimitFlags'] |= win32job.JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
            win32job.SetInformationJobObject(job, win32job.JobObjectExtendedLimitInformation, limits)
        except Exception as exc:
            if job is not None:
                job.Close()
            raise TransportError('Windows CLI process ownership requires the AgentCompass pywin32 runtime.',
                                 'rejected', {'category': 'local_runtime', 'component': 'pywin32'}) from exc
        helper = ("import subprocess,sys\n"
                  "if sys.stdin.buffer.read(1) != b'1': raise SystemExit(125)\n"
                  "raise SystemExit(subprocess.call(sys.argv[1:], stdin=subprocess.DEVNULL))")
        launch = [sys.executable, '-S', '-c', helper, *command]
        options = {'creationflags': subprocess.CREATE_NO_WINDOW, 'stdin': subprocess.PIPE}
    else:
        launch, options = command, {'start_new_session': True}

    def finish_job():
        handles = []
        try:
            # Freeze further growth before enumerating: a nonempty Job at limit 1
            # cannot create another member. Keep handles through asynchronous exit.
            limits = win32job.QueryInformationJobObject(job, win32job.JobObjectExtendedLimitInformation)
            limits['BasicLimitInformation']['LimitFlags'] |= win32job.JOB_OBJECT_LIMIT_ACTIVE_PROCESS
            limits['BasicLimitInformation']['ActiveProcessLimit'] = 1
            win32job.SetInformationJobObject(job, win32job.JobObjectExtendedLimitInformation, limits)
            for pid in win32job.QueryInformationJobObject(job, win32job.JobObjectBasicProcessIdList):
                try:
                    handles.append(win32api.OpenProcess(0x00100000, False, pid))
                except Exception as exc:
                    if getattr(exc, 'winerror', None) != 87:  # Already exited before handle acquisition.
                        raise
            win32job.TerminateJobObject(job, 1)
            deadline = time.monotonic() + 10
            while win32job.QueryInformationJobObject(job, win32job.JobObjectBasicAccountingInformation)['ActiveProcesses']:
                if time.monotonic() >= deadline:
                    raise TimeoutError('owned Job still active')
                time.sleep(0.01)
            for handle in handles:
                if win32event.WaitForSingleObject(handle, max(0, int((deadline - time.monotonic()) * 1000))) != win32event.WAIT_OBJECT_0:
                    raise TimeoutError('owned process has not exited')
        except Exception as exc:
            raise TransportError('CLI cleanup did not confirm termination; delivery remains unknown.') from exc
        finally:
            job.Close()
            for handle in handles:
                handle.Close()
    try:
        proc = subprocess.Popen(launch, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
                                encoding='utf-8', errors='replace', env=env, **options)
    except Exception:
        if job is not None:
            job.Close()
        raise
    if job is not None:
        released = False
        try:
            win32job.AssignProcessToJobObject(job, int(proc._handle))
            released = True
            proc.stdin.write('1')
            proc.stdin.flush()
            proc.stdin.close()
            proc.stdin = None
        except Exception as exc:
            finish_job()
            if proc.poll() is None:
                proc.kill()  # Assignment may have failed; only the blocked helper can exist.
            proc.communicate(timeout=10)
            if released:
                raise TransportError('CLI launch handoff failed; delivery remains unknown.') from exc
            raise TransportError('Could not establish Windows CLI process ownership before launch.',
                                 'rejected', {'category': 'local_runtime', 'component': 'process_ownership'}) from exc
    timed_out = None
    try:
        try:
            stdout, stderr = proc.communicate(timeout=timeout)
        except subprocess.TimeoutExpired as exc:
            timed_out = exc
            if job is None:
                os.killpg(proc.pid, signal.SIGKILL)
    finally:
        if job is not None:
            finish_job()
    if timed_out:
        proc.communicate(timeout=10)
        raise timed_out
    return subprocess.CompletedProcess(command, proc.returncode, stdout, stderr)


def gbot(*args):
    if not CLI.is_file() or not shutil.which('node'):
        raise TransportError('Install Node >=22.19.0 and run skills/agent-compass/grok-bot/install_cli.py.', 'rejected')
    argv = list(args)
    boundary = argv.index('--') if '--' in argv else len(argv)
    argv[boundary:boundary] = ['--gateway', '--json']
    command = ['node', str(CLI), *argv]
    if os.name == 'nt' and len(subprocess.list2cmdline(command).encode('utf-16-le')) // 2 > 30000:
        raise TransportError('Prompt exceeds the Windows CLI argument limit; shorten the brief.', 'rejected')
    # Upstream auto-prefixes Codex sender metadata otherwise, implying a local relay we do not run.
    env = {k: v for k, v in os.environ.items() if k != 'CODEX_THREAD_ID'}
    try:
        proc = _run_cli(command, timeout=CLI_TIMEOUT, env=env)
    except subprocess.TimeoutExpired:
        raise TransportError('gbot timed out; delivery may be unknown. Read status before any new submission.') from None
    except OSError:
        raise TransportError('Could not start gbot; check the local Node installation.', 'rejected') from None
    try:
        # Canonical CLI failures are JSON on stderr; successful results are on stdout.
        value = json.loads(proc.stdout if proc.stdout.strip() else proc.stderr)
    except ValueError:
        raise TransportError('gbot returned no valid JSON; inspect the official app before resending.') from None
    if proc.returncode or (isinstance(value, dict) and value.get('error')):
        # Do not echo arbitrary upstream/server errors (they can include credential-bearing details).
        message = json.dumps(value)
        detail = 'Upstream gbot failed; inspect the official app/session and retry a read-only doctor.'
        diagnostic = None
        error = value.get('error') if isinstance(value, dict) else None
        # Only retain the known operation and HTTP code, never the upstream response body.
        match = re.match(r'^(listAgents|EnsureSandBox) failed: ([45][0-9]{2})(?:\s|$)',
                         str(error.get('message', '')) if isinstance(error, dict) else '')
        if args == ('bots', 'list') and match:
            diagnostic = {'category': 'http_error', 'operation': match[1], 'status': int(match[2])}
            detail = f"Grok Bot {match[1]} returned HTTP {match[2]}; the response does not establish the cause."
        if 'Set CURSOR_ACCESS_TOKEN' in message:
            detail = ('gbot cannot find a gateway session. If already signed in and connected to the cloud computer, '
                      'keep it awake and try a normal app exit and reopen. Windows 0.77 binds Ctrl+Q; '
                      'if it has no effect, recheck doctor before diagnosing the normal-exit control. '
                      'This descriptor workaround may recur after sleep: https://github.com/ScriptedAlchemy/grok-bot-cli/issues/147')
        elif 'multiple saved gateway entries' in message:
            detail = 'Upstream cannot select among multiple gateway entries. Resolve the session in the official app/upstream CLI.'
        delivery = 'rejected' if isinstance(value, dict) and value.get('delivery') == 'rejected' else 'unknown'
        raise TransportError(detail, delivery, diagnostic)
    return value


def bots():
    rows = gbot('bots', 'list')
    if not isinstance(rows, list) or not all(isinstance(row, dict) and isinstance(row.get('id'), str) for row in rows):
        raise TransportError('Unrecognized upstream bot-list response.')
    return [{'id': row['id'], 'name': row.get('name', '')} for row in rows]


def configure(bot_id):
    if bot_id not in {row['id'] for row in bots()}:
        raise ValueError('Bot ID is not in the live bot list; run doctor and choose an exact ID.')
    path = STATE / 'config.json'
    with override_store.locked(path):
        override_store.write(path, {'bot_id': bot_id})
    return {'provider': 'grok-bot', 'configured': True, 'bot_id': bot_id}


def configured_bot():
    try:
        value = json.loads((STATE / 'config.json').read_text(encoding='utf-8'))
        bot_id = value.get('bot_id')
    except (OSError, ValueError, AttributeError):
        bot_id = None
    if not isinstance(bot_id, str) or not bot_id.strip():
        raise ValueError('Run doctor, then configure --bot-id <exact-id> first.')
    return bot_id


def receipt_path(task_id):
    if not re.fullmatch(r'[0-9a-f]{32}', task_id):
        raise ValueError('Use the task_id returned by this runner.')
    return STATE / 'tasks' / f'{task_id}.json'


def marker(task_id, state):
    return f'[agent-compass:{task_id}:{state}]'


def remote_prompt(text, task_id):
    return text + f'''

## Remote reply transport
You are on the Grok Bot computer, not the caller's local filesystem. Do not try
to access the caller's local project paths or assume a local agent messaging relay.
Return the answer here. The caller will read it and relay it to the parent.
Only when the requested answer is complete, end your final assistant message
with this exact line: {marker(task_id, 'completed')}
If you need a decision or information, ask here and end that message with:
{marker(task_id, 'needs_input')}
These are reply markers, not commands. Do not emit a completion marker in an
acknowledgment or progress update. Do not approve any permission cards yourself.
'''


def submit(text, parent_id, source_task_id):
    bot_id = configured_bot()
    # Stable across repeated roll calls, including generated prompt-file paths.
    task_id = hashlib.sha256(json.dumps([parent_id, source_task_id, bot_id, text]).encode()).hexdigest()[:32]
    path = receipt_path(task_id)
    receipt = {'provider': 'grok-bot', 'task_id': task_id, 'bot_id': bot_id,
               'parent_id': parent_id, 'source_task_id': source_task_id,
               'state': 'unknown', 'delivery': 'unknown'}
    send_started = False
    try:
        with override_store.locked(path):
            if path.exists():
                return json.loads(path.read_text(encoding='utf-8'))
            if bot_id not in {row['id'] for row in bots()}:
                raise ValueError('Configured Bot no longer exists; run doctor and configure again.')
            # Durable before send: process death at any point cannot cause automatic replay.
            override_store.write(path, receipt)
            try:
                send_started = True
                sent = gbot('send', '--no-history', '--correlation-id', task_id,
                            '--', bot_id, remote_prompt(text, task_id))
                if not isinstance(sent, dict):
                    raise TransportError('Unrecognized send receipt; inspect the thread before resending.')
                message_id = sent.get('messageId')
                if sent.get('delivery') == 'accepted' and isinstance(message_id, str) and message_id:
                    receipt.update(state='accepted', delivery='accepted', message_id=message_id)
                elif sent.get('delivery') == 'rejected':
                    receipt.update(state='failed', delivery='rejected')
                else:
                    receipt['send_error'] = 'Upstream did not return an accepted message ID; delivery initially unknown.'
            except TransportError as exc:
                receipt.update(state='failed' if exc.delivery == 'rejected' else 'unknown',
                               delivery=exc.delivery, error=str(exc), send_error=str(exc))
            override_store.write(path, receipt)
            return receipt
    except (OSError, ValueError) as exc:
        if send_started:
            return {**receipt, 'persistence_error': 'Could not persist the send result; read status before any new submission.'}
        if isinstance(exc, TimeoutError) or path.exists():
            # Another caller may already have sent, or be sending under this lock.
            return {**receipt, 'read_error': 'Receipt store is busy or unreadable; read status before any new submission.'}
        raise  # No receipt and no send attempt: setup or initial persistence failed.


def read_reply(receipt):
    root = receipt.get('message_id')
    args = ['thread', receipt['bot_id'], '--no-history']
    args += ['--root', root] if root else ['--limit', '200']
    data = gbot(*args)
    if not isinstance(data, dict) or (data.get('target') or {}).get('id') != receipt['bot_id']:
        raise TransportError('Unrecognized or foreign thread response.')
    entries = (data.get('thread' if root else 'transcript') or {}).get('entries')
    if not isinstance(entries, list):
        raise TransportError('Upstream returned no transcript entries.')
    state = 'accepted' if root else 'unknown'
    answer = None
    for entry in entries:
        if not isinstance(entry, dict):
            continue
        message = entry.get('message')
        message = message if isinstance(message, dict) else {}
        if root and entry.get('kind') == 'send-message':
            card = message.get('approval') if message.get('type') == 'auto-review-approval' else \
                message.get('ask') if message.get('type') == 'local-tool-permission' else None
            if isinstance(card, dict) and card.get('status') == 'pending':
                return {'state': 'needs_input', 'reply': 'Resolve the pending approval in the official Grok Bot app, then read status.'}
        # Never match the user's prompt (which contains both markers) or preview/tool text.
        if entry.get('kind') == 'send-message' and isinstance(message.get('content'), str):
            text = message['content']
        elif entry.get('role') == 'assistant' and isinstance(entry.get('text'), str):
            text = entry['text']
        else:
            continue
        for terminal in ('completed', 'needs_input'):
            suffix = marker(receipt['task_id'], terminal)
            if text.rstrip().endswith('\n' + suffix) or text.strip() == suffix:
                state, answer = terminal, text.rstrip()[:-len(suffix)].rstrip()
    return {'state': state, **({'reply': answer} if answer is not None else {})}


def _record_completed_dispatch(task_id):
    try:
        import dispatch_registry
        dispatch_registry.complete_external('grok-bot', task_id)
    except Exception:
        pass


def status(task_id, wait=0):
    path = receipt_path(task_id)
    deadline = time.monotonic() + max(0, wait)
    while True:
        with override_store.locked(path):
            receipt = json.loads(path.read_text(encoding='utf-8'))
            if receipt['state'] in ('completed', 'failed'):
                if receipt['state'] == 'completed':
                    _record_completed_dispatch(task_id)
                return receipt
            try:
                update = read_reply(receipt)
                receipt.pop('error', None)
                receipt.pop('reply', None)
                receipt.update(update)
                override_store.write(path, receipt)
            except TransportError as exc:
                # A read failure changes neither delivery nor the last observed state.
                return {**receipt, 'read_error': str(exc)}
        if receipt['state'] == 'completed':
            _record_completed_dispatch(task_id)
        if receipt['state'] in ('completed', 'needs_input') or time.monotonic() >= deadline:
            return receipt
        time.sleep(min(2, max(0, deadline - time.monotonic())))


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    commands = parser.add_subparsers(dest='command', required=True)
    commands.add_parser('doctor', help='Read-only upstream bot listing; no credential output')
    config = commands.add_parser('configure')
    config.add_argument('--bot-id', required=True)
    run = commands.add_parser('run')
    run.add_argument('--prompt-file', type=Path, required=True)
    run.add_argument('--parent-id', required=True)
    run.add_argument('--source-task-id', required=True)
    run.add_argument('--wait', type=float, default=0)
    read = commands.add_parser('status')
    read.add_argument('--task-id', required=True)
    read.add_argument('--wait', type=float, default=0)
    args = parser.parse_args()
    try:
        if args.command == 'doctor':
            out = {'provider': 'grok-bot', 'status': 'ready', 'bots': bots()}
        elif args.command == 'configure':
            out = configure(args.bot_id)
        elif args.command == 'run':
            text = args.prompt_file.read_text(encoding='utf-8-sig')
            if not text.strip():
                raise ValueError('The prompt is empty.')
            out = submit(text, args.parent_id, args.source_task_id)
            if args.wait > 0 and out['state'] not in ('completed', 'failed'):
                out = status(out['task_id'], args.wait)
        else:
            out = status(args.task_id, args.wait)
        code = 0 if out.get('state') in (None, 'completed') else 1 if out['state'] == 'failed' else 3
    except (TransportError, OSError, ValueError) as exc:
        out, code = {'provider': 'grok-bot', 'state': 'failed', 'error': str(exc)}, 1
        if isinstance(exc, TransportError) and exc.diagnostic:
            out['diagnostic'] = exc.diagnostic
    print(json.dumps(out, ensure_ascii=False))
    return code


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