[Research] Provider-specific post-reset activation to anchor quota windows #823

Area

Authentication / account pools / provider quota lifecycle

Status

Blocked on provider-specific evidence and policy design.

Do not open an implementation PR for generic post-reset activation until a supported provider has a documented and reproducible upstream contract proving that such activation is both effective and safe.

Goal

Determine whether specific providers can safely support an opt-in background operation shortly after a natural quota reset that establishes the next quota-window anchor as early as possible.

This issue does not assume that such behavior exists generically.

Any eventual automation must be provider-specific and evidence-backed.

Original observation

The motivating observation was that, for some accounts, a quota window appeared to behave like:

quota resets at T
    ↓
first post-reset use at T + N
    ↓
next quota window appears anchored from T + N

For example:

reset available: Aug 1 17:00
first use:       Aug 2 19:00
next reset:      Aug 9 19:00

This suggests that early post-reset use might influence the next reset window.

That observation is not sufficient evidence for automation.

It must first be established whether:

• the behavior is real and deterministic;
• it applies to a specific provider/account product;
• the first post-reset request actually establishes the next window;
• the behavior is documented or reproducibly demonstrated;
• sending a synthetic request is permitted and safe.

Important distinction: local account switching is not activation

Changing OpenCodex's selected or active account is only local routing state.

Conceptually:

OpenCodex active account
A -> B

does not prove that:

provider received a request for B

and therefore cannot establish a remote quota window.

Do not implement this feature by simply calling the existing account-switch API.

A real activation would require a provider-side operation.

Required provider evidence

Before supporting a provider, prove all of the following.

1. Window anchoring behavior

Demonstrate that the relevant quota window is actually anchored by the first qualifying use after a natural reset.

The evidence should distinguish this from:

• a fixed calendar reset;
• a rolling window;
• delayed provider reporting;
• cached quota metadata;
• coincidence between first use and reported reset time.

2. Activation operation

Identify the exact upstream operation that establishes the next window.

This may be:

a documented activation endpoint

or, if no dedicated endpoint exists:

a minimal ordinary inference request

but only if its behavior has been proven.

Do not invent a provider-independent “activation request.”

3. Success evidence

Define how OpenCodex can verify that the activation actually succeeded.

Examples might include:

• authoritative quota state changing to a new generation;
• a new reset timestamp becoming visible;
• an explicit upstream success response whose documented semantics establish the window.

A plain HTTP 200 is not automatically sufficient.

4. Cost

Prove whether activation consumes:

• request quota;
• tokens;
• paid usage;
• reset credits;
• other scarce capacity.

The feature should not describe the operation as “free” or “minimal” without evidence.

5. Provider terms and intended behavior

Do not automate artificial quota-window manipulation if the provider prohibits it or the behavior relies on an unintended exploit.

Provider-specific support should require a reasonable basis that the operation is permitted.

Provider capability gate

If eventually implemented, post-reset activation must be an explicit provider capability.

Conceptually:

supportsPostResetActivation: true

or an equivalent richer contract.

The capability must define enough provider-specific metadata to know:

• which quota window it applies to;
• how reset is detected;
• which operation activates the window;
• how success is verified;
• whether the operation consumes quota/cost;
• timing/grace requirements.

Unknown providers default to:

unsupported

Do not infer support from:

• OpenAI compatibility;
• adapter type;
• presence of quota/reset timestamps;
• model names;
• other providers exhibiting similar behavior.

Trigger

The trigger is a natural provider quota reset.

It is not:

• reset-credit expiry;
• reset-credit redemption;
• a generic 429;
• local cooldown expiry;
• account failover.

The runtime should require fresh provider-specific evidence that the relevant quota generation has reset.

A cached reset_at timestamp becoming older than Date.now() is not by itself sufficient authority to dispatch a synthetic request.

Opt-in only

Any eventual background activation must be explicitly enabled.

Default:

off

The user should understand that enabling the feature permits OpenCodex to send a provider request when no user request is currently pending.

This is materially different from normal proxy behavior.

Output isolation

A background activation operation must not create visible model output in an unrelated user conversation.

It must not:

• append assistant history;
• create tool calls;
• alter a conversation's previous_response_id chain;
• emit events to an active client;
• attach output to the wrong thread.

If the provider requires an operation that cannot be isolated safely, that provider should not support automated activation.

Normal routing must not be mutated

Background activation must not change:

• the user's active account;
• session affinity;
• account priority ordering;
• an existing conversation's assigned account.

Conceptually:

conversation X -> account A
background activation -> account B
conversation X remains -> account A

Do not implement activation by temporarily mutating global routing state and then “switching back.”

The activation path needs explicit account selection independent of normal affinity.

Multiple accounts

If several supported accounts become eligible for activation close together, operations must be bounded.

Possible behavior:

A
B
C

processed under a deterministic queue/concurrency contract.

Do not launch an unbounded burst of synthetic requests after startup or after several simultaneous reset events.

Single-flight and deduplication

At most one activation operation should run for the same:

account + quota-window generation

Concurrent quota refreshes, timers, or restart recovery must not trigger duplicates.

The system needs a stable generation identity or another conservative deduplication rule before automatic dispatch is allowed.

Restart and crash behavior

Restart must not cause blind replay of scheduled activation work.

On startup:

load pending intent
    ↓
refresh authoritative provider state
    ↓
same window still needs activation?
    ├─ no  -> discard
    └─ yes -> resume only under the accepted provider contract

If OpenCodex cannot determine whether an activation already happened before a crash, fail conservatively rather than repeatedly consuming quota.

Cancellation

Disabling the feature or removing the account before dispatch must cancel pending activation.

Shutdown should cancel undispatched work.

If a provider request has already been sent, OpenCodex must record the real outcome rather than claiming it was cancelled.

Credential security

Background activation uses stored provider credentials and therefore has a stronger security boundary than local account switching.

Never expose:

• access tokens;
• refresh tokens;
• authorization headers;
• API keys;
• raw provider payloads;
• unsafe account identifiers.

The activation operation must use the same credential-destination protections as normal provider requests.

No background request may redirect credentials to an untrusted host.

Observability

Record bounded events such as:

post_reset_activation_scheduled
post_reset_activation_skipped
post_reset_activation_dispatched
post_reset_activation_confirmed
post_reset_activation_failed

Include safe information such as:

provider
opaque account reference
quota-window type
generation/reset reference
result
skip/failure reason

Do not log prompts, credentials, or unrestricted response bodies.

Relationship to #657

#657 owns rejection-triggered failed-turn quota recovery and optional reset-credit redemption.

#823 does not replay a failed user request.

Its trigger would be:

natural quota reset
+
provider-specific activation contract

Relationship to #822

#822 owns proactive reset-credit redemption before credit expiry.

A reset credit is a separate upstream resource from a natural quota-window reset.

Redeeming a reset credit must not automatically trigger this feature unless a future provider-specific contract explicitly proves that composition is safe.

Relationship to #821 / #695

#821 delivered user-controlled account priority ordering.

#695 owns generic OAuth account selection, affinity, health and failover.

Background activation must not mutate or bypass those routing decisions.

It should address a specific account directly under its provider capability rather than temporarily changing the generic account-pool assignment.

Relationship to #1146

#1146 tracks local cooldown-expiry notifications.

A cooldown ending does not prove that a natural provider quota window reset or that activation should run.

Required research artifact

The next useful contribution to this issue is provider evidence, not implementation.

For a proposed provider, document:

provider:
quota window:
authoritative reset signal:
evidence first use anchors next window:
activation operation:
success verification:
quota/cost consumed:
terms/policy evidence:
failure behavior:

Include reproducible observations with secrets removed.

Once one provider satisfies this evidence gate, a focused provider-specific implementation design can be proposed.

Out of scope

Until provider evidence exists, do not implement:

• generic post-reset synthetic requests;
• “brief account switching” as activation;
• automatic model prompts after every observed reset;
• generic provider inference from reset_at;
• global routing mutations to touch each account;
• reset-credit redemption;
• failed-turn replay;
• local cooldown recovery.

Acceptance criteria

Research gate

• At least one specific provider has reproducible evidence that first post-reset use anchors the next quota window.
• The provider's relevant quota-window type is identified.
• A specific upstream activation operation is identified.
• The operation's success can be verified authoritatively.
• Cost/quota impact is known.
• Provider policy/terms do not prohibit the automation.
• The behavior is deterministic enough for automation.

Implementation gate

Only after the research gate passes:

• Activation is explicit opt-in and defaults off.
• Support is provider-capability-gated.
• Normal account selection and conversation affinity are not mutated.
• Background output is isolated from user conversations.
• One activation occurs at most once per account/window generation.
• Restart/crash behavior cannot blindly duplicate activation.
• Disabling/removing an account cancels undispatched work.
• Provider credentials remain confined to their trusted destination.
• Concurrent account activations are bounded.
• Activation outcome is safely observable.
• Focused provider-specific regression tests exist.
• Accepted implementation is merged into dev.

Related

• [Feature]: opt-in reset-credit recovery after verified pre-stream quota exhaustion #657 — rejection-triggered quota recovery/reset-credit use.
• [Feature]: opt-in crash-safe reset-credit auto-redemption before expiry #822 — reset-credit auto-redemption before expiry.
• [Feature]: Generic OAuth account-pool failover with session affinity and quota-aware selection #695 — generic OAuth account-pool runtime.
• [Feature] Let users define the priority order for automatic account failover in the Codex pool #821 — account priority ordering.
• [Feature]: provider/key cooldown recovery notifications #1146 — cooldown recovery notifications.