Index of every page on this site: llms.txt
All skills
kunchenguid avatar

/quota-array-dispatch

@427056c
by Kun Chenkunchenguid/firstmate9k stars
2,779
Run it yourself

Load when a crew-dispatch rule or default resolves to more than one profile candidate, or a Claude ship or scout is dispatched from a home that declares config/claude-accounts.

  • 1 file
  • 15.9 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/kunchenguid/firstmate/quota-array-dispatch

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈50 tokens for metadata: the name and description. ≈4k when used: this file.

Description uses 2.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈199 characters, or 2.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

quota-array-dispatch

This skill is the single owner of the completion-aware profile-array selection procedure. AGENTS.md section 4 owns the always-loaded intake boundary, load trigger, malformed-config refusal, every-candidate accounting, and strongest-reasoning/tie safety rules. harness-adapters owns harness verification, model/provider discovery, and effort fallback. quota-axi remains data-only: it publishes spendPriority as a comparable scalar and never recommends, selects, ranks, or infers a route. Do not add a daemon, opaque composite score, routing wrapper, hard-coded model-specific policy, or producer-side route recommendation. The worker helper and typed resolver own their deterministic mapping boundaries.

Shared-quota opt-out

When the home's config/crew-dispatch.json declares a top-level "shared_quota": true, this home draws every provider's usage from one single shared budget, so per-provider quota rows do not describe what is left, and this skill's quota snapshot, the quota parts of the eligibility and runway gates, and spendPriority ranking are off by home declaration. Make no quota-axi call, apply no quota row, quota floor, runway gate, or spendPriority rank, and choose the matched rule's first declared profile that its authoritative catalog supports and that meets the required reasoning class; catalog eligibility and reasoning-class fit still apply. preferred_provider is not a quota signal, so it still applies: preferred_provider still narrows the pool; declared order then picks within it. Account for every candidate as always, stating in place of quota evidence that quota ranking is off by home declaration. The declared value must be a boolean; anything else is an actionable configuration error.

Worker-side quota helper

The canonical shell helper for a worker that has already performed its model-selection reasoning and now needs to pick the first viable candidate is bin/fm-quota-choose.sh. Pass it the intake's already-captured default TOON or permitted JSON fallback through stdin or --snapshot; it never takes another quota snapshot, so it selects from the same quota state as the intake. Pass each candidate as harness:model, with earlier candidates preferred. The helper's header owns its provider mapping and quota selection mechanics. An exhausted_now runway vetoes the candidate. The helper selects a candidate only when its applicable quota has a known effectivePercentRemaining greater than zero. This is an optional narrow helper with a known limitation: it maps each harness to one primary provider family only, so a candidate whose established provider differs from that primary family is checked against the wrong quota row. omp has no primary family, so the helper keys an omp: candidate on its model prefix, mapping only openai-codex/ and claude-bridge/ and refusing every other prefix; the helper's header owns that mapping. Authoritative multi-provider routing - including provider discovery from the harness catalog and quota matching by that explicit provider - stays owned by this skill's intake procedure above and AGENTS.md section 4, not by the helper. Use it only when the brief already fixed the candidate order and every candidate's provider is the harness's primary family. It does not replace the reasoning-class, runway-feasibility, or authentication gates above. Firstmate can optionally arm bin/fm-procevent-quota.sh for a recurring mid-task check that wakes when the tracked provider drops below its configured threshold or its runway becomes exhausted_now. The opt-in typed resolver has its own documented gates. It never removes this skill's authority, and its ambiguous, escalate, and error outcomes return here.

Claude account list

When the home declares config/claude-accounts, each Claude candidate is one candidate per declared account, and the spawn needs the chosen account as --account <entry>. Measure them with bin/fm-claude-account-quota.sh [--model <model>] instead of the default TOON's single claude row, which reads only the ambient account; its header owns the per-account read and output. It prints data only, never a choice: each account's applicable scopes and any uncertainty it could not measure. Apply the three gates below to each account's rows, taking a projected runway's time from the row's own usableRunwaySeconds, rank the eligible ones by their limiting scope's spendPriority exactly as for profiles, and pass the chosen entry as --account <entry>. A genuine tie or no rankable account is the same terminal case as below: decide in the open from the rows or ask the captain, never by file order. Account for every declared account in the rationale, including unmeasured ones. A typed-resolver clear profile for Claude still needs this step's --account. The account is chosen once, at intake: a relaunch keeps the recorded one, and only an explicit --account relaunch moves a task (docs/configuration.md owns the contract).

Read the default TOON

When the home declares the shared-quota opt-out, skip this section's quota reading and every quota-derived check built on it (quota rows, floors, runway, and spendPriority); catalog eligibility and reasoning-class fit still apply. Start each intake by running quota-axi once with no --json, and reuse that TOON for every candidate. Post-consolidation quota-axi (the floor owned by bin/fm-quota-axi-lib.sh) puts spendPriority in the default quota[] block beside effectivePercentRemaining, runway, confidence, limitedBy, and resetsAt. Sparse exhaustion[] carries finite-runway seconds only for projected_exhaustion and exhausted_now. Sparse attention[] names auth, stale, and unmeasurable facts. spendPriority is THE quota-perspective ranker. It already computes the economics that older instructions reconstructed by hand from headroom, pace, reserve, and window-id lists; do not recompute those. Do not read --json on the normal path, and do not reach for --full to rebuild that economics.

After reading the TOON, fall back to one quota-axi --json call only when that TOON is genuinely ambiguous for the decision, or when the installed quota-axi is somehow below the floor so its TOON lacks spendPriority. Ambiguous means a candidate's spendPriority is the literal unknown or unmeasurable, a real tie still needs extra evidence, or a candidate's eligibility is unclear from quota[] plus attention[]. The fallback therefore has an explicit TOON-then-JSON call sequence; reuse its JSON result and do not take any further quota snapshots. Below-floor is rare: bootstrap enforces FM_QUOTA_AXI_MIN and normally reports OUTDATED before dispatch; if an intake somehow reaches an older build whose TOON lacks spendPriority, use the defensive --json fallback rather than treating the missing scalar as healthy. --json is a defensive belt, not a habit; never reach for it because it feels more complete. Read quota-axi auth --json only when a candidate's credential surface is in question.

For each candidate, preserve explicit harness, model, and provider; harness-adapters owns identity, and model/provider never infer harness.

Three gates, then provider preference and spendPriority

Apply the three cheap orthogonal gates first. spendPriority ranks only among candidates that pass all three. It cannot override a hard-gate failure, and it is never hidden inside a new composite score.

1. Eligibility

Outside those documented mappings, deterministic shell must not infer a provider family or credential store from a harness, model, or source name. You establish the remaining relations yourself, in the open, from the candidate's own authoritative catalog (harness-adapters owns the per-harness discovery surface) plus the one intake snapshot.

Confirm the catalog lists the candidate's model and record the provider family it reports. A model the catalog does not list is concrete contradictory evidence: block that candidate and quote the catalog result. Apply quota at the granularity the vendor actually supplies. A provider-level or all_models/all_products scope bounds every model you established in that family within the candidate's matched account, including one with no window of its own. A named-model or named-product scope is an additional bound for that model alone. A scope the vendor reports outside those names, such as an Antigravity tier, bounds a candidate only when its profile declares that exact scope as quota_scope; never infer the tier from the model name. Match the candidate to its quota[] row by that established provider, its accountKey when the snapshot is schema 6 (a Pi lane's auth provider id such as openai-codex-work, or codex-home for native Codex including Pi's codex-native/ adapter, then the default row, else unmeasured; never a row picked by position, never rows summed across accounts), and scope; a stale, auth-required, or unmeasurable scope is named in attention[] instead of a fabricated number.

A candidate authenticates through its own tuple's surface; another harness's CLI can never gate it, and harness=pi with model=xai/grok-* is Pi using xAI rather than the standalone Grok CLI. quota-axi auth --json lists each provider's credential sources independently, so read the one source the candidate actually uses rather than collapsing a provider to a single status. A provider can carry a healthy source beside a missing or expired one; the unused source's state is not the candidate's state. A Pi-hosted family may authenticate through the vendor's own store with no pi:-prefixed source at all, which is normal and never evidence against the candidate.

Uncertainty and ineligibility are different findings:

  • No model-level window, no matching auth source, an unmeasurable or unknown scope, or a surface quota-axi does not model at all is disclosed uncertainty. Keep the candidate eligible, state the unknown, and prefer known viable evidence when otherwise comparable.
  • An expired credential is a short-lived session token the owning vendor renews on next use, not a sign-out.
  • Only concrete contradictory evidence blocks: an authoritative catalog proving the model unsupported, or proof that the credential the candidate actually selects is unusable.
  • Reserve login wording for that proven-unusable case, and name the harness, model, surface, and evidence.

When a credential's local classification is the only thing standing between a candidate and a block, get ground truth before blocking. bin/fm-vendor-auth-probe.sh is the only approved vendor-credential probe; its --help owns the registered probes and mechanics. It takes no harness, model, or provider and returns a fact, not a route: only authenticated and unauthenticated are ground truth, while indeterminate, timeout, and unavailable establish nothing and must never be read as either outcome. Never launch a vendor CLI yourself, and never probe a credential store the candidate does not use. Grok prepaid credits are unrelated to paid-window headroom; never read them as exhaustion.

Malformed configuration is an actionable error, not a candidate to rank around.

2. Reasoning-class fit

Keep only candidates that meet the required reasoning class for this task (a simple bug fix versus very-difficult design). Never use spendPriority or remaining quota to silently replace that class. When every remaining candidate is tight, dispatch inside the strongest-reasoning class if one of those candidates can proceed, or stop and report that the strongest-class choice cannot proceed rather than downgrading it to spend or conserve quota.

3. Runway feasibility floor

Known runway that will not last until the inspectable likely-completion horizon fails this gate, even when that candidate has the highest spendPriority. Read runway from the quota[] row: through_reset passes this generic feasibility floor because the window reaches its refill without exhausting; never compare its resetsAt with the completion horizon as though reset were an exhaustion deadline. exhausted_now is zero, and projected_exhaustion uses the matching exhaustion[] row's usableRunwaySeconds. A high spendPriority on a nearly empty window that will exhaust soon must not route into a mid-task stall. Unknown or unmeasurable runway stays eligible with disclosed uncertainty and is never assumed to pass. Do not invent a generic percentage floor, and honor an explicit captain floor for a candidate when one exists.

Rank by spendPriority

Among candidates that pass all three gates, first apply the optional top-level preferred_provider from config/crew-dispatch.json. Its schema is owned by Crew dispatch profiles. Within the already matched rule or default, restrict ranking to eligible candidates of that family when any remain. Do not introduce other profiles, change a Claude-only rule, or override an explicit captain choice or approval requirement. Only concrete evidence that every matched preferred candidate is ineligible authorizes fallback to other families. Unknown quota, missing account evidence, and unrankable scalars do not establish ineligibility. If preferred candidates remain eligible but none can be ranked, escalate with that uncertainty instead of switching families. When no matched profile belongs to the preferred family, preserve the rule's candidate set. With the field absent, keep the existing candidate set unchanged. Print the preferred-family decision, including the reason for any fallback.

Within the resulting candidate set, pick the highest known spendPriority. A higher known scalar is better: positive means paid allowance is on track to reach reset unused, 0 is exact utilization, and negative means overdrawn against the reset clock. Rank only from comparable known scalars. Never treat absent, unknown, or unmeasurable spendPriority as zero or as healthy; 0 means exact utilization, a different claim from unknown. An unknown spendPriority keeps the candidate eligible with disclosed uncertainty. Prefer known viable evidence when otherwise comparable. After the permitted TOON-to-JSON fallback, escalate to Firstmate instead of routing if no candidate can be ranked or runway uncertainty prevents proving the feasibility floor for any candidate that could be selected. Never resolve that terminal uncertainty by treating unknown as healthy or by choosing arbitrarily. Show the scalar or the literal unknown in the rationale; do not hide it in a score.

Do not compare headroom against runway by hand. Do not use pace or signed reserve as a later tie-break layer. Do not read aheadWindowIds, behindWindowIds, onPaceWindowIds, limitingWindowIds, or other window-id lists to reconstruct what spendPriority already computed.

Genuine ties: stop and report every tied candidate for captain choice. Do not select by array order, harness name, or another arbitrary identity ordering. Report duplicate concrete profiles as a configuration error.

Account for every candidate visibly before selecting or escalating, naming its catalog evidence, provider relation, applicable quota and authentication facts, remaining uncertainty, fit and reasoning class, spendPriority, and runway-versus-horizon result. A blocked credential report must name harness, model, authentication surface, and concrete failure evidence; never emit a bare Grok unauthenticated statement. Never conclude with an unexplained "best quota" label.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 427056c. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 3 weeks ago
user-invocable
false
metadata
{
  "internal": true
}

README badge

README badge for kunchenguid/firstmate/quota-array-dispatch