Repository navigation
Description
Problem
Hosts keep offering AGY because the shared proactive-offer instructions name it directly. Offload already has adapter overrides and AGY, Codex, and Claude implementations, but the router, examples, and some adapter behavior retain AGY assumptions.
An installed CLI, saved login, or model catalog does not prove that the user can run a worker. Current adapters can default missing available and quota_available fields to true. This can select a provider whose subscription access expired or whose remaining allowance cannot cover the assignment.
Solution
Choose a compatible worker before offering offload. Verify access to the intended account, billing route, and model; read current usage; estimate the assignment's capacity needs; and rank eligible candidates. Name the chosen worker and give a brief reason in the offer. Preserve explicit user choices, existing authorization, isolation, verification, and retry rules.
The supported promise is any shell-capable orchestrator delegating through a compatible, verified worker adapter. Installing an arbitrary CLI does not make it a supported worker.
This specification implements the decisions recorded during the ADR 0009 design discussion and extends ADR 0003 and ADR 0008. The ADR 0009 and CONTEXT.md edits are currently local and should be included with the implementation. This issue is self-contained and does not depend on those edits having been published.
User stories
- As a user, I want the offer to name a suitable worker and explain its selection, so that I know where my work will run.
- As a user, I want providers without current account access excluded, so that an installed CLI with expired access is not offered.
- As a user, I want valid access to remain usable after cancelling renewal, so that eligibility follows actual entitlement rather than renewal status.
- As a user, I want remaining usage checked before work starts, so that exhausted providers are skipped.
- As a user, I want capacity reserved for the assignment, verification, and one retry, so that selection accounts for more than the first attempt.
- As a user, I want concurrent workers sharing an allowance counted together, so that each worker does not assume the entire balance is available.
- As a user, I want the most suitable eligible worker chosen by capability and expected quality, so that spare quota alone does not determine the choice.
- As a user, I want my explicit worker choice honored when eligible, so that automatic ranking does not override my preference.
- As a user, I want providers with unknown usage excluded from automatic selection, so that missing information is not treated as available capacity.
- As a user, I want to explicitly choose a provider with unknown usage after seeing the uncertainty, so that I can proceed when access and capabilities are otherwise established.
- As a user, I want a clear explanation when my chosen worker cannot run, so that I can choose another provider or keep the work with the orchestrator.
- As a user, I want changed access or quota checked again before dispatch, so that an earlier offer does not authorize an invalid launch.
- As a user, I want retries to preserve the selected worker and model, so that failures do not silently change providers or billing routes.
- As a user, I want equivalent behavior across supported hosts and shells, so that the caller does not determine which worker can be used.
- As a user, I want a declined offer respected for the session, so that worker discovery does not create repeated prompts.
Implementation decisions
Discovery and ownership
- The orchestrator owns selection, admission, quota reservations, verification, and reporting. Adapters own executable discovery, authenticated access and entitlement checks, usage retrieval, model catalogs, vendor arguments, and output normalization.
- Discover installed candidates among configured, supported adapters. Do not launch arbitrary executables as workers merely because they appear on PATH. Preserve explicit adapter configuration and document its precedence with user provider choices.
- Support AGY, Codex, and Claude through the same public contract. Provider or platform limitations must be reported as unsupported or unknown rather than hidden by AGY defaults.
- Keep source skills vendor-neutral. Do not require the Codex desktop usage tool, an interactive host feature, or a particular orchestrator to perform portable selection.
Access and usage contract
Extend and version the adapter protocol and selection evidence. Reconcile docs/adapter-contract.md with docs/worker-adapter-contract.md so the operational catalog/launch interface and lifecycle contract agree.
The normalized preflight record must distinguish:
- Adapter/provider identity and revision, selected model, supported capabilities and effort.
- Installation, authentication, and current entitlement as separate states, including unknown states and exclusion reasons.
- The intended account and billing route, using non-secret identifiers only where needed to detect changed accounts and shared allowances.
- Usage retrieval status, source, observation time, applicable quota bucket identities and scopes, remaining allowance and unit, and reset time when supplied.
- Eligibility, reason, and the policy revision used to derive it.
Missing, malformed, stale, or unsupported observations must never become zero usage or unlimited capacity. Old catalogs with only optimistic booleans do not establish verified automatic eligibility. Document protocol migration and reject incompatible records clearly.
Use bounded, read-only provider queries. Do not renew subscriptions, buy credits, consume reset credits, switch accounts, or fall back to a paid API route during discovery. Confirm entitlement to the intended worker/model, not merely that credentials exist. Expired access excludes the provider; cancellation with continuing entitlement does not.
Usage command availability does not establish a usable headless interface. Validate the installed version's behavior and parse only supported output. If a fresh query cannot be obtained without running a model request, report unknown rather than silently spending quota to probe it.
Eligibility and capacity
Apply eligibility before ranking. Require compatible capabilities and effort, established access, and sufficient known capacity. Unknown usage is eligible only after an explicit user choice with disclosed uncertainty; that exception cannot override known access failure, incompatibility, or exhaustion.
Estimate assignment demand plus verification and at most one retry. Include existing reservations for workers sharing each applicable allowance. Evaluate every binding window and model/account bucket; do not equate token counts with subscription percentages or compare raw percentages across different provider allowances.
Put estimation parameters, conservative cold-start defaults, observation freshness, and probe timeouts in documented, versioned policy rather than scattered vendor constants. The implementation must supply concrete defaults and boundary tests, with a rationale based on supported quota units and recorded runs. If available evidence cannot support a capacity estimate, classify capacity as unknown and apply the explicit-choice rule. No new product interview is required to choose these implementation parameters.
Record estimated versus observed demand and use that evidence to refine estimates. Reserve capacity during admission, release or reconcile it on completion, cancellation, failed launch, and recovery. Make competing admissions against the same observed balance atomic within the orchestrator's managed ledger. External account activity remains a source of uncertainty and is handled through fresh checks and existing exhaustion handoff.
Ranking, offers, and dispatch
- Honor an explicitly requested provider subject to eligibility. Otherwise filter candidates, rank by task capability and expected quality using the existing role preference and separate effort policy, then use normalized remaining capacity as the tie-breaker. Use a stable final identity tie-breaker for reproducibility. Do not use family names as proof of quality.
- Explain the selected worker and the relevant reason concisely. When none qualify, report why and keep unfinished work with the calling orchestrator. An explicit choice that fails eligibility must not silently select another provider.
- Preserve existing proactive-offer thresholds and once-per-session refusal suppression. Existing authorization remains valid; rechecking usage does not require another confirmation for the same selection.
- Revalidate access and capacity at admission and when observations expire or account context changes. If revalidation invalidates the offered choice, report it and require an explicit alternative or handoff.
- Persist provider, model, effort, account/billing context, observation references, reservation, policy revision, ranking reason, and any unknown-usage override in selection and routing evidence. Never persist credentials or raw authentication responses.
- Preserve assignment identity and pinned selection across retry/resume. Keep the maximum two attempts and immediate orchestrator handoff on explicit quota exhaustion. Do not silently switch provider, model, effort, or billing route.
Adapter and host compatibility
Remove AGY-only prerequisites and invocation assumptions from SKILL.md, mode documents, README examples, and project context where the generic contract applies. Adapters must preserve schema, effort, permissions, scope, and output requirements. Specifically fix the Codex path that accepts an inline schema from a mode but treats it as a file path and substitutes a generic schema. Verify effort forwarding and fail explicitly for unsupported requirements.
Update the canonical proactive-offer example to choose a worker. For the existing installation, migrate the shared global instruction source managed by skillshare and verify the derived Claude, Codex, Gemini, and OpenCode context files. The audited hook registrations invoke a synchronization helper; editing generated copies or replacing hooks alone does not fix the source. Keep machine-specific locations out of portable contracts. Document or perform the scoped installation migration without invoking unrelated synchronization, commit, or push side effects.
Keep equivalent behavior in PowerShell 7+ and Bash 3.2+ helper families. Preserve worker-context dispatch guards, filesystem isolation, resource ownership, frozen paths, execution scope checks, and result verification. Adapter compatibility is not a containment guarantee.
Acceptance and verification
Use the existing public launcher/dispatcher seams with fixture adapters and fake vendor executables. Extend the model-routing, adapter, dispatch-control, routing-provenance, and publication/workflow suites. Avoid internal mock-only tests or tests that merely reproduce selection code.
Required scenarios:
- Installed but unauthenticated; authenticated but entitlement expired; cancelled renewal with valid entitlement; wrong account or billing route.
- Exhausted allowance; sufficient allowance; insufficient task reserve; a binding weekly or model bucket despite available short-window quota.
- Missing, stale, malformed, timed-out, or unsupported usage; explicit unknown-usage override; explicit request for a known-ineligible provider.
- Multiple eligible providers with differing quality and capacity; exact ties; deterministic selection; no eligible provider.
- Concurrent admissions sharing one bucket; cancellation and launch failure releasing reservations; recovery without double reservation; fresh observations without double-counting recorded consumption.
- Entitlement or quota changing between offer and launch; pinned provider becoming unavailable on retry; quota exhaustion handing off without blocking sibling workers.
- Equivalent normalized outcomes from AGY, Codex, and Claude fixtures in both shell families, including inline/file schemas, effort, structured results, scope, and no caller override of policy-owned model arguments.
- No worker starts during preflight, no billing mutation occurs, secrets are absent from evidence, and generic host instructions no longer mandate AGY.
Validate real read-only access/usage probes where accounts permit. Report untested provider/version combinations honestly; fixtures alone do not establish live interface support. Existing regression checks must continue passing. Implementation is complete only when documented policy defaults, protocol migration, host instruction migration, and both helper families satisfy these scenarios.
Existing evidence and implementation map
scripts/run-agy-json.ps1and.share generic launchers despite their names; preserve their public compatibility or provide migration aliases if renamed.scripts/dispatch-worker.*own admission and assignment budgets. Extend their existing records rather than adding an unrelated scheduler.scripts/agy-adapter.*,scripts/run-codex-json.*, andscripts/run-claude-json.*own provider details. Current quota defaults are insufficient evidence of access or capacity.model-policy.json, selection records, androuting-outcomes.jsonalready establish policy and retry provenance.- Tests include
test_model_routing.*,test_worker_adapter_contract.*,test_dispatch_control.ps1,test_routing_provenance.ps1, provider adapter suites, and publication compatibility checks. - AGY CLI reference documents
/usageand/quota; its headless documentation warns against inserting slash commands into streaming JSON. - Claude commands documents
/usage. Status-line usage data is version/account dependent and appears after an API response, so it does not by itself establish a fresh pre-dispatch query. - Codex app-server documents
account/rateLimits/read. A live desktop usage read succeeded during the audit, but a portable adapter integration remains pending.
Out of scope
- Arbitrary installed CLI support without a compatible adapter, or new worker providers beyond the existing three.
- Subscription renewal, purchases, reset-credit redemption, automatic login/account changes, or silent billing fallback.
- Silent provider/model switching on failure, additional retries, or workers dispatching nested workers.
- A guarantee that quota estimates ensure completion, a general billing dashboard, or background quota monitoring.
- Broad hook-system replacement, unrelated global instruction cleanup, and changes to the independent grill-with-docs interview workflow.
- Implementing the feature as part of publishing this issue.
Activity