@atmorouter/helper 0.2.2 → 0.2.4

package/README.md

@@ -2,17 +2,17 @@
 
 Configure coding agents for AtmoRouter, get IDE setup instructions, discover model IDs, and check a key without running inference. Changes are previewed first; automatic configuration merges existing settings and creates backups.
 
-Requires Node.js 22 or newer. The public npm package uses the `yaml` runtime dependency to safely parse and preserve YAML configuration. No npm account or repository access is required.
+Requires Node.js 22 or newer. The package uses the `yaml` runtime dependency to safely parse and preserve YAML configuration. No repository access is required. Version 0.2.4 adds capacity cooldown and bounded retry guidance. The commands below use the versioned website archive.
 
 ```sh
-npx @atmorouter/helper@0.2.2 --help
-npx @atmorouter/helper@0.2.2 targets
-npx @atmorouter/helper@0.2.2 models --search claude
-npx @atmorouter/helper@0.2.2 configure --target opencode --model YOUR_MODEL_ID
-npx @atmorouter/helper@0.2.2 configure --target claude --model YOUR_MODEL_ID --write
+npx https://atmorouter.dev/downloads/atmorouter-helper-0.2.4.tgz --help
+npx https://atmorouter.dev/downloads/atmorouter-helper-0.2.4.tgz targets
+npx https://atmorouter.dev/downloads/atmorouter-helper-0.2.4.tgz models --search claude
+npx https://atmorouter.dev/downloads/atmorouter-helper-0.2.4.tgz configure --target opencode --model YOUR_MODEL_ID
+npx https://atmorouter.dev/downloads/atmorouter-helper-0.2.4.tgz configure --target claude --model YOUR_MODEL_ID --write
 ```
 
-The same version is available as `https://atmorouter.dev/downloads/atmorouter-helper-0.2.2.tgz`, with a `.sha256` checksum alongside it. Run it with `npx https://atmorouter.dev/downloads/atmorouter-helper-0.2.2.tgz --help`.
+The same version is available as `https://atmorouter.dev/downloads/atmorouter-helper-0.2.4.tgz`, with a `.sha256` checksum alongside it. Run it with `npx https://atmorouter.dev/downloads/atmorouter-helper-0.2.4.tgz --help`.
 
 With no command, the interactive wizard searches live text models and previews the selected setup. `configure` is preview-only unless `--write` is supplied. Non-interactive file writes additionally require `--yes`. Tests use temporary `--config-dir` folders, never real agent settings.
 
@@ -36,13 +36,27 @@ Guided targets print the steps to perform in your installed client; they do not
 
 Use `--shell powershell` for PowerShell snippets. `--config-dir PATH` explicitly selects a settings folder. `--offline` skips live model validation; it does not establish model availability or client compatibility. Preview output shows intended changes, not existing file contents.
 
+## Budgets after setup
+
+After an automatic setup, preview, manual IDE integration, or bridge launch, open [Budgets](https://atmorouter.dev/dashboard/budgets). Select the actual API key used by that client, then choose an all-model percentage rule for broad coverage. Illustrative examples only: 20% below official rates or 50% below official rates. Review the displayed rates and choose your own limit. A family or exact-model rule covers only that target. Account and key rules both apply; the strictest input and output limits win. The helper never saves or raises budget rules automatically.
+
+Market prices and tiers vary. A “From” price is a snapshot of the cheapest advertised offer, not a guaranteed execution price. Setup and key checks do not prove current availability within your limits. The CLI sends these reminders to stderr so piping an environment snippet from stdout still produces valid shell commands. Generated configuration files contain client settings only.
+
+## Waiting and retries in your harness
+
+Routing can wait up to 30 seconds for capacity within your caps. This wait is fixed; generation time is additional. Set the client timeout to allow both routing and the expected generation duration. The local bridge defaults to a 120-second total timeout, including routing and generation; a caller using the bridge must allow for that total duration.
+
+For HTTP 429 or temporary availability failures, honor `Retry-After` when present. Otherwise use bounded exponential backoff with jitter. Avoid blind retries and duplicate in-flight requests. After a timeout or interrupted stream, review the client outcome and usage before deciding to resend; a lost response does not establish that the request was unprocessed. The bridge does not automatically retry inference or raise price caps.
+
+Correct invalid requests before retrying. For authentication errors, verify the key and account eligibility. For insufficient balance, review Billing. For `balance_temporarily_reserved`, allow existing requests to finish. For `price_limit_unavailable`, wait for capacity within your caps or deliberately review your budget. Adding funds does not resolve pricing availability.
+
 ## Credentials
 
 The helper never saves or prints your API key. Set `ATMOROUTER_API_KEY` privately through your shell or secret manager. OpenCode reads `{env:ATMOROUTER_API_KEY}`; Oh My Pi reads the environment variable named by `apiKey`. Continue uses `${{ secrets.ATMOROUTER_API_KEY }}`; for the IDE, manually add the secret to `~/.continue/.env` without committing that file. For Claude Code, set `ANTHROPIC_AUTH_TOKEN` to the same key before launching Claude. Guided IDE targets require you to enter the key in the client's own credential UI.
 
 ```sh
 export ANTHROPIC_AUTH_TOKEN="$ATMOROUTER_API_KEY"
-npx @atmorouter/helper@0.2.2 check-key
+npx https://atmorouter.dev/downloads/atmorouter-helper-0.2.4.tgz check-key
 ```
 
 `GET /v1/models` is public and **cannot validate a key**. The optional explicit key check sends an empty JSON body to `/v1/chat/completions`. Only HTTP 400 with `model is required` proves the gateway accepted the credential before rejecting the body. No model is selected, no inference is forwarded, and nothing is billed. The check consumes a rate-limit slot. HTTP 401 rejects the key; 429 and all other responses are inconclusive. The key-check request has a 15-second timeout and refuse redirects. Catalog discovery has a 30-second timeout. No custom upstream origin can receive your key.
@@ -53,13 +67,13 @@ The public gateway implements Chat Completions and Anthropic Messages, not `/v1/
 
 ```sh
 # Prints instructions only; does not start a server or write Codex settings.
-npx @atmorouter/helper@0.2.2 configure --target codex --model YOUR_MODEL_ID
+npx https://atmorouter.dev/downloads/atmorouter-helper-0.2.4.tgz configure --target codex --model YOUR_MODEL_ID
 
 # Starts a temporary local bridge and launches your installed Codex CLI.
-npx @atmorouter/helper@0.2.2 codex --model YOUR_MODEL_ID
+npx https://atmorouter.dev/downloads/atmorouter-helper-0.2.4.tgz codex --model YOUR_MODEL_ID
 
 # Or run the bridge separately and follow its printed client instructions.
-npx @atmorouter/helper@0.2.2 bridge --port 43187
+npx https://atmorouter.dev/downloads/atmorouter-helper-0.2.4.tgz bridge --port 43187
 ```
 
 Set `ATMOROUTER_API_KEY` in the process environment before starting the bridge. It listens on loopback only, authenticates local requests, and forwards inference to the official AtmoRouter endpoint. The launcher preserves Codex's permission defaults. It does not weaken approvals or sandbox settings.
@@ -87,3 +101,8 @@ npm run test:package
 The packed-install check uses an isolated npm cache and the public registry, without requiring account credentials. The archive contains only the package manifest, README, CLI, and three library modules; tests, scripts, local settings, and keys are excluded.
 
 Client references: [Claude Code](https://code.claude.com/docs/en/llm-gateway), [OpenCode](https://opencode.ai/docs/providers/), [Oh My Pi](https://github.com/can1357/oh-my-pi), [Continue secrets](https://docs.continue.dev/customize/deep-dives/secrets), [Cursor keys](https://cursor.com/help/models-and-usage/api-keys), [VS Code language models](https://code.visualstudio.com/docs/agent-customization/language-models), [Cline](https://docs.cline.bot/provider-config/openai-compatible), [Roo Code](https://docs.roocode.com/providers/openai-compatible), and [Codex custom providers](https://developers.openai.com/codex/config-reference/).
+
+
+For explicit capacity refusals before any output, use `Retry-After` or `error.retry_after_seconds`, including errors carried inside HTTP 200 SSE streams. Wait at least that delay plus a small random jitter, with at most three automatic retries. Without a delay hint, wait 2, 4, then 8 seconds plus jitter. Review Usage and tool outcomes before resending a request that produced output or has an uncertain outcome.
+
+Capacity pauses use the model, API protocol and effective input/output price ceilings. Customer-specific ceilings are isolated by account. Three capacity refusals within one minute start a 15-second pause. One request probes recovery, with pauses increasing to 30 and then 60 seconds if capacity remains unavailable. The helper prints this guidance during setup. Retry behavior is controlled by the harness.

package/bin/atmorouter-helper.mjs

@@ -6,7 +6,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import {spawn} from 'node:child_process';
 import {setDefaultResultOrder} from 'node:dns';
-import {models,modelId,checkKey,planConfiguration,writeConfiguration,environment,INTEGRATIONS,guidedConfiguration} from '../lib/helper.mjs';
+import {models,modelId,checkKey,planConfiguration,writeConfiguration,environment,INTEGRATIONS,guidedConfiguration,SETUP_GUIDANCE} from '../lib/helper.mjs';
 import {startResponsesBridge} from '../lib/bridge.mjs';
 
 // Prefer IPv4 when both families are advertised; IPv6-only DNS still works.
@@ -59,6 +59,7 @@ async function launchCodex(model,args){
   const bridge=await startResponsesBridge({port:0});
   try {
     console.log('Starting Codex through a loopback-only bridge. Hosted web search is disabled for this run. Model requests are billed by AtmoRouter.');
+    console.error(SETUP_GUIDANCE);
     const configuration=['-c','model_provider="atmorouter"','-c','model='+JSON.stringify(model),'-c',`model_providers.atmorouter={name="AtmoRouter",base_url="${bridge.url}",env_key="ATMOROUTER_API_KEY",wire_api="responses",requires_openai_auth=false,supports_websockets=false}`,'-c','web_search="disabled"'];
     const code=await new Promise((resolve,reject)=>{
       const child=spawn(executable.file,[...executable.args,...configuration,...args],{stdio:'inherit',env:process.env});
@@ -84,6 +85,7 @@ async function main(){
     if(command==='bridge'){
       if(!/^\d+$/.test(values.port)||Number(values.port)<1||Number(values.port)>65535)throw Error('Bridge port must be an integer from 1 to 65535.');
       const bridge=await startResponsesBridge({port:Number(values.port)});
+      console.error(SETUP_GUIDANCE);
       console.log('Local Responses bridge: '+bridge.url+'\nStateless text/tools only; normal AtmoRouter charges apply. Press Ctrl+C to stop.');
       console.log('In your Codex configuration, set model_provider = "atmorouter" and your chosen model and web_search = "disabled" before provider tables. Then add:\n\n[model_providers.atmorouter]\nname = "AtmoRouter local bridge"\nbase_url = "'+bridge.url+'"\nenv_key = "ATMOROUTER_API_KEY"\nwire_api = "responses"\nrequires_openai_auth = false\nsupports_websockets = false\n\nSet ATMOROUTER_API_KEY privately in the terminal that starts Codex. Run configure --target codex --model YOUR_MODEL_ID for full instructions.');
       await new Promise(resolve=>{process.once('SIGINT',resolve);process.once('SIGTERM',resolve);});await bridge.close();return;
@@ -118,12 +120,12 @@ async function main(){
     if(integration.mode==='unavailable')throw Error(guidedConfiguration(target,model,{shell:values.shell}));
     if(['guided','bridge'].includes(integration.mode)){
       if(values.write)throw Error('This integration uses guided setup. No configuration files were changed.');
-      console.log(guidedConfiguration(target,model,{shell:values.shell}));return;
+      console.log(guidedConfiguration(target,model,{shell:values.shell}));console.error(SETUP_GUIDANCE);return;
     }
     if(!values.offline&&!rl){if(!(await models()).some(m=>m.id===model))throw Error('Model is not in the live text catalog. Use models to choose one.');}
     if(['openai','anthropic'].includes(target)){
       if(values.write)throw Error('Environment snippets are preview-only. Copy them into your shell.');
-      console.log(environment(target,model,values.shell));return;
+      console.log(environment(target,model,values.shell));console.error(SETUP_GUIDANCE);return;
     }
     const plan=await planConfiguration(target,model,{directory:values['config-dir']});
     // Print only the intended patch. Existing settings may contain secrets.
@@ -136,8 +138,9 @@ async function main(){
       if(values.yes)apply=true;
       else {if(!process.stdin.isTTY)throw Error('Non-interactive writes require --write --yes. Nothing changed.');rl=createInterface({input:process.stdin,output:process.stdout});apply=/^y(es)?$/i.test((await rl.question('Apply these changes? [y/N] ')).trim());}
     }
-    if(!apply){console.log('Preview only. No files changed.');return;}
+    if(!apply){console.log('Preview only. No files changed.');console.error(SETUP_GUIDANCE);return;}
     const written=await writeConfiguration(plan);console.log('Saved: '+written.file);if(written.backup)console.log('Backup: '+written.backup);
+    console.error(SETUP_GUIDANCE);
   } finally {rl?.close();}
 }
 main().catch(error=>{

package/lib/helper.mjs

@@ -6,6 +6,13 @@ import {planYamlConfiguration,assertSafeConfigurationPath} from './integrations.
 export {INTEGRATIONS,guidedConfiguration} from './integrations.mjs';
 
 export const ORIGIN = 'https://atmorouter.dev';
+export const SETUP_GUIDANCE = `Before using your client: review Budgets at https://atmorouter.dev/dashboard/budgets.
+Market prices and tiers vary. A "From" price is a snapshot of the cheapest advertised offer, not a guaranteed execution price.
+Select the actual API key used by this client and an all-model percentage rule for broad coverage. Illustrative examples only: 20% below official rates, or 50% below official rates; choose your own limit after reviewing the rates. Account and key rules both apply; the strictest input and output limits win. A rule for one model does not cover other models. The helper never saves or raises budget rules automatically.
+Routing can wait up to 30 seconds for capacity within your caps. This wait is fixed; generation time is additional. Allow both in your client timeout. The local bridge has a 120-second total timeout by default.
+For 429 or temporary availability failures, honor Retry-After when present; otherwise use bounded exponential backoff with jitter. Do not retry blindly or duplicate an in-flight request. After a timeout or interrupted stream, review the client outcome and usage before deciding to resend. Never raise price caps automatically.
+Capacity refusals can pause the affected model, protocol and effective price ceilings for 15, 30, then up to 60 seconds. Customer-specific limits are isolated by account. One eligible request tests recovery. For an explicit capacity rejection before output, honor Retry-After or error.retry_after_seconds, including errors inside HTTP 200 SSE streams. Wait at least that delay plus a small random jitter; allow at most three automatic retries. Without a delay hint, wait 2, 4, then 8 seconds plus jitter. If output arrived, tools ran, or the outcome is uncertain, review Usage and the client outcome before resending.
+For invalid requests, correct the request; for authentication errors, check the key and account eligibility; for insufficient balance, review Billing. A price_limit_unavailable refusal needs capacity within your caps or a deliberate budget review; adding funds does not fix pricing availability. Client setup and key checks do not prove current availability within your limits.`;
 const isRecord = value => value !== null && typeof value === 'object' && !Array.isArray(value);
 export function modelId(value) {
   if (typeof value!=='string' || value!==value.trim() || !/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,200}$/.test(value)) throw Error('Choose a model ID from the catalog; shell characters and whitespace are not allowed.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atmorouter/helper",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Configure AtmoRouter coding agents, guide IDE setup, and run a local Codex bridge",
   "homepage": "https://atmorouter.dev/docs/helper",
   "keywords": [