@atmorouter/helper 0.2.1 → 0.2.3

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.3 adds post-setup budget, routing-wait, and retry guidance while keeping generated configuration and shell output clean. The commands below pin that version; the versioned website archive is an alternative installation channel.
 
 ```sh
-npx @atmorouter/helper@0.2.1 --help
-npx @atmorouter/helper@0.2.1 targets
-npx @atmorouter/helper@0.2.1 models --search claude
-npx @atmorouter/helper@0.2.1 configure --target opencode --model YOUR_MODEL_ID
-npx @atmorouter/helper@0.2.1 configure --target claude --model YOUR_MODEL_ID --write
+npx @atmorouter/helper@0.2.3 --help
+npx @atmorouter/helper@0.2.3 targets
+npx @atmorouter/helper@0.2.3 models --search claude
+npx @atmorouter/helper@0.2.3 configure --target opencode --model YOUR_MODEL_ID
+npx @atmorouter/helper@0.2.3 configure --target claude --model YOUR_MODEL_ID --write
 ```
 
-The same version is available as `https://atmorouter.dev/downloads/atmorouter-helper-0.2.1.tgz`, with a `.sha256` checksum alongside it. Run it with `npx https://atmorouter.dev/downloads/atmorouter-helper-0.2.1.tgz --help`.
+The same version is available as `https://atmorouter.dev/downloads/atmorouter-helper-0.2.3.tgz`, with a `.sha256` checksum alongside it. Run it with `npx https://atmorouter.dev/downloads/atmorouter-helper-0.2.3.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,16 +36,30 @@ 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.1 check-key
+npx @atmorouter/helper@0.2.3 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. Requests have a 15-second timeout and refuse redirects. No custom upstream origin can receive your 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.
 
 ## Codex local bridge
 
@@ -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.1 configure --target codex --model YOUR_MODEL_ID
+npx @atmorouter/helper@0.2.3 configure --target codex --model YOUR_MODEL_ID
 
 # Starts a temporary local bridge and launches your installed Codex CLI.
-npx @atmorouter/helper@0.2.1 codex --model YOUR_MODEL_ID
+npx @atmorouter/helper@0.2.3 codex --model YOUR_MODEL_ID
 
 # Or run the bridge separately and follow its printed client instructions.
-npx @atmorouter/helper@0.2.1 bridge --port 43187
+npx @atmorouter/helper@0.2.3 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.

package/bin/atmorouter-helper.mjs

@@ -5,9 +5,14 @@ import {readFile} from 'node:fs/promises';
 import fs from 'node:fs';
 import path from 'node:path';
 import {spawn} from 'node:child_process';
-import {models,modelId,checkKey,planConfiguration,writeConfiguration,environment,INTEGRATIONS,guidedConfiguration} from '../lib/helper.mjs';
+import {setDefaultResultOrder} from 'node:dns';
+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.
+// This affects this CLI process only, including the bridge's outbound requests.
+setDefaultResultOrder('ipv4first');
+
 const HELP=`AtmoRouter helper
 Node.js 22+.
 
@@ -54,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});
@@ -79,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;
@@ -113,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.
@@ -131,13 +138,14 @@ 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=>{
   let message=String(error?.message || 'Operation failed.');
-  if(error?.code?.startsWith('ERR_PARSE_ARGS'))message='Unknown or unsupported command options. Do not pass API keys as arguments. Run --help.';
+  if(typeof error?.code==='string'&&error.code.startsWith('ERR_PARSE_ARGS'))message='Unknown or unsupported command options. Do not pass API keys as arguments. Run --help.';
   else if(error instanceof SyntaxError)message='Unexpected catalog JSON. Try again later.';
   else if(error instanceof TypeError || error?.name==='TimeoutError')message='Network operation failed. Check connectivity and retry.';
   if(process.env.ATMOROUTER_API_KEY)message=message.split(process.env.ATMOROUTER_API_KEY).join('[redacted]');

package/lib/helper.mjs

@@ -6,13 +6,19 @@ 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.
+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.');
   return value;
 }
 export async function models(fetcher = fetch) {
-  const response = await fetcher(ORIGIN+'/v1/models', {redirect:'error',signal:AbortSignal.timeout(15000)});
+  const response = await fetcher(ORIGIN+'/v1/models', {redirect:'error',signal:AbortSignal.timeout(30000)});
   if (!response.ok) throw Error('Catalog request failed: HTTP '+response.status);
   const body = await response.json();
   if (!Array.isArray(body.data)) throw Error('Unexpected catalog response.');

package/package.json

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