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

references/grok-bot.md

View on GitHub
# Grok Bot external runner

The AgentCompass **Integrations** page includes **Grok Bot CLI** with
**Install/repair**, **Check connection**, and **Usage guide** actions. Install/repair
uses the fixed upstream artifact and scope patch below. It never installs
a global CLI or starts a service. Account enablement remains in **Routing Settings**.
Installed status is separate from gateway connectivity. Entering the page automatically
checks once; refreshing, checking explicitly, or completing installation checks again.
Checks may wake the cloud computer through upstream recovery. There is no periodic
wake timer. The last result and its time remain visible while rechecking; requests
cannot overlap and older callbacks cannot replace newer results. Checks never send
a Bot task. Local installation checks alone do not establish remote availability.
The card exposes only controlled HTTP status/operation, without server payloads or credentials.

Canonical provider/account/model selector: `grok-bot`. The model selector names
the Bot service, not an asserted underlying model. This is a AgentCompass external
runner (like Dot), not a Paseo-native provider or an OpenAI-compatible endpoint.
It uses third-party `grok-bot-cli` from the fixed, unreleased upstream PR158 commit
below (base version 0.12.4), with a small dependency-level scope correction.
Authentication and HTTP transport stay in upstream code.
Underlying model capability, duration and hourly cost follow `accounts.json` `same_model` (`grok-bot` -> `claude-opus-5-5`, dated maintainer declaration); usage-float reads both the shared Grok `credits` meter and the signed-in Grok subscription tier, and runtime capacity matches the Claude subscription at the same monthly price (or scales the nearest Claude plan by monthly price ratio when no exact price match exists; an unreadable tier keeps `grok-bot` in Mode B with `plan unknown`).
A canonical dispatch bundle participates in ordinary automatic routing when
ready and enabled; explicit requests remain supported. The `grok` / Grok Build
integration is a separate launcher; the shipped `quota_sources` binds the Bot to its meter.

Quota sharing with another runner is an explicit account binding in the effective
configuration. A configured binding reuses the owner's observations, freshness,
capacity and active reservations. A service name or plan label alone does not prove
shared quota, model identity, unlimited capacity or a dollar price.

## Minimal dispatch contract

- Automatic routing: a ready, enabled Bot enters the ordinary candidate pool.
  Public scores are conservative low-confidence priors. Personal service ratings,
  route position and shared-pool burn calibration belong in the local fleet.
  Normal capability, account and configured route policies apply.
  Local-only work, file transfer/application and visual inputs are incompatible;
  an explicit refusal of outbound work excludes this remote worker. Private
  material still requires the caller's existing outbound authorization.
- When `quota_sources` (or an account's `quota_source`) explicitly binds the Bot to
  another account, the owner's observations retain their original freshness and reset.
  Missing or stale owner data stays unknown; a Bot snapshot cannot replace it. Fresh
  exhausted owner quota applies its configured launch floor to both runners.
  Capacity/demand and the provisional percent-per-worker-hour prior come from
  the configured quota owner; these are priors rather than measured Bot burn or dollar prices.
  Active dispatch reservations are matched by the configured shared quota pool.
  Without a binding, each account keeps its own observations and reservations.

- Failure: upstream send can time out after acceptance. Replaying can execute the
  same remote action twice. Persist the receipt before calling send; an existing
  receipt is read back, never resent. Unknown delivery stays unknown until a
  correlated reply is found. Recovery is `status` or inspection in the official
  app; a new task ID means a genuinely new submission, not a retry mechanism.
  A failed post-send receipt write retains the known send result and task ID;
  an unreadable or locked existing receipt retains unknown delivery and its
  continuation. Neither means that the task was definitely not sent.
- The runner sends text to a specifically configured Bot, which executes on its
  remote computer. It does not copy local files or apply returned files. Local-only
  tasks and file-transfer flags are unsupported inputs, diagnosed before send.
- Acceptance is a message ID, not completion. Read the rooted thread, require an
  assistant reply carrying this task's final-response marker, and then return the
  answer. Unrelated, partial or unrecognized entries do not prove completion.
  A marker confirms a text answer, not that every background Bot activity stopped.
- Approval cards and a correlated request for help return `needs_input`; the
  adapter never approves, cancels, changes security settings or starts a relay.
  Resolve approvals in the owning app and continue with `status`.
- Missing configuration/transport is a setup diagnostic. Discovery stays local
  and reads no credentials; live readiness is checked by upstream before send.
- Canonical registration: the production decision registry rejects unknown
  provider/account/model/effort combinations. A configured `grok-bot` registers
  only provider/account/model `grok-bot` with no effort, using the existing account
  bundle catalog. This service ID does not normalize to a Grok model-family alias.
  The ordinary allocator ranks its effective configured service profile;
  unknown billing receives no estimated spend or free-usage bonus. Wrong
  model/effort combinations and disallowed host accounts retain their existing
  rejection. Recovery is the documented canonical command/configuration, not a
  validator bypass. Validate the actual record stage with isolated SQLite/ledger
  and mocked transport: `--dry-run` alone does not exercise decision persistence.
  An account outside host policy's `allowed_accounts` is out of automatic
  routing only: a named route (below) still launches, with a warning in the
  decision. Legacy allowlists preserve exclusions; opted-in automatic admission
  follows the [shared discovery contract](provider-discovery.md#automatic-admission-of-newly-discovered-accounts).

## Setup and use

From the repository root (Node >= 22.19.0):

```powershell
python -X utf8 skills/agent-compass/grok-bot/install_cli.py
python -X utf8 skills/agent-compass/grok-bot/install_cli.py --check
python -X utf8 skills/agent-compass/scripts/run_grok_bot.py doctor
python -X utf8 skills/agent-compass/scripts/run_grok_bot.py configure --bot-id <exact-bot-id-from-doctor>
agentcompass providers
agentcompass roll --brief <task.md> --hours 0.1
```

The first four lines are Grok Bot's own installer and setup tool, which `agentcompass` does not wrap; they only exist at these paths in a source checkout (an installed package ships the same files under `data/skills/agent-compass/` inside its own `agentcompass` package folder). In a checkout without an install, write `python -X utf8 agentcompass` for `agentcompass` (from the repository root that is a valid path).

No provider flags are needed for automatic selection. To honor a user explicitly
requesting Grok Bot, the existing override remains available:

```powershell
agentcompass roll --brief <task.md> --hours 0.1 --provider grok-bot --account grok-bot --model grok-bot --basis 'User requested Grok Bot'
```

Use a dedicated Bot for AgentCompass tasks. Configure validates the ID with an
upstream read-only bot listing, then saves only the ID under
`~/.agent-compass/grok-bot/config.json`. Authentication remains in upstream/native
desktop handling under the current Windows user. No tokens belong in this config.
If `grok-bot` is kept out of automatic routing in AgentCompass's account settings,
the named command above still launches it, with a warning; switching it on only lets
the router choose it by itself. `configure` does not edit that policy; subsequent
discovery admits new ready accounts only when automatic admission is enabled.
A logged-in native account with readable, valid stored credentials is required.
Opening the cloud-computer preview or keeping an app process running is not required
by the CLI. It obtains a route on demand through upstream `EnsureSandBox`, including
when the optional gateway descriptor is absent. This can wake the remote computer.
Initial authentication, revoked/expired access tokens, and unsupported local secret
formats still require the official authentication flow; no token-refresh service is added.
Native parking/storage policy can remove descriptors. The adapter does not recreate
descriptors, change storage policy, or persist fresh routes/tokens.

## Fixed upstream recovery dependency

`upstream.json` pins [PR158](https://github.com/ScriptedAlchemy/grok-bot-cli/pull/158)
at commit `e76b5a065b6202ee34c337ea62d3a7521d4ecf71`, the public archive SHA256,
and all 29 original artifact files. This is an **unreleased upstream snapshot**, not
an npm upgrade to a new published version. `install_cli.py` verifies the archive and
full artifact tree, applies `dependency_patch.py` to both CLI bundles, verifies
patched hashes, and replaces only its scoped `runtime/` installation. `--archive`
accepts an offline copy of the same pinned archive. `--check` is read-only and
verifies installed identity, not remote health. No upstream install hook is run.
The old npm/v3-only installation is no longer used; a global CLI is never consulted.

Scope contract: native descriptor entries bind an account, but their payloads do
not bind the selected team. The dependency patch therefore obtains a fresh route
using the upstream active-account credential reader and `EnsureSandBox`, instead
of trusting a cached descriptor's team. It snapshots account/team, checks them
after Ensure and before gateway requests, and refuses changes before delivery.
Missing credentials, corrupt teams, unsupported account scopes, and ambiguous
legacy top-level team storage fail honestly; it does not guess or migrate secrets.
The original upstream decryption helpers and destination/redirect checks remain
unchanged. Ensure receives the account access token; gateway calls use only the
returned gateway credential. Explicit upstream environment overrides retain their
upstream semantics and do not get native-account fallback.

Upstream's allowlisted hibernated-read recovery remains bounded to one retry of
that read. `send` resolves the Bot in the same session, then sends once; a write
failure is never replayed. The runner budget is 210 seconds to accommodate the
bounded cold chain and local startup. A timeout after possible send remains
unknown; the owned CLI process tree is cleaned up and the existing receipt is
continued, never blindly resubmitted.
On Windows this uses AgentCompass's `pywin32` runtime and an owned Job object.
A small stdin-gated launcher joins the Job before it can start the CLI; cleanup
waits for owned process exit handles even if an intermediate parent exited first.
An unavailable Job setup fails before the CLI is released.

Offline checks:

```powershell
python -X utf8 -m unittest discover -s skills/agent-compass/grok-bot -p 'test_*.py'
node --test skills/agent-compass/grok-bot/test-recovery.mjs
```

The Node tests execute the installed upstream modules from both bundles with
synthetic encrypted Windows storage and mocked HTTP. They cover absent descriptor
bootstrap, same-scope recovery, list-417/Ensure/list-success followed by exactly
one send, no write replay, scope drift, and missing/corrupt/legacy credentials.
No app process, preview, native credential read, or real Bot submission is needed.

`roll` records the explicit user choice through the existing router and returns
`continuation_argv`. Run that exact command to read the answer without resending.
Receipts live under `~/.agent-compass/grok-bot/tasks/`. Exit 0 means completed,
3 means pending/unknown/needs_input, and 1 means a setup or rejected-send failure.
Once a correlated final reply proves completion, roll returns `completed: true`,
`launched: true` and `caller_action: completed`, even if the receipt retains
`delivery: unknown` as evidence that the original send acknowledgement was lost.
There is no background watcher: the caller owns continuation and relays questions
to the real parent. A repeated roll with the same parent, task and prompt reuses
the receipt. Use the original receipt if configuration or task text changes.

For a smoke test, put `Reply with AGENTCOMPASS_GROK_BOT_OK. Do not use tools,
files, connected apps or other side effects.` in a temporary brief and use the
roll command above. Submit once, then use continuation. Do not send repository
contents just to test connectivity.

The transport remains the fixed upstream CLI plus the documented scope patch.
Upstream CLI prompt arguments are subject to the Windows
command-line size limit; the adapter diagnoses oversized prompts rather than
silently truncating them. Responses without the agreed final marker remain open
for inspection in the app. No automatic completion callback or remote file
synchronization is provided.
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: 472kUpdated 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