@atmorouter/helper 0.1.0 → 0.2.0

package/README.md

@@ -1,54 +1,89 @@
 # AtmoRouter helper
 
-Configure Claude Code or OpenCode for AtmoRouter, discover model IDs, and check an API key without running paid inference. Review configuration changes before applying them; existing settings are merged and backed up.
+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. No runtime dependencies. Run the versioned package from the official AtmoRouter website:
+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.
 
 ```sh
-npx https://atmorouter.dev/downloads/atmorouter-helper-0.1.0.tgz --help
-npx https://atmorouter.dev/downloads/atmorouter-helper-0.1.0.tgz models --search claude
-npx https://atmorouter.dev/downloads/atmorouter-helper-0.1.0.tgz configure --target opencode --model YOUR_MODEL_ID
-npx https://atmorouter.dev/downloads/atmorouter-helper-0.1.0.tgz configure --target claude --model YOUR_MODEL_ID --write
+npx @atmorouter/helper@0.2.0 --help
+npx @atmorouter/helper@0.2.0 targets
+npx @atmorouter/helper@0.2.0 models --search claude
+npx @atmorouter/helper@0.2.0 configure --target opencode --model YOUR_MODEL_ID
+npx @atmorouter/helper@0.2.0 configure --target claude --model YOUR_MODEL_ID --write
 ```
 
-With no command, the interactive wizard searches live text models, previews the selected settings, and asks before applying changes. `configure` is preview-only unless `--write` is supplied. Non-interactive writes additionally require `--yes`. Tests use explicit temporary `--config-dir` folders, never the developer's real agent settings.
+The same version is available as `https://atmorouter.dev/downloads/atmorouter-helper-0.2.0.tgz`, with a `.sha256` checksum alongside it. Run it with `npx https://atmorouter.dev/downloads/atmorouter-helper-0.2.0.tgz --help`.
 
-Targets:
+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.
 
-| Target | Output |
-|---|---|
-| `claude` | `~/.claude/settings.json`, changing model/base URL variables and preserving other JSON settings |
-| `opencode` | `$XDG_CONFIG_HOME/opencode/opencode.json` or `~/.config/opencode/opencode.json`, using `@ai-sdk/openai-compatible` |
-| `openai` | OpenAI-compatible environment snippet; no file writes |
-| `anthropic` | Anthropic-compatible environment snippet; no file writes |
+## Connections
 
-Use `--shell powershell` for PowerShell snippets. `--config-dir PATH` explicitly selects a settings folder. `--offline` skips catalog validation, for previews or isolated tests; it does not establish model availability or agent compatibility. Preview output shows only intended changes, not existing file contents.
+| Target | Mode and output |
+|---|---|
+| `claude` | Automatic: `~/.claude/settings.json`, preserving unrelated JSON settings |
+| `opencode` | Automatic: `$XDG_CONFIG_HOME/opencode/opencode.json` or `~/.config/opencode/opencode.json`, using `@ai-sdk/openai-compatible` |
+| `omp` | Automatic: Oh My Pi `~/.omp/agent/models.yml`, with `api: openai-completions` and an environment variable name for `apiKey` |
+| `continue` | Automatic: `~/.continue/config.yaml`; the secret reference requires a separate manual IDE secret setup |
+| `cursor` | Guided UI: API key and OpenAI base URL override where available; custom keys apply to Chat, not Tab completion |
+| `vscode` | Guided UI: Copilot Chat Manage Language Models → Add Models → Custom Endpoint, replacing the deprecated OpenAI Compatible setting |
+| `cline` | Guided UI: select OpenAI Compatible, set the endpoint, key, and model |
+| `roo` | Guided UI: select OpenAI Compatible; the chosen model must support native tool calling |
+| `codex` | Local bridge instructions; explicit `codex` or `bridge` commands start the bridge |
+| `antigravity` | Unsupported native IDE integration; diagnostic instructions only |
+| `openai`, `anthropic` | Protocol-specific shell environment snippets; no file writes |
+
+Guided targets print the steps to perform in your installed client; they do not edit undocumented IDE files. Antigravity does not offer a documented native IDE custom endpoint or authenticated SDK integration path suitable for this helper. It is not advertised as compatible.
+
+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.
 
 ## Credentials
 
-The helper never saves or prints an API key. Set `ATMOROUTER_API_KEY` privately through your shell or secret manager. OpenCode reads `{env:ATMOROUTER_API_KEY}`. For Claude Code, set `ANTHROPIC_AUTH_TOKEN` to the same value before launching Claude. Settings that already embed Claude credentials or custom provider credential headers require a manual merge, so an older secret cannot silently override your new environment.
+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 https://atmorouter.dev/downloads/atmorouter-helper-0.1.0.tgz check-key
+npx @atmorouter/helper@0.2.0 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.
+
+## Codex local bridge
+
+The public gateway implements Chat Completions and Anthropic Messages, not `/v1/responses`. The helper can explicitly start a localhost Responses adapter for Codex and translate a supported subset of requests to Chat Completions:
+
+```sh
+# Prints instructions only; does not start a server or write Codex settings.
+npx @atmorouter/helper@0.2.0 configure --target codex --model YOUR_MODEL_ID
+
+# Starts a temporary local bridge and launches your installed Codex CLI.
+npx @atmorouter/helper@0.2.0 codex --model YOUR_MODEL_ID
+
+# Or run the bridge separately and follow its printed client instructions.
+npx @atmorouter/helper@0.2.0 bridge --port 43187
 ```
 
-`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` is accepted as proof that 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. There is no custom API origin option that could send a credential to a different host.
+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.
+
+The bridge supports stateless text and function-tool exchanges, including streaming. The launcher disables hosted web search for this run because the gateway cannot execute that tool. It rejects unsupported built-in tools and stateful Responses features. Reasoning summaries and encrypted reasoning output are unavailable. Image/audio inputs and complete Responses API parity are not promised. Client and model features can still be incompatible. Calls through the bridge are normal paid inference, billed to your AtmoRouter key. The server starts only when you explicitly run `codex` or `bridge`.
 
 ## Applying and restoring settings
 
-Existing strict JSON settings are merged, not replaced wholesale. JSONC, invalid JSON, non-object roots, and symlink targets are refused. If an `opencode.jsonc` file exists, use a manual merge instead of creating a competing JSON file. Writes recheck that the file still matches its preview, make a timestamped `.atmorouter-backup-*` copy, and publish the new settings through a temporary file in the same directory. Backups and new files request owner-only permissions (0600 on POSIX); Windows access also depends on directory ACLs.
+Existing JSON and YAML settings are merged, not replaced wholesale. Unsupported formats, malformed documents, non-object roots, symlinks, or ambiguous existing configuration require a manual merge. JSONC is refused. If an `opencode.jsonc` file exists, use a manual merge instead of creating a competing JSON file. Writes recheck that the file matches its preview, create a timestamped `.atmorouter-backup-*` copy, and publish through a temporary file in the same directory. Backups and new files request owner-only permissions (0600 on POSIX); Windows access also depends on directory ACLs.
 
-To roll back, stop the agent, compare its current file with the backup, and restore the backup after preserving any intervening edits. For a newly created settings file, remove only the AtmoRouter entries you added; do not delete unrelated settings.
+To roll back, stop the agent, compare its current file with the backup, and restore the backup after preserving intervening edits. For newly created files, remove only the AtmoRouter entries you added.
 
-The helper does not install agents, execute models, alter shell profiles, create keys, move money, or manage accounts. It does not configure Codex/Responses. A generated config establishes the API connection format; tools, context handling, and agent features remain model/client dependent.
+The helper does not install agents, alter shell profiles, create keys, move money, or manage accounts. Tools, context handling, and agent features depend on the selected model and client.
 
 ## Checks
 
 ```sh
 cd packages/helper
+npm ci --registry=https://registry.npmjs.org/ --ignore-scripts
 node --test
 npm pack --dry-run
+npm run test:package
 ```
 
-Source references: [Claude Code gateways](https://code.claude.com/docs/en/llm-gateway), [OpenCode custom providers](https://opencode.ai/docs/providers/). The documented AtmoRouter endpoints are verified against the gateway implementation.
+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/).

package/bin/atmorouter-helper.mjs

@@ -2,37 +2,91 @@
 import {parseArgs} from 'node:util';
 import {createInterface} from 'node:readline/promises';
 import {readFile} from 'node:fs/promises';
-import {models,checkKey,planConfiguration,writeConfiguration,environment} from '../lib/helper.mjs';
+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 {startResponsesBridge} from '../lib/bridge.mjs';
 
 const HELP=`AtmoRouter helper
-Node.js 22+; no runtime dependencies.
+Node.js 22+.
 
 Commands:
   models [--search TEXT]               List live text models; no key required
   check-key                           Check ATMOROUTER_API_KEY without inference
   configure --target TARGET --model ID Preview settings (default: no write)
+  targets                             List automatic, guided, and bridge integrations
+  bridge [--port 43187]                Run a loopback-only Responses bridge
+  codex --model ID [-- CODEX_ARGS]     Start installed Codex through the local bridge
   No command                          Interactive configuration wizard
 
-Targets: claude, opencode, openai, anthropic
+Run targets for current compatibility and limitations.
 Options:
-  --write                             Apply JSON configuration after confirmation
+  --write                             Apply configuration after confirmation
   --yes                               Confirm writes for non-interactive use
   --config-dir PATH                   Explicit configuration folder
   --offline                           Skip catalog lookup; review model ID yourself
   --shell posix|powershell             Environment snippet format
   --help                              Show this help
   --version                           Show the installed version
+  --port NUMBER                       Local bridge port (default: 43187)
 
 Keys are read only from ATMOROUTER_API_KEY for check-key. They are never printed
 or stored in generated files. Set ANTHROPIC_AUTH_TOKEN separately for Claude.
-No Responses/Codex, payment, key-creation, or account-management actions.`;
+Codex uses a local stateless text/tool Responses bridge, not a native gateway
+Responses endpoint. Normal model charges apply. No payment or account actions.`;
+
+function codexExecutable(){
+  const extensions=process.platform==='win32'?['.exe','.cmd','.bat','']:[''];
+  for(const directory of (process.env.PATH || '').split(path.delimiter))for(const extension of extensions){
+    const file=path.join(directory,'codex'+extension);if(!fs.existsSync(file))continue;
+    if(process.platform==='win32'&&['.cmd','.bat'].includes(extension)){
+      for(const wrapper of [path.join(directory,'node_modules/@openai/codex/bin/codex.js'),path.resolve(directory,'../@openai/codex/bin/codex.js')])if(fs.existsSync(wrapper))return {file:process.execPath,args:[wrapper]};
+      continue;
+    }
+    return {file,args:[]};
+  }
+  throw Error('Install the official Codex CLI and add it to PATH first, or use bridge with a manually configured client.');
+}
+async function launchCodex(model,args){
+  if(!/^ar-[a-f0-9]{48}$/.test(process.env.ATMOROUTER_API_KEY || ''))throw Error('Set ATMOROUTER_API_KEY privately before starting Codex.');
+  const executable=codexExecutable();
+  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.');
+    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});
+      let receivedSignal;
+      const interrupt=()=>{receivedSignal='SIGINT';child.kill('SIGINT');};
+      const terminate=()=>{receivedSignal='SIGTERM';child.kill('SIGTERM');};
+      const cleanup=()=>{process.off('SIGINT',interrupt);process.off('SIGTERM',terminate);};
+      process.on('SIGINT',interrupt);process.on('SIGTERM',terminate);
+      child.once('error',error=>{cleanup();reject(error);});
+      child.once('exit',(value,signal)=>{cleanup();resolve(value ?? ((signal||receivedSignal)==='SIGINT'?130:(signal||receivedSignal)==='SIGTERM'?143:1));});
+    });
+    process.exitCode=code;
+  } finally {await bridge.close();}
+}
 async function main(){
-  const {values,positionals}=parseArgs({allowPositionals:true,options:{target:{type:'string'},model:{type:'string'},search:{type:'string'},'config-dir':{type:'string'},shell:{type:'string',default:'posix'},write:{type:'boolean'},yes:{type:'boolean'},offline:{type:'boolean'},help:{type:'boolean'},version:{type:'boolean'}}});
+  const {values,positionals}=parseArgs({allowPositionals:true,options:{target:{type:'string'},model:{type:'string'},search:{type:'string'},'config-dir':{type:'string'},shell:{type:'string',default:'posix'},port:{type:'string',default:'43187'},write:{type:'boolean'},yes:{type:'boolean'},offline:{type:'boolean'},help:{type:'boolean'},version:{type:'boolean'}}});
   if(values.version){console.log(JSON.parse(await readFile(new URL('../package.json',import.meta.url),'utf8')).version);return;}
   if(values.help){console.log(HELP);return;}
   let command=positionals[0],target=values.target,model=values.model,rl;
   try {
-    if(positionals.length>1)throw Error('Unexpected command arguments. Use --help.');
+    if(positionals.length>1&&command!=='codex')throw Error('Unexpected command arguments. Use --help.');
+    if(command==='targets'){console.log(INTEGRATIONS.map(t=>`${t.id} [${t.mode}] — ${t.name}: ${t.description}`).join('\n'));return;}
+    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.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;
+    }
+    if(command==='codex'){
+      modelId(model);if(!values.offline&&!(await models()).some(m=>m.id===model))throw Error('Choose an enabled text model from the catalog.');
+      await launchCodex(model,positionals.slice(1));return;
+    }
     if(command==='check-key'){console.log(await checkKey(process.env.ATMOROUTER_API_KEY));return;}
     if(command==='models'){
       const rows=(await models()).filter(m=>m.id.toLowerCase().includes((values.search || '').toLowerCase()));
@@ -41,8 +95,9 @@ async function main(){
     if(!command){
       if(!process.stdin.isTTY)throw Error('Use configure --target TARGET --model ID for non-interactive use.');
       rl=createInterface({input:process.stdin,output:process.stdout});
-      console.log('Preview a connection for Claude Code, OpenCode, or an SDK. No secrets will be saved.');
-      target=(await rl.question('Target (claude/opencode/openai/anthropic): ')).trim();
+      console.log('Choose an integration. No API key will be printed or saved.');
+      console.log(INTEGRATIONS.map(t=>`${t.id}: ${t.name} [${t.mode}]`).join('\n'));
+      target=(await rl.question('Target: ')).trim();
       const query=(await rl.question('Search model IDs: ')).trim().toLowerCase();
       const rows=(await models()).filter(m=>m.id.toLowerCase().includes(query)).slice(0,25);
       if(!rows.length)throw Error('No matching models. Try a different search.');
@@ -52,6 +107,14 @@ async function main(){
       model=rows[selected-1].id;command='configure';
     } else if(command!=='configure')throw Error('Unknown command. Use --help.');
     if(!target||!model)throw Error('configure requires --target and --model.');
+    modelId(model);
+    const integration=INTEGRATIONS.find(t=>t.id===target);
+    if(!integration)throw Error('Unknown target. Run targets to list integrations.');
+    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;
+    }
     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.');
@@ -60,7 +123,8 @@ async function main(){
     const plan=await planConfiguration(target,model,{directory:values['config-dir']});
     // Print only the intended patch. Existing settings may contain secrets.
     console.log('Configuration: '+plan.file+'\nChanges:\n'+JSON.stringify(plan.patch,null,2));
-    console.log(target==='claude'?'Before starting Claude, set ANTHROPIC_AUTH_TOKEN to your AtmoRouter key.':'Before starting OpenCode, set ATMOROUTER_API_KEY to your AtmoRouter key.');
+    console.log(target==='claude'?'Before starting Claude, set ANTHROPIC_AUTH_TOKEN to your AtmoRouter key.':'Before starting the agent, configure ATMOROUTER_API_KEY privately.');
+    if(plan.instructions)console.log(plan.instructions);
     let apply=false;
     if(rl)apply=/^y(es)?$/i.test((await rl.question('Apply these changes? [y/N] ')).trim());
     else if(values.write){

package/lib/bridge.mjs

@@ -0,0 +1,165 @@
+import http from 'node:http';
+import {randomUUID} from 'node:crypto';
+
+const UPSTREAM = 'https://atmorouter.dev/v1/chat/completions';
+const LIMIT = 32 * 1024 * 1024;
+class BridgeError extends Error { constructor(status, code) { super(code); this.status=status; this.code=code; } }
+const invalid = () => { throw new BridgeError(400,'unsupported_request'); };
+const object = x => x !== null && typeof x === 'object' && !Array.isArray(x);
+function keys(value, allowed) { if(!object(value) || Object.keys(value).some(k=>!allowed.includes(k))) invalid(); }
+function textContent(content) {
+  if(typeof content==='string') return content;
+  if(!Array.isArray(content)) invalid();
+  return content.map(p=>{keys(p,['type','text','annotations']);if(!['input_text','output_text','text'].includes(p.type)||typeof p.text!=='string')invalid();return p.text;}).join('');
+}
+function translate(body) {
+  keys(body,['model','input','instructions','stream','store','tools','tool_choice','parallel_tool_calls','max_output_tokens','output_tokens','temperature','top_p','text','reasoning','metadata','client_metadata','include','truncation','service_tier','prompt_cache_key','safety_identifier']);
+  if(typeof body.model!=='string'||!body.model||body.store===true|| (body.store!==undefined&&body.store!==false) || (body.stream!==undefined&&typeof body.stream!=='boolean'))invalid();
+  if(body.include!==undefined && (!Array.isArray(body.include)||body.include.some(x=>x!=='reasoning.encrypted_content')))invalid();
+  if(body.truncation!==undefined && body.truncation!=='disabled')invalid();
+  const messages=[], toolMap=new Map();toolMap.namespaces=new Map();
+  const identities=new Map(),namespacedTools=new WeakSet();
+  const flatName=(namespace,name)=>{if(namespace!==undefined&&(typeof namespace!=='string'||!/^[-a-zA-Z0-9_]+$/.test(namespace)))invalid();const flat=namespace?`${namespace}__${name}`:name;if(typeof name!=='string'||!name||!/^[-a-zA-Z0-9_]{1,64}$/.test(flat))invalid();const identity=JSON.stringify([namespace??null,name]);if(identities.has(flat)&&identities.get(flat)!==identity)invalid();identities.set(flat,identity);if(namespace!==undefined)toolMap.namespaces.set(flat,{name,namespace});return flat;};
+  if(body.instructions!==undefined){if(typeof body.instructions!=='string')invalid();messages.push({role:'system',content:body.instructions});}
+  const input=typeof body.input==='string'?[{role:'user',content:body.input}]:body.input;
+  if(!Array.isArray(input))invalid();
+  for(const item of input){
+    if(!object(item))invalid();
+    if(item.type==='function_call'||item.type==='custom_tool_call'){
+      keys(item,['type','id','call_id','name','namespace','arguments','input','status']);
+      if(item.type==='custom_tool_call'&&typeof item.input!=='string')invalid();
+      const args=item.type==='custom_tool_call'?JSON.stringify({input:item.input}):item.arguments;
+      if(typeof item.call_id!=='string'||typeof item.name!=='string'||typeof args!=='string')invalid();
+      const call={id:item.call_id,type:'function',function:{name:flatName(item.namespace,item.name),arguments:args}};
+      const prior=messages.at(-1);
+      if(prior?.role==='assistant'){prior.tool_calls??=[];prior.tool_calls.push(call);}else messages.push({role:'assistant',content:null,tool_calls:[call]});
+    } else if(item.type==='function_call_output'||item.type==='custom_tool_call_output'){
+      keys(item,['type','id','call_id','output','status']);
+      if(typeof item.call_id!=='string')invalid();
+      messages.push({role:'tool',tool_call_id:item.call_id,content:textContent(item.output)});
+    } else {
+      keys(item,['type','id','role','content','status']);
+      if(item.type!==undefined&&item.type!=='message')invalid();
+      if(!['system','developer','user','assistant'].includes(item.role))invalid();
+      messages.push({role:item.role==='developer'?'system':item.role,content:textContent(item.content)});
+    }
+  }
+  const out={model:body.model,messages,stream:body.stream===true};
+  if(body.tools!==undefined){
+    if(!Array.isArray(body.tools))invalid();
+    const tools=[];for(const tool of body.tools){if(tool?.type==='namespace'){keys(tool,['type','name','description','tools']);if(typeof tool.name!=='string'||!tool.name||!Array.isArray(tool.tools)||tool.description!==undefined&&typeof tool.description!=='string')invalid();for(const child of tool.tools){if(!object(child)||!['function','custom'].includes(child.type)||child.description!==undefined&&typeof child.description!=='string')invalid();const name=flatName(tool.name,child.name);const normalized={...child,name,...(tool.description?{description:`${tool.description}\n\n${child.description??''}`}:{})};namespacedTools.add(normalized);tools.push(normalized);}}else tools.push(tool);}
+    out.tools=tools.map(tool=>{
+      if(!object(tool))invalid();
+      if(!namespacedTools.has(tool))flatName(undefined,tool.name);if(toolMap.has(tool.name))invalid();
+      if(tool.type==='function'){
+        keys(tool,['type','name','description','parameters','strict']);
+        if(typeof tool.name!=='string'||(tool.parameters!==undefined&&!object(tool.parameters)))invalid();
+        toolMap.set(tool.name,'function');
+        return {type:'function',function:{name:tool.name,...(tool.description!==undefined?{description:tool.description}:{}),parameters:tool.parameters??{type:'object',properties:{}},...(tool.strict!==undefined?{strict:tool.strict}:{})}};
+      }
+      if(tool.type==='custom'){
+        keys(tool,['type','name','description','format']);
+        if(typeof tool.name!=='string')invalid();
+        // Grammar-constrained custom tools cannot be preserved by Chat Completions.
+        if(tool.format!==undefined&&tool.format.type!=='text')invalid();
+        toolMap.set(tool.name,'custom');
+        return {type:'function',function:{name:tool.name,description:tool.description,parameters:{type:'object',properties:{input:{type:'string'}},required:['input'],additionalProperties:false}}};
+      }
+      invalid();
+    });
+  }
+  if(body.tool_choice!==undefined){
+    if(['auto','none','required'].includes(body.tool_choice))out.tool_choice=body.tool_choice;
+    else {keys(body.tool_choice,['type','name','namespace']);const name=flatName(body.tool_choice.namespace,body.tool_choice.name);if(!['function','custom'].includes(body.tool_choice.type)||!toolMap.has(name))invalid();out.tool_choice={type:'function',function:{name}};}
+  }
+  for(const k of ['temperature','top_p','parallel_tool_calls','service_tier'])if(body[k]!==undefined)out[k]=body[k];
+  const max=body.max_output_tokens??body.output_tokens;
+  if(max!==undefined){if(!Number.isSafeInteger(max)||max<1)invalid();out.max_tokens=max;}
+  if(body.reasoning!==undefined){keys(body.reasoning,['effort','summary']);if(body.reasoning.summary!==undefined&&!['auto','concise','detailed'].includes(body.reasoning.summary))invalid();if(body.reasoning.effort!==undefined){if(!['none','minimal','low','medium','high','xhigh'].includes(body.reasoning.effort))invalid();out.reasoning_effort=body.reasoning.effort;}}
+  if(body.text!==undefined){keys(body.text,['format','verbosity']);if(body.text.verbosity!==undefined)invalid();if(body.text.format){const f=body.text.format;if(f.type==='text'){keys(f,['type']);}else if(f.type==='json_object'){keys(f,['type']);out.response_format=f;}else if(f.type==='json_schema'){keys(f,['type','name','description','schema','strict']);out.response_format={type:'json_schema',json_schema:{name:f.name,schema:f.schema,...(f.description!==undefined?{description:f.description}:{}),...(f.strict!==undefined?{strict:f.strict}:{})}};}else invalid();}}
+  if(out.stream)out.stream_options={include_usage:true};
+  return {request:out,toolMap};
+}
+function usage(u){return {input_tokens:u?.prompt_tokens??0,input_tokens_details:{cached_tokens:u?.prompt_tokens_details?.cached_tokens??0},output_tokens:u?.completion_tokens??0,output_tokens_details:{reasoning_tokens:u?.completion_tokens_details?.reasoning_tokens??0},total_tokens:u?.total_tokens??((u?.prompt_tokens??0)+(u?.completion_tokens??0))};}
+function responseBase(body){return {id:'resp_'+randomUUID().replaceAll('-',''),object:'response',created_at:Math.floor(Date.now()/1000),status:'in_progress',error:null,incomplete_details:null,instructions:body.instructions??null,model:body.model,output:[],parallel_tool_calls:body.parallel_tool_calls??true,store:false,tool_choice:body.tool_choice??'auto',tools:body.tools??[],usage:null};}
+function toolItem(name,args,callId,map,id){
+  if(map.get(name)==='custom'){
+    let input;try{input=JSON.parse(args).input;}catch{throw new BridgeError(502,'invalid_upstream_response');}
+    if(typeof input!=='string')throw new BridgeError(502,'invalid_upstream_response');
+    return {type:'custom_tool_call',id,call_id:callId,...(map.namespaces.get(name)??{name}),input,status:'completed'};
+  }
+  return {type:'function_call',id,call_id:callId,...(map.namespaces.get(name)??{name}),arguments:args,status:'completed'};
+}
+async function boundedJSON(upstream,limit){const reader=upstream.body?.getReader();if(!reader)throw new BridgeError(502,'invalid_upstream_response');let size=0;const chunks=[];while(true){const {value,done}=await reader.read();if(done)break;size+=value.byteLength;if(size>limit){await reader.cancel();throw new BridgeError(502,'upstream_output_limit');}chunks.push(Buffer.from(value));}try{return JSON.parse(Buffer.concat(chunks).toString('utf8'));}catch{throw new BridgeError(502,'invalid_upstream_response');}}
+async function* frames(body,limit){
+  const reader=body?.getReader();if(!reader)throw new BridgeError(502,'invalid_upstream_response');
+  const decoder=new TextDecoder('utf-8',{fatal:true});let buffer='',total=0,data=[];
+  try {while(true){const {value,done}=await reader.read();total+=value?.byteLength??0;if(total>limit)throw new BridgeError(502,'upstream_output_limit');buffer+=done?decoder.decode():decoder.decode(value,{stream:true});
+    while(true){const match=/\r\n|\r|\n/.exec(buffer);if(!match)break;if(!done&&match[0]==='\r'&&match.index===buffer.length-1)break;const line=buffer.slice(0,match.index);buffer=buffer.slice(match.index+match[0].length);if(line===''){if(data.length){yield data.join('\n');data=[];}}else if(line.startsWith('data:'))data.push(line.slice(5).replace(/^ /,''));}
+    if(buffer.length>1024*1024||data.join('\n').length>1024*1024)throw new BridgeError(502,'upstream_frame_limit');
+    if(done){if(buffer||data.length)throw new BridgeError(502,'truncated_upstream_stream');break;}
+  }}finally{await reader.cancel().catch(()=>{});reader.releaseLock();}
+}
+async function streamResponse(upstream,res,base,map,limit){
+  let seq=0;const output=[],tools=new Map();let message,finished=false,done=false,finishReason,tokenUsage;
+  async function emit(type,fields={}){if(res.destroyed)throw new BridgeError(499,'request_cancelled');const event={type,sequence_number:seq++,...fields};if(!res.write(`event: ${type}\ndata: ${JSON.stringify(event)}\n\n`))await new Promise((resolve,reject)=>{const cleanup=()=>{res.off('drain',drain);res.off('close',close);res.off('error',close);};const drain=()=>{cleanup();resolve();};const close=()=>{cleanup();reject(new BridgeError(499,'request_cancelled'));};res.once('drain',drain);res.once('close',close);res.once('error',close);});}
+  await emit('response.created',{response:{...base}});await emit('response.in_progress',{response:{...base}});
+  const add=async item=>{const index=output.length;output.push(item);await emit('response.output_item.added',{output_index:index,item:{...item}});return index;};
+  try {
+    for await(const frame of frames(upstream.body,limit)){
+      if(frame==='[DONE]'){done=true;break;}
+      let chunk;try{chunk=JSON.parse(frame);}catch{throw new BridgeError(502,'invalid_upstream_stream');}
+      if(chunk.error)throw new BridgeError(502,'upstream_stream_error');
+      if(chunk.usage)tokenUsage=chunk.usage;
+      if(!Array.isArray(chunk.choices))throw new BridgeError(502,'invalid_upstream_stream');
+      for(const choice of chunk.choices){if(choice.index!==undefined&&choice.index!==0)throw new BridgeError(502,'invalid_upstream_stream');const d=choice.delta??{};
+        if(d.refusal||d.audio)throw new BridgeError(502,'unsupported_upstream_output');
+        if(d.content){if(finished||typeof d.content!=='string')throw new BridgeError(502,'invalid_upstream_stream');if(!message){const item={id:'msg_'+randomUUID(),type:'message',status:'in_progress',role:'assistant',content:[]};const index=await add(item);const part={type:'output_text',text:'',annotations:[]};item.content.push(part);message={item,index,part};await emit('response.content_part.added',{item_id:item.id,output_index:index,content_index:0,part:{...part}});}message.part.text+=d.content;await emit('response.output_text.delta',{item_id:message.item.id,output_index:message.index,content_index:0,delta:d.content});}
+        for(const t of d.tool_calls??[]){if(finished||!Number.isSafeInteger(t.index)||t.index<0||t.index>1024||t.type&&t.type!=='function'||t.id!==undefined&&typeof t.id!=='string'||t.function?.name!==undefined&&typeof t.function.name!=='string'||t.function?.arguments!==undefined&&typeof t.function.arguments!=='string')throw new BridgeError(502,'invalid_upstream_stream');let entry=tools.get(t.index);if(!entry){entry={id:'fc_'+randomUUID(),call_id:t.id??'',name:'',arguments:'',emitted:0,index:null};tools.set(t.index,entry);}if(t.id){if(entry.call_id&&entry.call_id!==t.id)throw new BridgeError(502,'invalid_upstream_stream');entry.call_id=t.id;}if(t.function?.name){if(entry.index!==null)throw new BridgeError(502,'invalid_upstream_stream');entry.name+=t.function.name;}if(t.function?.arguments)entry.arguments+=t.function.arguments;
+          if(entry.index===null&&entry.name&&entry.call_id&&entry.arguments.length){if(!map.has(entry.name))throw new BridgeError(502,'unknown_upstream_tool');const custom=map.get(entry.name)==='custom';entry.index=await add({id:entry.id,type:custom?'custom_tool_call':'function_call',status:'in_progress',call_id:entry.call_id,...(map.namespaces.get(entry.name)??{name:entry.name}),...(custom?{input:''}:{arguments:''})});}
+          if(entry.index!==null&&map.get(entry.name)!=='custom'&&entry.arguments.length>entry.emitted){await emit('response.function_call_arguments.delta',{item_id:entry.id,output_index:entry.index,delta:entry.arguments.slice(entry.emitted)});entry.emitted=entry.arguments.length;}
+        }
+        if(choice.finish_reason!==null&&choice.finish_reason!==undefined){if(finished)throw new BridgeError(502,'invalid_upstream_stream');finished=true;finishReason=choice.finish_reason;}
+      }
+    }
+    if(!finished||!done)throw new BridgeError(502,'truncated_upstream_stream');
+    if(!['stop','tool_calls','length'].includes(finishReason))throw new BridgeError(502,'unsupported_upstream_output');
+    if(finishReason==='length'&&tools.size)throw new BridgeError(502,'truncated_upstream_tool_call');
+    if(message){message.item.status='completed';await emit('response.output_text.done',{item_id:message.item.id,output_index:message.index,content_index:0,text:message.part.text});await emit('response.content_part.done',{item_id:message.item.id,output_index:message.index,content_index:0,part:message.part});}
+    for(const entry of tools.values()){if(entry.index===null){if(!entry.call_id||!map.has(entry.name))throw new BridgeError(502,'invalid_upstream_stream');const custom=map.get(entry.name)==='custom';entry.index=await add({id:entry.id,type:custom?'custom_tool_call':'function_call',status:'in_progress',call_id:entry.call_id,...(map.namespaces.get(entry.name)??{name:entry.name}),...(custom?{input:''}:{arguments:''})});}const item=toolItem(entry.name,entry.arguments,entry.call_id,map,entry.id);output[entry.index]=item;if(item.type==='custom_tool_call'){await emit('response.custom_tool_call_input.delta',{item_id:item.id,output_index:entry.index,delta:item.input});await emit('response.custom_tool_call_input.done',{item_id:item.id,output_index:entry.index,input:item.input});}else await emit('response.function_call_arguments.done',{item_id:item.id,output_index:entry.index,arguments:item.arguments});}
+    for(let i=0;i<output.length;i++)await emit('response.output_item.done',{output_index:i,item:output[i]});
+    const response={...base,status:finishReason==='length'?'incomplete':'completed',incomplete_details:finishReason==='length'?{reason:'max_output_tokens'}:null,output,usage:usage(tokenUsage)};await emit(finishReason==='length'?'response.incomplete':'response.completed',{response});
+  }catch(error){if(!res.destroyed)await emit('response.failed',{response:{...base,status:'failed',error:{code:error instanceof BridgeError?error.code:'upstream_stream_error',message:'The upstream response could not be completed.'},output:[]}});}
+  res.end();
+}
+function forwardHeaders(upstream,res){for(const [name,value] of upstream.headers){if((['x-request-id','request-id','retry-after'].includes(name)||/^x-(?:atmorouter-)?(?:cost|usage|ratelimit)[a-z0-9-]*$/.test(name))&&/^[\x20-\x7e]{1,256}$/.test(value))res.setHeader(name,value);}}
+
+/** Starts a stateless Responses adapter bound exclusively to IPv4 loopback. */
+export async function startResponsesBridge({port=0,fetcher=fetch,timeoutMs=120000,maxBodyBytes=LIMIT,maxOutputBytes=LIMIT}={}){
+  const controllers=new Set();let actualPort;
+  const server=http.createServer(async(req,res)=>{
+    const controller=new AbortController();controllers.add(controller);const abort=()=>controller.abort();req.on('aborted',abort);res.on('close',()=>{if(!res.writableEnded)abort();});const timer=setTimeout(abort,timeoutMs);timer.unref();
+    try{
+      if(req.headers.origin!==undefined)throw new BridgeError(403,'browser_requests_forbidden');
+      if(req.headers.host!==`127.0.0.1:${actualPort}`)throw new BridgeError(403,'invalid_host');
+      if(req.url!=='/v1/responses')throw new BridgeError(404,'not_found');
+      if(req.method!=='POST')throw new BridgeError(405,'method_not_allowed');
+      if(!/^Bearer ar-[a-fA-F0-9]{48}$/.test(req.headers.authorization??''))throw new BridgeError(401,'invalid_api_key');
+      if(!/^application\/json(?:\s*;|$)/i.test(req.headers['content-type']??''))throw new BridgeError(415,'json_required');
+      if(Number(req.headers['content-length'])>maxBodyBytes)throw new BridgeError(413,'request_too_large');
+      const chunks=[];let size=0;for await(const chunk of req){size+=chunk.length;if(size>maxBodyBytes)throw new BridgeError(413,'request_too_large');chunks.push(chunk);}
+      let body;try{body=JSON.parse(Buffer.concat(chunks).toString('utf8'));}catch{throw new BridgeError(400,'invalid_json');}
+      const {request,toolMap}=translate(body);
+      const upstream=await fetcher(UPSTREAM,{method:'POST',redirect:'error',headers:{Authorization:req.headers.authorization,'Content-Type':'application/json',Accept:request.stream?'text/event-stream':'application/json'},body:JSON.stringify(request),signal:controller.signal});
+      forwardHeaders(upstream,res);
+      if(!upstream.ok){await upstream.body?.cancel();throw new BridgeError(upstream.status>=400&&upstream.status<=599?upstream.status:502,'upstream_request_failed');}
+      const base=responseBase(body);
+      if(request.stream){if(!upstream.headers.get('content-type')?.includes('text/event-stream'))throw new BridgeError(502,'invalid_upstream_response');res.writeHead(200,{'Content-Type':'text/event-stream','Cache-Control':'no-store','Connection':'keep-alive','X-Accel-Buffering':'no'});await streamResponse(upstream,res,base,toolMap,maxOutputBytes);}
+      else {const data=await boundedJSON(upstream,maxOutputBytes),choice=data.choices?.[0];if(data.error||!choice||!['stop','tool_calls','length'].includes(choice.finish_reason))throw new BridgeError(502,'invalid_upstream_response');const m=choice.message,output=[];if(choice.finish_reason==='length'&&m?.tool_calls?.length)throw new BridgeError(502,'truncated_upstream_tool_call');if(!object(m)||m.refusal)throw new BridgeError(502,'invalid_upstream_response');if(m.content!==null&&m.content!==undefined){if(typeof m.content!=='string')throw new BridgeError(502,'unsupported_upstream_output');output.push({id:'msg_'+randomUUID(),type:'message',status:'completed',role:'assistant',content:[{type:'output_text',text:m.content,annotations:[]}]});}for(const t of m.tool_calls??[]){if(t.type!=='function'||!toolMap.has(t.function?.name)||typeof t.function.arguments!=='string'||typeof t.id!=='string')throw new BridgeError(502,'invalid_upstream_response');output.push(toolItem(t.function.name,t.function.arguments,t.id,toolMap,'fc_'+randomUUID()));}res.writeHead(200,{'Content-Type':'application/json','Cache-Control':'no-store'});res.end(JSON.stringify({...base,status:choice.finish_reason==='length'?'incomplete':'completed',incomplete_details:choice.finish_reason==='length'?{reason:'max_output_tokens'}:null,output,usage:usage(data.usage)}));}
+    }catch(error){if(!res.headersSent&&!res.destroyed){const status=error instanceof BridgeError?error.status:controller.signal.aborted?504:502;res.writeHead(status,{'Content-Type':'application/json','Cache-Control':'no-store'});res.end(JSON.stringify({error:{type:'bridge_error',code:error instanceof BridgeError?error.code:controller.signal.aborted?'upstream_timeout':'upstream_unavailable',message:error instanceof BridgeError&&error.code==='unsupported_request'?'Unsupported Responses feature. Use stateless text/function tools; hosted tools, grammar tools, images and stored sessions are unsupported. See https://atmorouter.dev/docs/helper.':'The local adapter could not complete this request.'}}));}else if(!res.destroyed)res.end();}
+    finally{clearTimeout(timer);controllers.delete(controller);}
+  });
+  server.requestTimeout=timeoutMs;server.headersTimeout=Math.min(timeoutMs,60000);server.maxHeadersCount=100;
+  await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(port,'127.0.0.1',resolve);});actualPort=server.address().port;
+  return {url:`http://127.0.0.1:${actualPort}/v1`,close:async()=>{for(const controller of controllers)controller.abort();server.closeAllConnections();await new Promise((resolve,reject)=>server.close(error=>error?reject(error):resolve()));}};
+}

package/lib/helper.mjs

@@ -2,6 +2,8 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 import {randomUUID} from 'node:crypto';
+import {planYamlConfiguration,assertSafeConfigurationPath} from './integrations.mjs';
+export {INTEGRATIONS,guidedConfiguration} from './integrations.mjs';
 
 export const ORIGIN = 'https://atmorouter.dev';
 const isRecord = value => value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -36,7 +38,8 @@ export function environment(target, model, shell='posix') {
 }
 export async function planConfiguration(target, model, {directory,home=os.homedir(),env=process.env}={}) {
   modelId(model);
-  if (!['claude','opencode'].includes(target)) throw Error('Configuration target must be claude or opencode. Codex/Responses is not supported.');
+  if (['omp','continue'].includes(target)) return planYamlConfiguration(target,model,{directory,home,env});
+  if (!['claude','opencode'].includes(target)) throw Error('Automatic configuration target must be claude, opencode, omp, or continue.');
   const folder=path.resolve(directory || (target==='claude'?path.join(home,'.claude'):path.join(env.XDG_CONFIG_HOME || path.join(home,'.config'),'opencode')));
   const file=path.join(folder,target==='claude'?'settings.json':'opencode.json');
   if (target==='opencode') {
@@ -71,6 +74,7 @@ export async function planConfiguration(target, model, {directory,home=os.homedi
   return {file,patch,original,content:JSON.stringify(merged,null,2)+'\n',target};
 }
 export async function writeConfiguration(plan) {
+  await assertSafeConfigurationPath(plan.file);
   let current=null;
   try { const stat=await fs.lstat(plan.file);if(stat.isSymbolicLink()||!stat.isFile())throw Error('Target is no longer a regular file.');current=await fs.readFile(plan.file,'utf8'); } catch(e) {if(e.code!=='ENOENT')throw e;}
   if(current!==plan.original)throw Error('Configuration changed after preview. Run the helper again.');

package/lib/integrations.mjs

@@ -0,0 +1,133 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import {parseDocument,isMap,isSeq,isAlias,visit} from 'yaml';
+
+const base='https://atmorouter.dev/v1';
+const secret='${{ secrets.ATMOROUTER_API_KEY }}';
+const entries=[
+  ['claude','Claude Code','automatic','Merge Claude settings with environment authentication.','https://code.claude.com/docs/en/llm-gateway'],
+  ['opencode','OpenCode','automatic','Merge an OpenAI-compatible provider.','https://opencode.ai/docs/providers/'],
+  ['omp','Oh My Pi','automatic','Merge models.yml using an environment key reference.','https://github.com/can1357/oh-my-pi/blob/main/docs/models.md'],
+  ['continue','Continue','automatic','Merge config.yaml; configure IDE secrets manually.','https://docs.continue.dev/reference'],
+  ['cursor','Cursor','guided','Configure API keys in the IDE UI where supported.','https://cursor.com/help/models-and-usage/api-keys'],
+  ['vscode','VS Code','guided','Configure the Custom Endpoint language model provider.','https://code.visualstudio.com/docs/agent-customization/language-models'],
+  ['cline','Cline','guided','Configure the OpenAI Compatible provider in settings.','https://docs.cline.bot/provider-config/openai-compatible'],
+  ['roo','Roo Code','guided','Configure OpenAI Compatible with a native tool-capable model.','https://docs.roocode.com/providers/openai-compatible'],
+  ['codex','Codex','bridge','Use the local Responses-to-Chat-Completions bridge.','https://developers.openai.com/codex/config-reference/'],
+  ['antigravity','Antigravity','unavailable','Native IDE custom endpoints are not documented.','https://antigravity.google/docs/'],
+  ['openai','OpenAI environment','environment','Print OpenAI-compatible environment variables.','https://atmorouter.dev/docs'],
+  ['anthropic','Anthropic environment','environment','Print Anthropic-compatible environment variables.','https://atmorouter.dev/docs'],
+];
+export const INTEGRATIONS=Object.freeze(entries.map(([id,name,mode,description,docsUrl])=>Object.freeze({id,name,mode,description,docsUrl})));
+
+function validateModel(model) {
+  if(typeof model!=='string'||model!==model.trim()||!/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,200}$/.test(model))throw Error('Choose a valid model ID from the catalog.');
+}
+export function guidedConfiguration(target,model,{shell='posix'}={}) {
+  validateModel(model);
+  if(!['posix','powershell'].includes(shell))throw Error('Shell must be posix or powershell.');
+  const info=INTEGRATIONS.find(item=>item.id===target);
+  if(!info)throw Error('Unknown integration target.');
+  const details=`Endpoint: ${base}\nModel: ${model}\nAPI key: <your ATMOROUTER_API_KEY> (${target==='codex'?'set securely in the environment':'enter securely in the application UI'})`;
+  let instructions;
+  if(target==='cursor')instructions='Open Cursor Settings > Models > API Keys. Use an OpenAI-compatible custom base URL only if your installed version exposes that option. Enter the endpoint, model, and key in the UI, then verify chat. Custom keys do not promise Tab completion or every agent feature.';
+  else if(target==='vscode')instructions='Open Manage Language Models > Add Models > Custom Endpoint. Open its configuration in chatLanguageModels.json and merge this provider into the existing array. VS Code prompts for the key and stores it securely. Enable toolCalling only after verifying native tool support for this model.\n'+JSON.stringify({name:'AtmoRouter',vendor:'customendpoint',apiType:'chat-completions',apiKey:'${input:atmorouterApiKey}',models:[{id:model,name:model,url:base+'/chat/completions'}]},null,2);
+  else if(target==='cline'||target==='roo')instructions=`Open ${info.name} settings and select OpenAI Compatible. Enter the base URL, model ID, and key in the UI. ${target==='roo'?'Roo requires native tool calling; verify this model supports it before using agent mode.':'Verify the selected model supports the tool calling needed by your workflow.'} Set context limits or capabilities only from verified model documentation.`;
+  else if(target==='codex')instructions=`Set ATMOROUTER_API_KEY securely in your ${shell==='powershell'?'PowerShell':'shell'} environment, then launch your installed Codex through the loopback bridge:\nnpx @atmorouter/helper codex --model ${model}\nThe launcher supplies configuration for this run without overwriting your Codex config. Compatibility depends on the installed Codex version and the client/model tool behavior; verify the launch in your environment.\n\nFor a standalone bridge:\nnpx @atmorouter/helper bridge --port 43187\nMerge this TOML configuration manually if needed (root settings must precede provider tables):\nmodel = "${model}"\nmodel_provider = "atmorouter"\nweb_search = "disabled"\n\n[model_providers.atmorouter]\nname = "AtmoRouter local bridge"\nbase_url = "http://127.0.0.1:43187/v1"\nenv_key = "ATMOROUTER_API_KEY"\nwire_api = "responses"\nrequires_openai_auth = false\nsupports_websockets = false\n\nKeys stay in the environment. This bridge supports a stateless text and function-tool subset. Stored responses, images, hosted tools, and remote compaction are unsupported.`;
+  else if(target==='antigravity')instructions='Unsupported native IDE setup: no documented native custom endpoint configuration is available. No IDE files will be modified. The SDK LocalOpenAIAgentConfig transport has no authenticated API-key field; SDK examples do not establish authenticated native IDE support.';
+  else if(target==='continue')instructions='Use configure --target continue for a YAML plan. For the IDE, manually set ATMOROUTER_API_KEY=<your key> in ~/.continue/.env and restart the IDE. Shell environment variables work with Continue CLI only. Docs: https://docs.continue.dev/faqs';
+  else throw Error('This integration uses automatic configuration, environment snippets, or the local Codex bridge.');
+  return `${info.name}\n${details}\n\n${instructions}\nDocs: ${info.docsUrl}`;
+}
+
+export async function assertSafeConfigurationPath(file) {
+  for(let current=path.resolve(file);;current=path.dirname(current)) {
+    try {const stat=await fs.lstat(current);if(stat.isSymbolicLink())throw Error('Configuration path contains a symbolic link; merge manually.');}
+    catch(error){if(error.code!=='ENOENT')throw error;}
+    if(path.dirname(current)===current)break;
+  }
+}
+async function exists(file) {
+  try {await fs.lstat(file);return true;}catch(error){if(error.code==='ENOENT')return false;throw error;}
+}
+function mapping(doc,keys,label) {
+  const node=doc.getIn(keys,true);
+  if(node!==undefined&&!isMap(node))throw Error(`${label} must be a YAML mapping; merge manually.`);
+  if(node===undefined)doc.setIn(keys,doc.createNode({}));
+  return doc.getIn(keys,true);
+}
+function checkCredentials(node,expected) {
+  if(!node)return;
+  visit(node,{
+    Pair(_,pair){
+      const key=String(pair.key?.value ?? '').toLowerCase();
+      if(/authorization|api[-_]?key|secret|credential|cookie/.test(key)||['auth','token','authtoken','accesstoken','access_token','refreshtoken','refresh_token','bearertoken','bearer_token','x-auth-token'].includes(key)) {
+        if(key==='apikey'&&pair.value?.value===expected)return;
+        throw Error('Existing AtmoRouter configuration has credential headers or secret overrides. Resolve them manually.');
+      }
+    },
+  });
+}
+function parseConfiguration(original) {
+  const doc=parseDocument(original??'{}\n',{uniqueKeys:true,strict:true});
+  if(doc.errors.length||doc.warnings.length)throw Error('Existing YAML is malformed, has duplicate keys, or uses unsupported tags; merge manually.');
+  if(!isMap(doc.contents))throw Error('Configuration root must be a YAML mapping.');
+  visit(doc,(_,node)=>{
+    if(isAlias(node)||node?.tag||node?.key?.value==='<<')throw Error('YAML aliases, merge keys, and explicit tags require a manual merge.');
+  });
+  return doc;
+}
+export async function planYamlConfiguration(target,model,{directory,home=os.homedir(),env=process.env}={}) {
+  validateModel(model);
+  if(!['omp','continue'].includes(target))throw Error('Unknown YAML integration.');
+  if(target==='omp'&&!directory&&(env.PI_CONFIG_DIR||env.PI_PROFILE||env.OMP_PROFILE))throw Error('Custom OMP config roots or named profiles require an explicit --config-dir pointing to the active agent directory.');
+  const folder=path.resolve(directory||(target==='omp'?(env.PI_CODING_AGENT_DIR||path.join(home,'.omp','agent')):path.join(home,'.continue')));
+  let name=target==='omp'?'models.yml':'config.yaml';
+  if(target==='omp') {
+    const yml=await exists(path.join(folder,'models.yml')),yaml=await exists(path.join(folder,'models.yaml'));
+    if(yml&&yaml)throw Error('Both models.yml and models.yaml exist; resolve the alternate configuration manually.');
+    if(await exists(path.join(folder,'models.json'))||await exists(path.join(folder,'models.jsonc')))throw Error('Legacy OMP models.json configuration exists; migrate it manually first.');
+    if(yaml)name='models.yaml';
+  }else if(await exists(path.join(folder,'config.yml'))||await exists(path.join(folder,'config.json'))||await exists(path.join(folder,'config.ts')))throw Error('An alternate or legacy Continue configuration exists; merge it manually.');
+  const file=path.join(folder,name);
+  await assertSafeConfigurationPath(file);
+  let original=null;
+  try {const stat=await fs.lstat(file);if(!stat.isFile())throw Error('Configuration must be a regular file.');original=await fs.readFile(file,'utf8');}catch(error){if(error.code!=='ENOENT')throw error;}
+  const doc=parseConfiguration(original);
+  let patch;
+  if(target==='omp') {
+    mapping(doc,['providers'],'OMP providers');
+    const provider=mapping(doc,['providers','atmorouter'],'OMP AtmoRouter provider');
+    checkCredentials(provider,'ATMOROUTER_API_KEY');
+    const models=provider.get('models',true);
+    if(models!==undefined&&!isSeq(models))throw Error('OMP AtmoRouter models must be a sequence.');
+    const added={id:model,name:model};
+    const fields={baseUrl:base,apiKey:'ATMOROUTER_API_KEY',api:'openai-completions',authHeader:true};
+    for(const [key,value] of Object.entries(fields))provider.set(key,value);
+    if(!models)provider.set('models',doc.createNode([added]));
+    else if(!models.items.some(item=>isMap(item)&&item.get('id')===model))models.add(doc.createNode(added));
+    patch={providers:{atmorouter:{...fields,models:[added]}}};
+  }else {
+    if(original===null)for(const [key,value] of Object.entries({name:'AtmoRouter',version:'1.0.0',schema:'v1'}))doc.set(key,value);
+    let models=doc.get('models',true);
+    if(models!==undefined&&!isSeq(models))throw Error('Continue models must be a YAML sequence.');
+    if(!models){doc.set('models',doc.createNode([]));models=doc.get('models',true);}
+    const name=`AtmoRouter (${model})`;
+    const matching=[];
+    for(const item of models.items) {
+      if(!isMap(item))throw Error('Continue model entries must be mappings; merge manually.');
+      if(item.get('apiBase')===base||String(item.get('name')||'').startsWith('AtmoRouter ('))checkCredentials(item,secret);
+      if(item.get('name')===name||(item.get('apiBase')===base&&item.get('model')===model))matching.push(item);
+    }
+    if(matching.length>1)throw Error('Multiple matching AtmoRouter models exist; merge manually.');
+    const added={name,provider:'openai',model,apiBase:base,apiKey:secret,roles:['chat','edit','apply']};
+    if(matching.length)for(const [key,value] of Object.entries(added))matching[0].set(key,doc.createNode(value));
+    else models.add(doc.createNode(added));
+    patch={models:[added]};
+  }
+  const instructions=target==='continue'
+    ? 'For Continue IDE, manually set ATMOROUTER_API_KEY=<your key> in ~/.continue/.env and restart the IDE. For a custom config directory, use a Continue-supported .env location. Shell environment variables work with Continue CLI only. See https://docs.continue.dev/faqs. Verify model tool support before agent mode.'
+    : `Set ATMOROUTER_API_KEY in the environment before launching OMP, then run: omp --model atmorouter/${model}. Named profiles require --config-dir pointing to the active agent directory. Verify native tool support for agent use.`;
+  return {file,target,original,patch,content:doc.toString(),instructions};
+}

package/package.json

@@ -1,14 +1,42 @@
 {
   "name": "@atmorouter/helper",
-  "version": "0.1.0",
-  "description": "Configure AtmoRouter connections for Claude Code and OpenCode",
+  "version": "0.2.0",
+  "description": "Configure AtmoRouter coding agents, guide IDE setup, and run a local Codex bridge",
   "homepage": "https://atmorouter.dev/docs/helper",
-  "keywords": ["atmorouter", "claude-code", "opencode", "setup", "cli"],
-  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "keywords": [
+    "atmorouter",
+    "claude-code",
+    "opencode",
+    "codex",
+    "cursor",
+    "continue",
+    "setup",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "type": "module",
   "license": "UNLICENSED",
-  "engines": { "node": ">=22" },
-  "bin": { "atmorouter-helper": "bin/atmorouter-helper.mjs" },
-  "files": ["bin", "lib", "README.md"],
-  "scripts": { "test": "node --test", "test:package": "node scripts/verify-package.mjs" }
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "atmorouter-helper": "bin/atmorouter-helper.mjs"
+  },
+  "files": [
+    "bin/atmorouter-helper.mjs",
+    "lib/helper.mjs",
+    "lib/integrations.mjs",
+    "lib/bridge.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "test:package": "node scripts/verify-package.mjs"
+  },
+  "dependencies": {
+    "yaml": "2.9.1"
+  }
 }