@1endpoint/coding-helper 0.1.1 → 0.1.3

package/README.md

@@ -1,123 +1,196 @@
 # @1endpoint/coding-helper
 
-Safe, isolated setup for **DeepSeek Harness** and **Claude Code CLI** using the single 1endpoint API base URL:
+Connect **DeepSeek Harness** or **Claude Code** to 1endpoint with an interactive setup menu. Choose your language, select models, and manage your connection without editing configuration files by hand.
 
-```text
-https://1endpoint.dev/api/v1
+## Before you start
+
+- Install **Node.js 22.19 or newer**.
+- Install [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) or [Claude Code](https://code.claude.com/docs/en/overview) separately. The helper configures these tools; it does not install them.
+- Have a 1endpoint API key ready. Keep it private: do not paste it into command arguments, shared configuration files or a repository.
+
+## 1. Open the helper
+
+Run this in your terminal:
+
+```bash
+npx @1endpoint/coding-helper
 ```
 
-**Release status: not yet published to npm.** The following registry commands become available only after the maintainer publishes the package. Until then, run the local executable or a reviewed tarball. This helper is an independent integration, not an official DeepSeek or Anthropic product.
+1. Choose **English** or **Tiếng Việt**.
+2. Choose **Setup**.
+3. Select **DSH** or **Claude Code**.
+4. Paste your API key into the masked prompt, or select **Open Console** and press Enter to create a key first.
+5. Choose whether to save the key locally or use it for this session only.
+6. Select models from the 1endpoint catalog.
+7. Review the selection, then choose **Confirm**.
+
+Use **↑ / ↓** to move and **Enter** to select. Press **Escape** to cancel. Confirmation is a selection, not a typed `y/n` answer.
+
+### Choosing models
+
+For DSH, choose the model you want to use by default.
+
+For Claude Code, choose a 1endpoint model for each tier: **Haiku**, **Sonnet** and **Opus**. Each tier can use a different model. Sonnet is used as the main/default selection. Select optional **Fable** mapping only if your installed Claude Code version supports that tier; otherwise keep the standard three-tier option.
+
+If the catalog cannot be loaded, choose **Retry**, explicitly choose **Manual model ID**, or **Cancel**. The helper does not silently substitute a model.
+
+## 2. Provide your API key
 
-## Requirements
+Paste your key directly into the helper's **masked API-key prompt**. The key is not shown on screen or placed in command arguments.
 
-- Node.js **22.19 or newer** (tested locally on Node 24).
-- Install the desired coding tool separately from its official distribution. The helper does not download tools or run installation scripts.
-- An enabled public model ID from the [1endpoint model catalog](https://console.1endpoint.dev/models).
-- Set `ONEENDPOINT_API_KEY` in the launching process environment using your shell or secret manager. Never put the key in command arguments, a Git repository, or a shared configuration file.
+Need a key? Select **Open Console** and press **Enter**. The helper opens [API keys](https://console.1endpoint.dev/api-keys), or the [Vietnamese API-key page](https://console.1endpoint.dev/vi/api-keys) when Vietnamese is selected. Create a key, copy it, return to the terminal and paste it into the prompt.
 
-## Setup
+Choose how to use the key:
 
-After publication:
+- **Save locally:** remember it for the selected tool, so future launches do not require manual environment export. The saved file is plaintext, **not encrypted**, protected with private file permissions (0600 file, 0700 directory on POSIX systems). Other processes running as your user may still access it.
+- **This session only:** keep it in memory for this helper process. After setup, select **Start a new session now** to launch with it. Reopening the helper later requires entering the key again.
+- **Use an existing key:** reuse an available environment or saved key without displaying its value.
+
+DSH and Claude Code store their keys separately. An explicit session key takes priority, followed by `ONEENDPOINT_API_KEY`, then the selected tool's saved key. The helper never puts keys in generated tool settings, model configuration, backups or logs.
+
+### Optional: use an environment variable
+
+If you prefer a secret manager or shell environment instead of local storage, provide `ONEENDPOINT_API_KEY`. For **Bash**, this hidden prompt keeps the key out of the command itself:
 
 ```bash
-npx @1endpoint/coding-helper
-# First choose English / Tiếng Việt, then the action.
-# Colorful menu: use ↑/↓ and Enter; Escape cancels. No typed y/n.
-# Setup, reconfigure, remove, diagnose and run are available in the menu.
-# Fetches public 1endpoint text models for selection; Claude tiers map independently.
-# Or explicit, scriptable setup:
-npx @1endpoint/coding-helper setup --tool dsh --model your-model-id --dry-run
-npx @1endpoint/coding-helper setup --tool dsh --model your-model-id
-npx @1endpoint/coding-helper setup --tool claude --model your-model-id
+read -r -s -p "1endpoint API key: " ONEENDPOINT_API_KEY
+printf '\n'
+export ONEENDPOINT_API_KEY
+```
+
+For another shell, use its secure environment-variable mechanism or your secret manager. Do not type a real key into a command you intend to share. A key set in one terminal is not automatically available in another terminal or after restarting the shell.
+
+## 3. Check the connection setup
+
+For DSH:
+
+```bash
+npx @1endpoint/coding-helper doctor --tool dsh
+```
+
+For Claude Code:
+
+```bash
+npx @1endpoint/coding-helper doctor --tool claude
+```
+
+Doctor checks your saved connection configuration, whether the tool is installed, and whether an environment or saved API key is available. It does not validate the key against the server or make an inference request.
+
+## 4. Start a new tool session
+
+**After setup or reconfiguration, close the old tool session and start a new session through the helper. An already-open session does not pick up the new connection or model mapping.**
+
+Start DSH:
+
+```bash
+npx @1endpoint/coding-helper run --tool dsh
 ```
 
-Before publication, from the repository:
+Start Claude Code:
 
 ```bash
-yarn install --immutable
-yarn test
-node src/cli.mjs setup --tool dsh --model your-model-id --dry-run
-node src/cli.mjs setup --tool dsh --model your-model-id
+npx @1endpoint/coding-helper run --tool claude
 ```
 
-**After setup or reconfigure, restart the DSH/Claude Code session for changes to take effect. An already-open session does not update automatically. Start the new session through `coding-helper run`, not the original tool command, to use the isolated helper profile.**
+You can also reopen the helper and select **Run**.
+
+**Use the helper to launch the configured session.** Running `dsh` or `claude` directly uses the tool's ordinary configuration, not this helper connection. Tool requests may incur charges; the tool's normal permission and workspace-trust prompts remain active.
+
+### Important Claude Code behavior
+
+The helper uses an isolated configuration. **Project/local settings, including their hooks and permissions, are not loaded in this mode.** Managed organization policy still applies, and the helper does not enable permission bypass. If your project requires those local restrictions or hooks, use your organization's approved configuration instead.
 
-The wizard begins with **English / Tiếng Việt** selection before configuration/reconfiguration/deletion. It fetches the public 1endpoint text model catalog for arrow-key choices. Claude's Haiku, Sonnet and Opus tiers can each map to a different public model; optional Fable mapping is available for versions supporting that tier. The helper does not infer vendor/model equivalence from names. If catalog loading fails, choose Retry, explicit manual ID entry, or Cancel.
+### Important DSH behavior
 
-Setup never asks for, reads, validates or stores your API key. It creates only helper-owned files under `~/.1endpoint/coding-helper`. Use an absolute `ONEENDPOINT_HELPER_HOME` to choose a different state directory. Dry-run makes no writes. Existing DSH and Claude user configuration is not edited or imported.
+DSH runs with a separate home, so your ordinary sessions, plugins and provider settings are not imported or changed. Supported profiles are `web` (default), `headless`, `acp` and `sdk`; `sdk-minimal` is not supported.
 
-## Diagnose and launch
+## Change models
 
-After setting the key in your process environment:
+Open the helper again, select **Reconfigure**, choose the tool, and select new models:
 
 ```bash
-coding-helper doctor --tool dsh
-coding-helper run --tool dsh
-coding-helper run --tool dsh --profile headless -- 'Reply exactly OK'
-coding-helper doctor --tool claude
-coding-helper run --tool claude
-coding-helper run --tool claude -- -p 'Reply exactly OK'
+npx @1endpoint/coding-helper
 ```
 
-For npx-only use, replace `coding-helper` with `npx @1endpoint/coding-helper`. For local use, replace it with `node src/cli.mjs`.
+The previous connection configuration is backed up automatically. **Restart the tool session through the helper after confirming the change.**
+
+For scripted use, preview and apply a DSH model change:
+
+```bash
+npx @1endpoint/coding-helper reconfigure --tool dsh --model your-model-id --dry-run
+npx @1endpoint/coding-helper reconfigure --tool dsh --model your-model-id
+```
 
-`doctor` verifies owned-file integrity, CLI availability and whether the key environment variable is present. It does **not** validate credentials, make network requests, call inference, execute an apiKeyHelper or read your original tool credentials. `run` is explicit consent to launch the selected tool; tool startup and inference can contact networks and incur charges. Permission/trust prompts remain tool-owned. Authentication, provider health and real inference are separate from local configuration tests.
+Replace `your-model-id` with the exact public model ID you want to use. Replace `dsh` with `claude` for Claude Code. To set separate Claude tiers explicitly:
 
-### DeepSeek Harness
+```bash
+npx @1endpoint/coding-helper reconfigure --tool claude \
+  --model your-main-model-id \
+  --haiku-model your-fast-model-id \
+  --sonnet-model your-balanced-model-id \
+  --opus-model your-strong-model-id
+```
 
-- Uses a separate `DSH_HOME` plus a dedicated `--patch` overlay.
-- Configures the native `llm-pi-ai` provider with `api: openai-completions`, `baseURL` and `apiKeyEnv: ONEENDPOINT_API_KEY`.
-- Configures the native `agent-default-model` selection. No secret interpolation, custom proxy or injected agent instruction is required.
-- Supported profiles: `web`, `headless`, `acp`, `sdk`. `sdk-minimal` lacks the required entries and is deliberately rejected.
-- The helper does not reuse current sessions, plugins, model presets or provider configurations. Existing sessions can retain their own model selection; start a new session in the isolated profile.
-- DSH owns request assembly, conversation state, streaming, tool loops and permissions. The helper only sets the connection.
-- Verified configuration contract: DSH `0.2.1-alpha.3`. This prerelease contract may change. A successful dump exit code alone is insufficient: the integration tests also inspect provider and selected-model rows. The shipped Web schema dump has a separate preset/tree-carrier failure; headless schema validation is the supported check.
+An optional `--fable-model` sets Fable explicitly. Without it, Fable follows Opus. Explicit tier selections take priority over the `--model` fallback. Explicit model IDs in your own agent/skill definitions or managed policy are not rewritten by these default mappings.
 
-### Claude Code CLI
+## Remove the connection
 
-- Uses a separate `CLAUDE_CONFIG_DIR`, a helper-owned `--settings` file and `--setting-sources user`.
-- **Project and local settings, including their hooks and permissions, are intentionally not loaded.** This is a tradeoff for deterministic routing, not transparent preservation of project behavior. Managed/organization policy still applies and can override the connection. Do not use this mode if those project restrictions are required; configure the tool manually with your administrator instead.
-- The raw process key becomes `ANTHROPIC_AUTH_TOKEN` in the child environment only. The CLI constructs the Bearer header. No key is written to settings or included in argv.
-- Maps main, Opus, Sonnet, Haiku, optional Fable and default subagent roles. The wizard offers distinct catalog selections per tier; scripted setup accepts `--haiku-model`, `--sonnet-model`, `--opus-model` and optional `--fable-model`. `--model` is the main/default fallback; explicit role selections take priority. Without a Fable mapping it follows the Opus selection. Explicit model IDs in agent/skill definitions or managed policy are outside that default mapping; no promise is made to rewrite every model choice.
-- Clears inherited conflicting Anthropic/cloud authentication and routing variables in the child only. It does not log out, modify the parent's environment, bypass permission prompts or execute existing key helpers.
-- Uses the same universal base URL above. Claude appends `/v1/messages`, producing `/api/v1/v1/messages`, a supported gateway alias. Do not change the base to a different per-client URL.
-- Claude owns request assembly, conversation state, streaming and tool execution. Version verification and fixture boundaries are recorded in the release checklist.
+Stop the tool session first. Open the helper, select **Remove**, choose the tool and confirm the removal. You do not need to find or delete configuration files yourself.
 
-## Update, backup and recovery
+Alternatively, preview and confirm removal:
 
 ```bash
-coding-helper backup --tool dsh
-coding-helper reconfigure --tool dsh --model another-public-model --dry-run
-coding-helper reconfigure --tool dsh --model another-public-model
-coding-helper remove --tool dsh --dry-run
-coding-helper remove --tool dsh --yes
+npx @1endpoint/coding-helper remove --tool dsh --dry-run
+npx @1endpoint/coding-helper remove --tool dsh --yes
 ```
 
-`reconfigure` validates the unchanged helper manifest/configuration, automatically backs up the verified old connection configuration and changes the model. Legacy `setup --update` is also available. Backups contain only generated configuration, never keys. Identical setup is idempotent. Normal setup refuses unknown files, modified configuration, malformed manifests and symlink state paths. Writes use an exclusive setup lock, private file permissions and atomic replacement; failed configuration writes attempt rollback.
+Use `--tool claude` for Claude Code. The menu asks whether to **keep or delete the saved API key**. For scripted removal, add `--remove-key` to delete it explicitly:
+
+```bash
+npx @1endpoint/coding-helper remove --tool dsh --yes --remove-key
+```
 
-`remove` previews with `--dry-run` and requires explicit `--yes` to delete the selected tool's generated connection file and manifest. It preserves runtime homes, conversations, backups, unrelated files and all original tool settings. **Stop the corresponding tool before removing its connection configuration.** To return to normal tools, launch `dsh` or `claude` directly without the helper.
+Without that choice, the saved key is retained. Removal deletes only the helper-generated connection configuration and, when selected, its saved key. **Your original tool settings, runtime conversations and configuration backups are preserved.** To return to your ordinary setup, launch `dsh` or `claude` directly.
 
-For corrupted or hand-modified helper configuration, use `coding-helper remove --tool dsh --force --yes` (or `claude`), then run setup again. Force recovery targets only the fixed helper-generated connection file and manifest, never paths read from a damaged manifest; it does not copy potentially secret-bearing tampered content into backups. Symlinks remain refused even in force mode. There is no need to find and delete configuration files manually. Runtime homes may contain tool-created conversations or credentials; they are intentionally retained, not silently wiped or backed up. Do not share or commit them. A stale setup lock still requires reviewing that no setup is active before retrying; do not defeat a live writer lock.
+### Recover from damaged connection configuration
 
-This is configuration isolation, **not an OS sandbox**. The coding tools still have their ordinary filesystem/network access and can create runtime data. No unattended install, background daemon, automatic paid smoke, telemetry or global config migration is included.
+If the helper reports that its generated configuration has been modified or corrupted, choose **Force removal recovery** in the Remove menu, review the warning and confirm. Then run Setup again.
 
-## Development and packaging
+For scripted recovery:
 
 ```bash
-yarn install --immutable
-yarn check
-yarn test
-yarn pack --out ../coding-helper-0.1.0.tgz
+npx @1endpoint/coding-helper remove --tool dsh --force --yes
 ```
 
-No production dependencies and no build step. The published entry is native ESM. Package contents are allowlisted. See the [publishing guide](docs/PUBLISHING.md) for step-by-step npm authentication, first publication, verification, updates and troubleshooting. See the [release checklist](docs/RELEASE.md) for current verification boundaries. Publishing is a separate maintainer action; creating or pushing the repository does not publish npm.
+Force removal deletes only the fixed helper connection files, including modified contents, without backing up those modified contents. It still preserves original tool settings and runtime conversations. Use it only for recovery, not routine reconfiguration.
+
+## Configuration and privacy
+
+- The shared API base URL is `https://1endpoint.dev/api/v1`.
+- Connection configuration is stored under `~/.1endpoint/coding-helper`. Set an absolute `ONEENDPOINT_HELPER_HOME` if you need a different location.
+- Setup does not overwrite your existing DSH or Claude Code configuration.
+- The interactive menu fetches the public text-model catalog without sending your API key. Explicit setup, reconfigure and doctor commands work locally.
+- Your key is supplied to the launched tool through its process environment, not saved in the helper's connection files.
+- Runtime tools can create their own session data. Keep their isolated homes private.
+- Configuration isolation is **not an operating-system sandbox**; the tools retain their ordinary filesystem and network access.
 
-## Reference and attribution
+This is an independent integration, not an official DeepSeek or Anthropic product.
 
-The onboarding/product design was reviewed against [Z.AI coding-helper](https://www.npmjs.com/package/@z_ai/coding-helper) `0.1.1`: wizard, per-tool setup and doctor. Its registry metadata labels the package Proprietary. No implementation code is copied; this is an independent implementation with an explicit test suite, no stored API keys, and no automatic tool installation. The reference has no DSH support and is not authority for the DSH configuration contract.
+## Troubleshooting
 
-Official references: [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), [Claude gateway setup](https://code.claude.com/docs/en/llm-gateway-connect), [settings](https://code.claude.com/docs/en/settings), [models](https://code.claude.com/docs/en/model-config).
+| Problem | What to do |
+| --- | --- |
+| Node version error | Install Node.js 22.19 or newer, then reopen your terminal. |
+| CLI not found | Install the selected coding tool and make sure its executable is on your `PATH`. |
+| API key missing | Open the helper and paste a key, or press Enter on Open Console to create one. Choose Save locally for future launches. |
+| Catalog unavailable | Choose Retry, or explicitly choose manual entry with a known public model ID. |
+| New model is not taking effect | Close the old session and start a new one with the helper's Run action. |
+| Ordinary tool launch ignores the helper | Launch through `npx @1endpoint/coding-helper run --tool dsh` or `--tool claude`. |
+| Generated configuration is damaged | Use Remove → Force removal recovery, then Setup again. |
+| Authentication or model request fails | Confirm your key, model access and account balance in 1endpoint. Doctor does not validate server-side access. |
 
-## Tiếng Việt
+## More help
 
-Helper hỗ trợ ưu tiên DeepSeek Harness và Claude Code CLI; dùng một base URL chung, home riêng và API key từ biến môi trường. Không sửa cấu hình công cụ đang dùng, không lưu key, không tự cài công cụ và không tự gọi inference có phí. `setup --dry-run` xem trước; `doctor` chỉ kiểm tra cục bộ; `run` mới khởi chạy công cụ. Claude chạy ở chế độ này **không nạp settings/hook/quyền project-local**; chính sách quản trị vẫn có hiệu lực. Package chưa publish: dùng lệnh local ở trên cho tới khi maintainer phát hành. Hướng dẫn Console có cả EN/VI.
+- [Console usage guide](https://console.1endpoint.dev/docs/guides/coding-tools/coding-helper)
+- [Report a problem](https://github.com/dothinh115/1endpoint-coding-helper/issues)
+- Maintainers: [publishing](docs/PUBLISHING.md) and [release verification](docs/RELEASE.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1endpoint/coding-helper",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Safe isolated 1endpoint setup for DeepSeek Harness and Claude Code CLI",
   "type": "module",
   "bin": {

package/src/browser.mjs

@@ -0,0 +1,40 @@
+import { spawn } from 'node:child_process'
+
+/** Explicitly open only the Console create-key page; never accepts a caller URL. */
+export function openConsole({ language = 'en', spawnImpl = spawn, platform = process.platform } = {}) {
+  const url = language === 'vi' ? 'https://console.1endpoint.dev/vi/api-keys' : 'https://console.1endpoint.dev/api-keys'
+  const command = platform === 'darwin' ? 'open' : platform === 'win32' ? 'rundll32.exe' : 'xdg-open'
+  const args = platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url]
+  return new Promise((resolve, reject) => {
+    let child, timer, settled = false
+    const fail = () => {
+      const error = new Error('Could not open Console. Try again or open the Console API keys page manually.')
+      error.code = 'BROWSER_OPEN_FAILED'
+      return error
+    }
+    const finish = error => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      if (child) {
+        child.off('error', onError)
+        child.off('close', onClose)
+        // Absorb a late spawn error after timeout.
+        child.on('error', () => {})
+      }
+      if (error) reject(error)
+      else resolve()
+    }
+    const onError = () => finish(fail())
+    const onClose = code => finish(code === 0 ? undefined : fail())
+    try {
+      child = spawnImpl(command, args, { shell: false, stdio: 'ignore', windowsHide: true })
+      child.once('error', onError)
+      child.once('close', onClose)
+      timer = setTimeout(() => {
+        try { child.kill() } catch {}
+        finish(fail())
+      }, 5000)
+    } catch { finish(fail()) }
+  })
+}

package/src/cli.mjs

@@ -7,13 +7,14 @@ import { wizard, colorize } from './ui.mjs'
 import { setup, reconfigure, remove, backup, loadState, stateRoot, validateTool, assertSafePath } from './state.mjs'
 import { launchClaude, childEnvironment } from './adapters/claude.mjs'
 import { launchDsh } from './adapters/dsh.mjs'
+import { getCredential, saveCredential, removeCredential } from './credentials.mjs'
 
 const HELP = `@1endpoint/coding-helper — isolated 1endpoint coding-tool setup
 
 Usage:
   coding-helper setup --tool dsh|claude --model PUBLIC_MODEL [--dry-run] [--update]
   coding-helper reconfigure --tool dsh|claude --model PUBLIC_MODEL [--dry-run]
-  coding-helper remove --tool dsh|claude [--yes] [--dry-run] [--force]
+  coding-helper remove --tool dsh|claude [--yes] [--dry-run] [--force] [--remove-key]
   coding-helper doctor --tool dsh|claude
   coding-helper run --tool dsh|claude [--profile web|headless|acp|sdk] -- [tool args]
   coding-helper backup --tool dsh|claude
@@ -24,7 +25,9 @@ Wizard fetches public 1endpoint text models for independent tool/tier selections
 Claude setup/reconfigure accepts --haiku-model ID --sonnet-model ID --opus-model ID
 and optional --fable-model ID for supporting versions. --model is the main/default fallback.
 Node.js >=22.19 is required.
-API key: export ONEENDPOINT_API_KEY in your shell; never pass it as an argument.
+Paste your API key privately in the menu, or press Enter on Open Console to create one.
+Choose private local storage or session-only use. Saved keys are plaintext private files, not encrypted.
+ONEENDPOINT_API_KEY remains an optional environment override; never pass keys as arguments.
 State: ONEENDPOINT_HELPER_HOME or ~/.1endpoint/coding-helper (isolated tool homes).
 No existing DSH/Claude settings are edited. Setup/doctor make no API requests.
 Claude launch excludes project/local settings, hooks and permissions; managed policy applies.
@@ -38,12 +41,12 @@ function parse(argv) {
   while (args.length) {
     const arg = args.shift()
     if (arg === '--') { forwarded.push(...args); break }
-    if (['--dry-run', '--update', '--yes', '--force'].includes(arg)) { if (options[arg]) throw new Error('Duplicate option.'); options[arg] = true; continue }
+    if (['--dry-run', '--update', '--yes', '--force', '--remove-key'].includes(arg)) { if (options[arg]) throw new Error('Duplicate option.'); options[arg] = true; continue }
     if (!['--tool', '--model', '--profile', '--haiku-model', '--sonnet-model', '--opus-model', '--fable-model'].includes(arg)) throw new Error('Unknown option. Use --help. API keys must never be command-line arguments.')
     if (options[arg] !== undefined || !args.length || args[0].startsWith('-')) throw new Error('Missing or duplicate option value.')
     options[arg] = args.shift()
   }
-  const allowed = { setup: ['--tool', '--model', '--dry-run', '--update', '--haiku-model', '--sonnet-model', '--opus-model', '--fable-model'], reconfigure: ['--tool', '--model', '--dry-run', '--haiku-model', '--sonnet-model', '--opus-model', '--fable-model'], remove: ['--tool', '--yes', '--dry-run', '--force'], doctor: ['--tool'], backup: ['--tool'], run: ['--tool', '--profile'] }
+  const allowed = { setup: ['--tool', '--model', '--dry-run', '--update', '--haiku-model', '--sonnet-model', '--opus-model', '--fable-model'], reconfigure: ['--tool', '--model', '--dry-run', '--haiku-model', '--sonnet-model', '--opus-model', '--fable-model'], remove: ['--tool', '--yes', '--dry-run', '--force', '--remove-key'], doctor: ['--tool'], backup: ['--tool'], run: ['--tool', '--profile'] }
   if (!allowed[command] || Object.keys(options).some(key => !allowed[command].includes(key)) || (command !== 'run' && forwarded.length)) throw new Error('Invalid command/options. Use --help.')
   validateTool(options['--tool'])
   if (options['--tool'] !== 'claude' && ['haiku', 'sonnet', 'opus', 'fable'].some(role => options[`--${role}-model`])) throw new Error('Tier model flags are only supported for Claude.')
@@ -63,7 +66,10 @@ async function executable(command, env) {
   return null
 }
 async function main(argv, context = {}) {
-  if (!argv.length) return wizard({ dispatch: main })
+  if (!argv.length) return wizard({ dispatch: main, getKeyStatus: async ({ tool }) => {
+    const credential = await getCredential({ stateDir: stateRoot(), tool })
+    return { available: Boolean(credential.key), source: credential.source }
+  } })
   if (argv.length === 1 && ['--help', '-h'].includes(argv[0])) { console.log(HELP); return }
   if (argv.length === 1 && ['--version', '-v'].includes(argv[0])) {
     const metadata = JSON.parse(await fs.readFile(new URL('../package.json', import.meta.url), 'utf8'))
@@ -76,8 +82,12 @@ async function main(argv, context = {}) {
     const result = await remove({ stateDir, tool, dryRun: options['--dry-run'], yes: options['--yes'], force: options['--force'] })
     console.log(`${result.dryRun ? t('Preview removal', 'Xem trước việc xóa') : result.changed ? t('Removed helper configuration', 'Đã xóa cấu hình riêng') : t('Already removed', 'Cấu hình đã được xóa')}: ${tool}`)
     for (const file of result.files) console.log(`  ${file}`)
+    if (options['--remove-key'] || context.removeKey) {
+      await removeCredential({ stateDir, tool, dryRun: Boolean(options['--dry-run']) })
+      console.log(options['--dry-run'] ? t('Saved-key removal preview only.', 'Chỉ xem trước việc xóa khóa đã lưu.') : t('Saved API key removed (if present).', 'Đã xóa khóa API đã lưu (nếu có).'))
+    }
     if (result.force) console.log(t('Forced recovery removes only fixed helper configuration paths; modified contents are not backed up.', 'Khôi phục cưỡng chế chỉ xóa đường dẫn cấu hình riêng cố định; nội dung đã sửa không được sao lưu.'))
-    console.log(t('Existing user settings, runtime homes, backups and unknown files were preserved.', 'Đã giữ nguyên cài đặt gốc, dữ liệu phiên chạy, bản sao lưu và các tệp khác.'))
+    console.log(t('Original tool settings, conversations and backups are unchanged.', 'Cài đặt gốc, hội thoại và bản sao lưu được giữ nguyên.'))
     return
   }
   if (command === 'setup' || command === 'reconfigure') {
@@ -87,25 +97,31 @@ async function main(argv, context = {}) {
     for (const file of result.files) console.log(`  ${file.path}`)
     if (context.language !== 'vi') for (const hint of result.hints || []) console.log(hint)
     else console.log(tool === 'claude' ? 'Không nạp cài đặt, hook và quyền project/local. Chính sách quản trị vẫn áp dụng; không bỏ qua quyền.' : 'DSH dùng home và cấu hình riêng; không sửa cài đặt gốc. Chế độ sdk-minimal không được hỗ trợ.')
-    console.log(t('Set ONEENDPOINT_API_KEY in your shell, then use run --tool ', 'Đặt ONEENDPOINT_API_KEY trong môi trường shell, sau đó dùng run --tool ') + tool + t('. No key was saved.', '. Không lưu khóa API.'))
+    if (!result.dryRun && context.apiKey && context.saveKey) {
+      await saveCredential({ stateDir, tool, key: context.apiKey })
+      console.log(t('API key saved privately for this tool. Local storage is not encrypted.', 'Đã lưu khóa API riêng cho công cụ này. Tệp lưu cục bộ không được mã hóa.'))
+    } else if (context.apiKey) console.log(t('API key is available for this session only.', 'Khóa API chỉ dùng trong phiên này.'))
+    else console.log(t('Use the interactive menu to paste an API key, or provide ONEENDPOINT_API_KEY in your environment.', 'Mở menu để dán khóa API, hoặc cung cấp ONEENDPOINT_API_KEY qua môi trường.'))
     if (!result.dryRun && !context.language) console.log(colorize('RESTART REQUIRED: existing sessions are not updated. Start a new session through coding-helper run --tool ' + tool + '.', 'warning'))
     return
   }
   if (command === 'backup') { console.log('Secret-free configuration backup: ' + await backup({ stateDir, tool })); return }
   const { state, plan } = await loadState(stateDir, tool)
+  const credential = context.apiKey ? { key: context.apiKey, source: 'session' } : await getCredential({ stateDir, tool })
   const bin = await executable(plan.command, process.env)
   if (command === 'doctor') {
     console.log(`${t('Configuration integrity: OK', 'Tính toàn vẹn cấu hình: OK')} (${tool})`)
     console.log(`${t('CLI installed', 'Đã cài CLI')}: ${bin ? t('yes', 'có') : t('no', 'chưa')}`)
-    console.log(`ONEENDPOINT_API_KEY: ${process.env.ONEENDPOINT_API_KEY ? t('present (not validated)', 'đã có (chưa xác thực)') : t('missing', 'chưa có')}`)
+    console.log(`${t('API key', 'Khóa API')}: ${credential.key ? t('available (not validated)', 'đã có (chưa xác thực)') : t('missing', 'chưa có')}`)
     console.log(t('No credentials read from tool files. No network or inference check performed.', 'Không đọc thông tin đăng nhập từ tệp công cụ. Không kiểm tra mạng hoặc gọi mô hình.'))
     if (context.language !== 'vi') for (const hint of plan.hints || []) console.log(hint)
-    if (!bin || !process.env.ONEENDPOINT_API_KEY) process.exitCode = 1
+    if (!bin || !credential.key) process.exitCode = 1
     return
   }
   if (!bin) throw new Error('CLI not found on PATH. Install the tool from its official distribution first.')
-  const key = process.env.ONEENDPOINT_API_KEY
-  if (!key || /[\r\n\0]/.test(key)) throw new Error('Set a valid ONEENDPOINT_API_KEY in the environment. It is never saved.')
+  const key = credential.key
+  if (!key || /[\s\x00-\x1f\x7f-\x9f]/.test(key)) throw new Error(t('Add an API key through the interactive menu or set ONEENDPOINT_API_KEY.', 'Thêm khóa API qua menu hoặc đặt ONEENDPOINT_API_KEY.'))
+  if (context.apiKey && context.saveKey) await saveCredential({ stateDir, tool, key })
   let launch
   try { launch = (tool === 'dsh' ? launchDsh : launchClaude)({ stateDir, model: state.model, roleModels: state.roles, args: forwarded, profile: options['--profile'] || 'web' }) }
   catch { throw new Error('Unsupported tool arguments: routing, agent/plugin and permission-bypass overrides are not allowed.') }

package/src/credentials.mjs

@@ -0,0 +1,158 @@
+import fs from 'node:fs/promises'
+import { constants } from 'node:fs'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { assertSafePath, validateTool } from './state.mjs'
+
+// Opt-in local storage is plaintext, NOT encryption. Credentials are kept only in
+// credentials/<tool>.json (0600), inside credentials/ (0700), never manifests or
+// backups. Atomic replacement leaves the previous credential intact on failure.
+const failure = () => new Error('Unable to access a safe credential store. Check ownership, permissions, and saved credential format.')
+const invalidKey = () => new Error('Provide a valid API key token without whitespace or control characters.')
+const MAX_BYTES = 16384
+const posix = process.platform !== 'win32'
+
+function token(key) {
+  if (typeof key !== 'string' || !key.length || key.length > 8192 || /[\s\p{Cc}\p{Cf}]/u.test(key)) throw invalidKey()
+  return key
+}
+function locations(stateDir, tool) {
+  validateTool(tool)
+  if (typeof stateDir !== 'string' || !stateDir.length) throw failure()
+  const root = path.resolve(stateDir)
+  return { root, dir: path.join(root, 'credentials'), file: path.join(root, 'credentials', `${tool}.json`), lock: path.join(root, '.setup.lock') }
+}
+function owned(stat) {
+  if (posix && typeof process.getuid === 'function' && stat.uid !== process.getuid()) throw failure()
+}
+function privateFile(stat) {
+  owned(stat)
+  if (!stat.isFile() || stat.nlink !== 1 || (posix && (stat.mode & 0o7777) !== 0o600) || stat.size > MAX_BYTES) throw failure()
+}
+async function optionalStat(file) {
+  try { return await fs.lstat(file) } catch (error) { if (error.code === 'ENOENT') return null; throw error }
+}
+async function inspect(paths) {
+  await assertSafePath(paths.file)
+  const root = await optionalStat(paths.root)
+  if (root) {
+    owned(root)
+    if (!root.isDirectory() || (posix && (root.mode & 0o022))) throw failure()
+  }
+  const dir = await optionalStat(paths.dir)
+  if (dir) {
+    owned(dir)
+    if (!dir.isDirectory() || (posix && (dir.mode & 0o7777) !== 0o700)) throw failure()
+  }
+  const stat = await optionalStat(paths.file)
+  if (stat) privateFile(stat)
+  return stat
+}
+function sameFile(a, b) { return a.dev === b.dev && a.ino === b.ino }
+async function readSaved(paths, tool) {
+  const stat = await inspect(paths)
+  if (!stat) return null
+  const handle = await fs.open(paths.file, constants.O_RDONLY | (constants.O_NOFOLLOW || 0))
+  try {
+    const opened = await handle.stat()
+    privateFile(opened)
+    if (!sameFile(stat, opened)) throw failure()
+    const raw = await handle.readFile('utf8')
+    const after = await handle.stat()
+    privateFile(after)
+    if (Buffer.byteLength(raw) > MAX_BYTES || !sameFile(opened, after)) throw failure()
+    const current = await inspect(paths)
+    if (!current || !sameFile(opened, current)) throw failure()
+    const saved = JSON.parse(raw)
+    if (!saved || typeof saved !== 'object' || Array.isArray(saved) || Object.keys(saved).sort().join(',') !== 'key,tool,version' || saved.version !== 1 || saved.tool !== tool) throw failure()
+    return token(saved.key)
+  } finally { await handle.close() }
+}
+
+export async function getCredential({ stateDir, tool, env = process.env }) {
+  validateTool(tool)
+  const key = env.ONEENDPOINT_API_KEY
+  // An invalid nonempty environment token must not silently fall back to disk.
+  if (key !== undefined && key !== '') return { key: token(key), source: 'environment' }
+  try {
+    const saved = await readSaved(locations(stateDir, tool), tool)
+    return saved === null ? { key: undefined, source: 'missing' } : { key: saved, source: 'saved' }
+  } catch { throw failure() }
+}
+
+export async function credentialExists({ stateDir, tool }) {
+  return (await getCredential({ stateDir, tool, env: {} })).source === 'saved'
+}
+
+async function withLock(paths, operation) {
+  await inspect(paths)
+  await fs.mkdir(paths.root, { recursive: true, mode: 0o700 })
+  await inspect(paths)
+  await assertSafePath(paths.lock)
+  let lock
+  try { lock = await fs.open(paths.lock, 'wx', 0o600) } catch (error) {
+    if (error.code === 'EEXIST') throw new Error('Another setup may be active. Review the helper lock before retrying.')
+    throw error
+  }
+  try { return await operation() } finally {
+    const held = await lock.stat()
+    await lock.close()
+    await assertSafePath(paths.lock)
+    const current = await optionalStat(paths.lock)
+    if (!current || !sameFile(held, current)) throw failure()
+    await fs.unlink(paths.lock)
+  }
+}
+
+export async function saveCredential({ stateDir, tool, key }) {
+  const paths = locations(stateDir, tool)
+  token(key)
+  try {
+    return await withLock(paths, async () => {
+      const previous = await readSaved(paths, tool)
+      if (previous === key) return { changed: false }
+      await fs.mkdir(paths.dir, { mode: 0o700, recursive: true })
+      await inspect(paths)
+      const temp = path.join(paths.dir, `.${tool}-${randomUUID()}.tmp`)
+      let handle
+      try {
+        handle = await fs.open(temp, 'wx', 0o600)
+        await handle.chmod(0o600)
+        await handle.writeFile(JSON.stringify({ version: 1, tool, key }) + '\n', 'utf8')
+        await handle.sync()
+        await handle.close()
+        handle = null
+        // The only commit is rename: all fallible preparation happens first.
+        await inspect(paths)
+        await assertSafePath(temp)
+        privateFile(await fs.lstat(temp))
+        await fs.rename(temp, paths.file)
+        return { changed: true }
+      } finally {
+        if (handle) await handle.close()
+        await fs.unlink(temp).catch(error => { if (error.code !== 'ENOENT') throw error })
+      }
+    })
+  } catch (error) {
+    if (error.message === 'Another setup may be active. Review the helper lock before retrying.') throw error
+    throw failure()
+  }
+}
+
+export async function removeCredential({ stateDir, tool, dryRun = false }) {
+  const paths = locations(stateDir, tool)
+  try {
+    const present = await inspect(paths)
+    if (dryRun || !present) return { changed: false, dryRun }
+    return await withLock(paths, async () => {
+      const current = await inspect(paths)
+      if (!current) return { changed: false, dryRun: false }
+      // Fixed validated path only; malformed JSON can be safely removed too.
+      await fs.unlink(paths.file)
+      return { changed: true, dryRun: false }
+    })
+  } catch (error) {
+    if (error.message === 'Another setup may be active. Review the helper lock before retrying.') throw error
+    throw failure()
+  }
+}

package/src/ui.mjs

@@ -1,5 +1,6 @@
 import { createInterface } from 'node:readline/promises'
 import { fetchModels } from './catalog.mjs'
+import { openConsole } from './browser.mjs'
 import * as claudeAdapter from './adapters/claude.mjs'
 
 const palette = { heading: 36, info: 34, success: 32, warning: 33, error: 31, muted: 90, selected: 35 }
@@ -31,12 +32,19 @@ export async function select({ message, choices, input = process.stdin, output =
   const wasPaused = typeof input.isPaused === 'function' && input.isPaused()
   let index = 0, rendered = false, buffer = '', timer, settled = false
   const pageSize = Math.min(choices.length, 8, Math.max(1, (output.rows || 24) - 4))
-  const lines = pageSize + 2
-  // Conservative cell budget also prevents wrapping wide Unicode labels.
-  const fit = text => {
-    const chars = Array.from(clean(text))
-    const limit = Math.max(8, Math.floor((output.columns || 120) / 2) - 1)
-    return chars.length > limit ? chars.slice(0, limit - 1).join('') + '…' : chars.join('')
+  let renderedLines = 0
+  const wrap = text => {
+    const width = Math.max(4, (output.columns || 120) - 1)
+    const lines = ['']
+    let cells = 0
+    for (const { segment } of new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(clean(text))) {
+      const cp = segment.codePointAt(0)
+      const size = /^\p{Mark}+$/u.test(segment) ? 0 : /\p{Extended_Pictographic}/u.test(segment) || cp >= 0x1100 && (cp <= 0x115f || cp >= 0x2e80 && cp <= 0xa4cf || cp >= 0xac00 && cp <= 0xd7a3 || cp >= 0xf900 && cp <= 0xfaff || cp >= 0xfe10 && cp <= 0xfe6f || cp >= 0xff01 && cp <= 0xff60 || cp >= 0x20000) ? 2 : 1
+      if (cells + size > width) { lines.push(''); cells = 0 }
+      lines[lines.length - 1] += segment
+      cells += size
+    }
+    return lines
   }
   return new Promise((resolve, reject) => {
     const cleanup = () => {
@@ -59,16 +67,24 @@ export async function select({ message, choices, input = process.stdin, output =
     }
     function onFailure() { finish(uiError()) }
     function draw() {
-      if (rendered) output.write(`\u001b[${lines}A\r`)
-      output.write('\u001b[2K' + colorize(fit(message), 'heading', { output }) + '\n')
+      if (rendered) output.write(`\u001b[${renderedLines}A\r\u001b[J`)
+      const rows = wrap(message).map(text => ({ text, kind: 'heading' }))
       const start = Math.min(Math.max(0, index - pageSize + 1), choices.length - pageSize)
-      choices.slice(start, start + pageSize).forEach((choice, offset) => {
-        const i = start + offset
-        const text = `${i === index ? '❯' : ' '} ${choice.label}${choice.description ? ` — ${choice.description}` : ''}`
-        output.write('\u001b[2K' + colorize(fit(text), i === index ? 'selected' : 'info', { output }) + '\n')
-      })
       const hint = language === 'vi' ? '↑/↓ chọn · Enter xác nhận · Esc hủy' : '↑/↓ select · Enter accept · Esc cancel'
-      output.write('\u001b[2K' + colorize(fit(`${index + 1}/${choices.length} · ${hint}`), 'muted', { output }) + '\n')
+      const footer = wrap(`${index + 1}/${choices.length} · ${hint}`)
+      let candidates = choices.slice(start, start + pageSize).map((choice, offset) => ({
+        i: start + offset,
+        lines: wrap(`${start + offset === index ? '❯' : ' '} ${choice.label}${choice.description ? ` — ${choice.description}` : ''}`)
+      }))
+      const budget = Math.max(1, (output.rows || 24) - rows.length - footer.length - 1)
+      while (candidates.length > 1 && candidates.reduce((n, c) => n + c.lines.length, 0) > budget) {
+        if (candidates[0].i < index) candidates.shift()
+        else candidates.pop()
+      }
+      for (const candidate of candidates) for (const text of candidate.lines) rows.push({ text, kind: candidate.i === index ? 'selected' : 'info' })
+      for (const text of footer) rows.push({ text, kind: 'muted' })
+      for (const { text, kind } of rows) output.write('\u001b[2K' + colorize(text, kind, { output }) + '\n')
+      renderedLines = rows.length
       rendered = true
     }
     function onData(chunk) {
@@ -114,6 +130,81 @@ export async function select({ message, choices, input = process.stdin, output =
   })
 }
 
+/** Masked single-token entry. Bracketed paste is buffered until its end marker. */
+export async function readApiKey({ input = process.stdin, output = process.stdout, language = 'en' } = {}) {
+  if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== 'function') throw uiError()
+  const wasRaw = Boolean(input.isRaw), wasPaused = input.isPaused?.()
+  let value = '', buffer = '', pasting = false, pasted = '', settled = false, timer
+  return new Promise((resolve, reject) => {
+    const finish = (error, result) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      for (const event of ['data', 'error', 'end', 'close']) input.off(event, event === 'data' ? onData : onFailure)
+      output.off('error', onFailure)
+      try { input.setRawMode(wasRaw) } catch {}
+      try { if (wasPaused) input.pause() } catch {}
+      try { output.write('\u001b[?2004l\n') } catch {}
+      value = ''; pasted = ''; buffer = ''
+      if (error) reject(error)
+      else resolve(result)
+    }
+    const invalid = () => {
+      const error = new Error(language === 'vi' ? 'Khóa API phải là một chuỗi duy nhất, không có khoảng trắng hoặc ký tự điều khiển.' : 'API key must be a single token without whitespace or control characters.')
+      error.code = 'UI_INVALID_KEY'
+      finish(error)
+    }
+    const valid = text => /^[\x21-\x7e]+$/.test(text) && text.length <= 8192
+    function onFailure() { finish(uiError()) }
+    function onData(chunk) {
+      try {
+        clearTimeout(timer)
+        buffer += chunk.toString('utf8')
+        while (buffer && !settled) {
+          if (pasting) {
+            const end = buffer.indexOf('\u001b[201~')
+            if (end < 0) {
+              // Retain a possible split terminator; no pasted byte is interpreted as a key.
+              if (buffer.length > 6) { pasted += buffer.slice(0, -6); buffer = buffer.slice(-6) }
+              if (pasted.length > 8192) return invalid()
+              return
+            }
+            pasted += buffer.slice(0, end)
+            buffer = buffer.slice(end + 6)
+            if (!valid(pasted) || value.length + pasted.length > 8192) return invalid()
+            value += pasted; output.write('*'.repeat(pasted.length)); pasted = ''; pasting = false
+            continue
+          }
+          if (buffer.startsWith('\u001b[200~')) { buffer = buffer.slice(6); pasting = true; continue }
+          if ('\u001b[200~'.startsWith(buffer) && buffer[0] === '\u001b') {
+            timer = setTimeout(() => finish(uiError(true)), 35); return
+          }
+          const char = buffer[0]; buffer = buffer.slice(1)
+          if (char === '\u0003' || char === '\u001b') return finish(uiError(true))
+          if (char === '\r' || char === '\n') {
+            if (!valid(value) || buffer.length) return invalid()
+            return finish(null, value)
+          }
+          if (char === '\x7f' || char === '\b') {
+            if (value) { value = value.slice(0, -1); output.write('\b \b') }
+            continue
+          }
+          if (!valid(char) || value.length >= 8192) return invalid()
+          value += char; output.write('*')
+        }
+      } catch { finish(uiError()) }
+    }
+    try {
+      input.on('data', onData)
+      for (const event of ['error', 'end', 'close']) input.on(event, onFailure)
+      output.on('error', onFailure)
+      input.setRawMode(true)
+      output.write('\u001b[?2004h' + (language === 'vi' ? 'Dán khóa API (ẩn): ' : 'Paste API key (masked): '))
+      input.resume()
+    } catch { finish(uiError()) }
+  })
+}
+
 async function modelQuestion(input, output, language = 'en') {
   const controller = new AbortController()
   const terminal = createInterface({ input, output, terminal: true })
@@ -139,7 +230,7 @@ async function modelQuestion(input, output, language = 'en') {
 }
 
 /** Gather CLI arguments only. State and tool execution belong to dispatch. */
-export async function wizard({ dispatch, input = process.stdin, output = process.stdout, loadModels = fetchModels }) {
+export async function wizard({ dispatch, input = process.stdin, output = process.stdout, loadModels = fetchModels, getKeyStatus = async () => ({ available: false }), openConsole: openBrowser = openConsole }) {
   if (typeof dispatch !== 'function') throw new Error('Wizard requires a CLI dispatcher.')
   let language = 'en'
   const t = (en, vi) => language === 'vi' ? vi : en
@@ -152,7 +243,7 @@ export async function wizard({ dispatch, input = process.stdin, output = process
     language = await choose('Language / Ngôn ngữ', [
       { label: 'English', value: 'en' }, { label: 'Tiếng Việt', value: 'vi' }
     ])
-    const action = await choose(t('1endpoint coding-helper · isolated configuration; no API key is requested or saved', '1endpoint coding-helper · cấu hình riêng; không yêu cầu hoặc lưu khóa API'), [
+    const action = await choose(t('1endpoint coding-helper · isolated configuration', '1endpoint coding-helper · cấu hình riêng'), [
       { label: t('Setup', 'Cấu hình'), value: 'setup' },
       { label: t('Reconfigure', 'Cấu hình lại'), value: 'reconfigure' },
       { label: t('Remove', 'Xóa cấu hình'), value: 'remove' },
@@ -165,6 +256,44 @@ export async function wizard({ dispatch, input = process.stdin, output = process
       { label: 'DSH', value: 'dsh' }, { label: 'Claude Code', value: 'claude' }
     ])
     const argv = [action, '--tool', tool]
+    const context = { language }
+    if (['setup', 'reconfigure', 'run'].includes(action)) {
+      let available = false
+      try { available = (await getKeyStatus({ tool }))?.available === true } catch {}
+      if (action !== 'run' || !available) {
+        while (true) {
+          const keyAction = await choose(t('API key', 'Khóa API'), [
+            { label: t('Paste key (masked)', 'Dán khóa (ẩn)'), value: 'paste' },
+            { label: t('Open Console create API key', 'Mở Console tạo khóa API'), value: 'open', description: t('Enter opens the API keys page', 'Enter mở trang khóa API') },
+            ...(available ? [{ label: t('Use existing saved/environment key', 'Dùng khóa đã lưu hoặc biến môi trường'), value: 'existing' }] : []),
+            { label: t('Skip; use environment key later', 'Bỏ qua; dùng khóa môi trường sau'), value: 'skip' },
+            { label: t('Cancel', 'Hủy'), value: 'cancel' }
+          ])
+          if (keyAction === 'cancel') return
+          if (keyAction === 'existing' || keyAction === 'skip') break
+          if (keyAction === 'open') {
+            try { await openBrowser({ language }) }
+            catch { output.write(t('Could not open Console. Select Open Console to retry, or paste a key.\n', 'Không mở được Console. Chọn Mở Console để thử lại hoặc dán khóa.\n')) }
+            continue
+          }
+          let key
+          try { key = await readApiKey({ input, output, language }) }
+          catch (error) {
+            if (error.code !== 'UI_INVALID_KEY') throw error
+            output.write(error.message + '\n'); continue
+          }
+          output.write(t('Local keys are plaintext, mode 0600: accessible to your user account, not encrypted.\n', 'Khóa cục bộ ở dạng văn bản thuần, quyền 0600: tài khoản của bạn có thể đọc, không được mã hóa.\n'))
+          const storage = await choose(t('Key storage', 'Lưu khóa'), [
+            { label: t('Save locally', 'Lưu cục bộ'), value: 'save' },
+            { label: t('This run only', 'Chỉ lần chạy này'), value: 'session' },
+            { label: t('Cancel', 'Hủy'), value: 'cancel' }
+          ])
+          if (storage === 'cancel') return
+          context.apiKey = key; context.saveKey = storage === 'save'
+          break
+        }
+      }
+    }
     if (action === 'setup' || action === 'reconfigure') {
       let models, manual = false
       while (!models && !manual) {
@@ -192,7 +321,7 @@ export async function wizard({ dispatch, input = process.stdin, output = process
         const optionalRoles = claudeAdapter.CLAUDE_OPTIONAL_ROLES || []
         let activeRoles = [...roles]
         if (optionalRoles.length) {
-          const extra = await choose(t('Claude tier support depends on your installed version; no version is guessed.', 'Các cấp Claude tùy thuộc phiên bản đã cài; không tự suy đoán phiên bản.'), [
+          const extra = await choose(t('Select the tiers supported by your Claude Code version.', 'Chọn các cấp được phiên bản Claude Code của bạn hỗ trợ.'), [
             { label: t('Standard Haiku / Sonnet / Opus', 'Các cấp chuẩn Haiku / Sonnet / Opus'), value: false },
             { label: t('Include optional tiers', 'Thêm cấp tùy chọn'), value: true, description: t('Only if your installed Claude supports ', 'Chỉ chọn nếu Claude đã cài hỗ trợ ') + optionalRoles.map(role => role.label).join(', ') }
           ])
@@ -224,16 +353,28 @@ export async function wizard({ dispatch, input = process.stdin, output = process
       ])
       if (mode === 'cancel') return
       if (mode === 'force') output.write(colorize(t('WARNING: Force recovery deletes fixed helper configuration paths, including modified contents, without backup.\n', 'CẢNH BÁO: xóa cưỡng chế xóa các đường dẫn cấu hình riêng cố định, kể cả nội dung đã sửa, không sao lưu.\n'), 'warning', { output }))
+      context.removeKey = await choose(t('Saved key for this tool', 'Khóa đã lưu cho công cụ này'), [
+        { label: t('Keep saved key', 'Giữ khóa đã lưu'), value: false },
+        { label: t('Remove saved key too', 'Xóa cả khóa đã lưu'), value: true }
+      ])
       if (!await confirm(mode === 'force' ? t('Confirm forced recovery deletion without backup?', 'Xác nhận xóa cưỡng chế không sao lưu?') : t('Confirm removal of helper-owned configuration?', 'Xác nhận xóa cấu hình riêng?'))) return
       argv.push('--yes')
       if (mode === 'force') argv.push('--force')
     }
-    const result = await dispatch(argv, { language })
+    const result = await dispatch(argv, context)
     if (action === 'setup' || action === 'reconfigure') {
       const warning = t(`Restart your ${tool === 'dsh' ? 'DSH' : 'Claude Code'} session to apply. Existing sessions do not update automatically. Start a new session through coding-helper.\n`, `Khởi động lại phiên ${tool === 'dsh' ? 'DSH' : 'Claude Code'} để áp dụng. Phiên hiện có không tự cập nhật. Mở phiên mới thông qua coding-helper.\n`)
       const colored = colorize(warning, 'warning', { output })
       output.write(colored === warning ? warning : `\u001b[1m${colored}\u001b[0m`)
     }
+    if ((action === 'setup' || action === 'reconfigure') && context.apiKey && !context.saveKey) {
+      output.write(t('This key is only available now. Paste it again when reopening coding-helper.\n', 'Khóa chỉ có trong lần chạy này. Dán lại khi mở coding-helper lần sau.\n'))
+      const launch = await choose(t('Start a new session?', 'Mở phiên mới?'), [
+        { label: t('Finish', 'Hoàn tất'), value: false },
+        { label: t('Start new session now (may incur charges)', 'Mở phiên mới ngay (có thể phát sinh phí)'), value: true }
+      ])
+      if (launch) return dispatch(['run', '--tool', tool], { language, apiKey: context.apiKey, saveKey: false })
+    }
     return result
   } catch (error) {
     if (error.code === 'UI_CANCELLED') {