@1endpoint/coding-helper 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1endpoint contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# @1endpoint/coding-helper
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Safe, isolated setup for **DeepSeek Harness** and **Claude Code CLI** using the single 1endpoint API base URL:
+
+```text
+https://1endpoint.dev/api/v1
+```
+
+**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.
+
+## Requirements
+
+- 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.
+
+## Setup
+
+After publication:
+
+```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
+```
+
+Before publication, from the repository:
+
+```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
+```
+
+**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.**
+
+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.
+
+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.
+
+## Diagnose and launch
+
+After setting the key in your process environment:
+
+```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'
+```
+
+For npx-only use, replace `coding-helper` with `npx @1endpoint/coding-helper`. For local use, replace it with `node src/cli.mjs`.
+
+`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.
+
+### DeepSeek Harness
+
+- 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.
+
+### Claude Code CLI
+
+- 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.
+
+## Update, backup and recovery
+
+```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
+```
+
+`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.
+
+`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.
+
+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.
+
+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.
+
+## Development and packaging
+
+```bash
+yarn install --immutable
+yarn check
+yarn test
+yarn pack --out ../coding-helper-0.1.0.tgz
+```
+
+No production dependencies and no build step. The published entry is native ESM. Package contents are allowlisted. See [release checklist](docs/RELEASE.md) for current verification boundaries and publishing steps. Publishing is a separate maintainer action; creating or pushing the repository does not publish npm.
+
+## Reference and attribution
+
+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.
+
+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).
+
+## Tiếng Việt
+
+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.

package/docs/RELEASE.md

@@ -0,0 +1,45 @@
+# Release and verification gate
+
+## Scope
+
+Initial package: `@1endpoint/coding-helper@0.1.0`, public npm access. Independent repository: `dothinh115/1endpoint-coding-helper`. First Git commit: `first push`. **Git push does not authorize npm publication.** Maintainer publishes after reviewing the handoff.
+
+## Architecture and support plan
+
+1. First release prioritizes native DeepSeek Harness and Claude Code CLI connection contracts, isolated homes, environment-only credentials, language-first EN/VI colored arrow menus, fetched public text-model choices, independent per-tier model mappings, prominent session-restart instructions, local diagnostics, automatic-backup reconfiguration and command-managed configuration removal/recovery.
+2. Keep original tool settings untouched. Do not migrate plugins, sessions, permissions, hooks or credentials implicitly. Native coding tools remain owners of agent execution.
+3. Extend tools through separate declarative adapters returning generated files, command/argv, child environment and safety hints. New adapters require isolated tests and actual installed-client contract checks.
+4. Future features (automatic version-specific tier discovery, user-selected integration of existing project settings, remote credential validation, optional paid inference smoke) require separate opt-in and independent security tests. Do not represent local doctor checks as network authentication checks.
+5. Broaden compatibility by testing pinned newer tool versions and operating systems before widening support claims. No automatic self-update, tool installation, permission bypass or runtime proxy is part of 0.1.0.
+
+## Required local checks
+
+```bash
+yarn install --immutable
+yarn check
+yarn test
+yarn pack --out /absolute/reviewed/output/coding-helper-0.1.0.tgz
+```
+
+Check the tarball allowlist, entry executable bit, no secrets/dev artifacts, package version/help, local `yarn dlx` invocation from the packed tarball, and a setup/doctor cycle with an isolated home. Avoid running the unpublished package name against the registry as a test.
+
+Configuration tests use fake keys and temporary isolated homes. Installed DSH checks parse real composed configuration and headless schema without a provider call. Installed Claude tests may use a loopback synthetic Messages server only; that proves client wire shape, not production gateway authentication or billing. Native Web schema has an upstream preset/tree-carrier diagnostic limitation separate from provider setup.
+
+Console checks: focused coding-helper documentation regressions, scoped ESLint, typecheck, production build (including EN/VI message compilation), whitespace and vendor-byte integrity checks. Browser/mobile verification and production deployment remain separate boundaries.
+
+## Before npm publication
+
+- Confirm repository source, initial commit and remote branch match reviewed package files.
+- Confirm no release blocker in test output or security review, and inspect tarball.
+- Verify the npm account has publish rights for scope `@1endpoint` and satisfies npm 2FA/trusted-publishing requirements. Never copy npm credentials into repository or chat.
+- Re-run the checks above from the committed source.
+- Maintainer may publish with Yarn's npm publish command, public access, and the desired release tag. This task deliberately does not run it.
+- After publication verify registry version, integrity, bin mapping and real `npx @1endpoint/coding-helper --version` from a fresh environment. Only then remove the Console/docs unpublished warning, commit/deploy the Console update through its normal pipeline, and announce availability.
+
+## Verification record
+
+Local verification on 2026-10-15: 52/52 tests pass with the explicit installed-Claude fixture enabled; no skips/failures. This includes DSH 0.2.1-alpha.3 native composition/headless schema and Claude Code 2.1.294 loopback Messages request/response (exact `/api/v1/v1/messages?beta=true`, raw dummy key becomes Bearer, selected model retained). The ordinary suite skips the opt-in installed-Claude fixture. Public anonymous catalog smoke returns 22 text models; this is not credential or paid-inference validation. Console has 7/7 focused regressions plus scoped lint/typecheck/production build passing.
+
+Final Yarn tarball contains only LICENSE, README, release guide, package metadata and six source modules; entry executable bit is present. Local tarball `yarn dlx` version/help and setup → independent tier mapping → reconfigure/automatic backup → remove preview/confirmation pass. Source tests additionally cover language-first EN/VI, scrolling arrow menus, no y/n, explicit recovery, restart messaging, private writes, integrity, symlinks, fake launch environments and secret nonpersistence.
+
+macOS local testing does not establish Windows/Linux E2E compatibility. Optional Fable selection is explicit based on operator-known installed-version support; automatic version-specific tier discovery remains future work. Actual paid gateway inference, browser/mobile QA, frontend deployment and npm publication are not performed. Native Web schema dumping retains its upstream preset diagnostic limitation. Same-user malicious filesystem races are not a supported security boundary; this is not an OS sandbox.

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@1endpoint/coding-helper",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Safe isolated 1endpoint setup for DeepSeek Harness and Claude Code CLI",
+  "type": "module",
+  "bin": {
+    "1endpoint-helper": "src/cli.mjs",
+    "coding-helper": "src/cli.mjs"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "packageManager": "yarn@4.17.0",
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check src/cli.mjs",
+    "prepack": "yarn check && yarn test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dothinh115/1endpoint-coding-helper.git"
+  },
+  "homepage": "https://console.1endpoint.dev/docs/guides/coding-tools",
+  "bugs": {
+    "url": "https://github.com/dothinh115/1endpoint-coding-helper/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "1endpoint",
+    "deepseek",
+    "harness",
+    "claude-code",
+    "cli",
+    "setup"
+  ]
 }

package/src/adapters/claude.mjs

@@ -0,0 +1,43 @@
+import path from 'node:path'
+
+export const MODEL_VARIABLES = ['ANTHROPIC_MODEL', 'ANTHROPIC_DEFAULT_OPUS_MODEL', 'ANTHROPIC_DEFAULT_SONNET_MODEL', 'ANTHROPIC_DEFAULT_HAIKU_MODEL', 'ANTHROPIC_DEFAULT_FABLE_MODEL', 'CLAUDE_CODE_SUBAGENT_MODEL']
+export const CLAUDE_ROLES = [{ id: 'haiku', label: 'Haiku' }, { id: 'sonnet', label: 'Sonnet' }, { id: 'opus', label: 'Opus' }]
+export const CLAUDE_OPTIONAL_ROLES = [{ id: 'fable', label: 'Fable' }]
+export function createClaudePlan({ stateDir, model, roleModels }) {
+  const directory = path.resolve(stateDir, 'claude')
+  const settings = { model, env: Object.fromEntries(MODEL_VARIABLES.map(name => [name, model])) }
+  if (roleModels) {
+    settings.model = roleModels.sonnet || model
+    settings.env.ANTHROPIC_MODEL = roleModels.sonnet || model
+    settings.env.ANTHROPIC_DEFAULT_HAIKU_MODEL = roleModels.haiku || model
+    settings.env.ANTHROPIC_DEFAULT_SONNET_MODEL = roleModels.sonnet || model
+    settings.env.ANTHROPIC_DEFAULT_OPUS_MODEL = roleModels.opus || model
+    settings.env.ANTHROPIC_DEFAULT_FABLE_MODEL = roleModels.fable || roleModels.opus || model
+    settings.env.CLAUDE_CODE_SUBAGENT_MODEL = roleModels.sonnet || model
+  }
+  settings.env.ANTHROPIC_BASE_URL = 'https://1endpoint.dev/api/v1'
+  return {
+    files: [{ path: path.join(directory, 'settings.json'), content: JSON.stringify(settings, null, 2) + '\n' }],
+    command: 'claude',
+    args: ['--setting-sources', 'user', '--settings', path.join(directory, 'settings.json')],
+    env: { CLAUDE_CONFIG_DIR: path.join(directory, 'home'), ...settings.env },
+    hints: ['Project/local settings, permissions and hooks are intentionally excluded. Managed policy still applies.', 'Normal tool permission and workspace trust prompts remain enabled.'],
+  }
+}
+export function launchClaude({ stateDir, model, roleModels, args = [] }) {
+  // Do not allow forwarded flags to silently replace the routing/isolation contract.
+  if (!Array.isArray(args) || args.some(arg => typeof arg !== 'string' || arg.includes('\0'))) throw new Error('Tool arguments must be strings without NUL characters.')
+  const blocked = /^(?:--(?:settings|setting-sources|model|fallback-model|agent|agents|plugin-dir|bare|dangerously-skip-permissions|allow-dangerously-skip-permissions|permission-mode)(?:=|$)|-m)/
+  if (args.some(arg => blocked.test(arg))) throw new Error('Routing, agent and permission-bypass overrides are not supported by the isolated launcher.')
+  return { ...createClaudePlan({ stateDir, model, roleModels }), args: [...createClaudePlan({ stateDir, model, roleModels }).args, ...args] }
+}
+export function childEnvironment(env, plan, key) {
+  const result = { ...env }
+  for (const name of Object.keys(result)) {
+    if (/^(?:ANTHROPIC_|CLAUDE_|DSH_)/.test(name) || /^(?:NODE_OPTIONS|NODE_PATH|BASH_ENV|ENV|LD_PRELOAD|LD_LIBRARY_PATH|DYLD_.*)$/.test(name)) delete result[name]
+  }
+  Object.assign(result, plan.env)
+  if (plan.command === 'claude') result.ANTHROPIC_AUTH_TOKEN = key
+  result.ONEENDPOINT_API_KEY = key
+  return result
+}

package/src/adapters/dsh.mjs

@@ -0,0 +1,75 @@
+import { resolve, join } from 'node:path';
+
+const PROFILES = new Set(['web', 'headless', 'acp', 'sdk']);
+const ROUTING_FLAGS = new Set([
+  '--patch', '--profile', '--from-default-profile', '--dump-default-config',
+  '--config', '--config-file', '--home', '--dsh-home',
+  '--provider', '--model', '--api-key', '--api-key-env', '--base-url', '--baseURL',
+]);
+
+function nonemptyString(value, name) {
+  if (typeof value !== 'string' || !value.trim() || value.includes('\0')) {
+    throw new TypeError(`${name} must be a non-empty string without NUL characters`);
+  }
+}
+
+/** Build an isolated, declarative DSH configuration; never reads or writes secrets. */
+export function createDshPlan({ stateDir, model } = {}) {
+  return launchDsh({ stateDir, model });
+}
+
+/** Return files and a launch specification; the caller materializes and executes it. */
+export function launchDsh({ stateDir, model, args = [], profile = 'web' } = {}) {
+  nonemptyString(stateDir, 'stateDir');
+  nonemptyString(model, 'model');
+  if (!PROFILES.has(profile)) {
+    throw new TypeError(`Unsupported DSH profile: ${String(profile)}; use web, headless, acp, or sdk`);
+  }
+  if (!Array.isArray(args) || args.some((arg) => typeof arg !== 'string' || arg.includes('\0'))) {
+    throw new TypeError('args must be an array of strings without NUL characters');
+  }
+  for (const arg of args) {
+    // Commander permits unambiguous long-option abbreviations; reject those too.
+    const flag = arg.split('=', 1)[0];
+    if (flag.startsWith('--') && flag.length > 2
+      && [...ROUTING_FLAGS].some((blocked) => blocked.startsWith(flag))) {
+      throw new TypeError(`DSH routing override argument is not allowed: ${flag}`);
+    }
+  }
+  const directory = resolve(stateDir, 'dsh');
+  const home = join(directory, 'home');
+  const overlay = join(directory, '1endpoint.patch.yml');
+  const patches = [
+    {
+      id: 'llm-pi-ai',
+      name: '@deepseek-ai/dsh-llm-pi-ai',
+      config: {
+        providers: {
+          '1endpoint': {
+            displayName: '1endpoint',
+            api: 'openai-completions',
+            baseURL: 'https://1endpoint.dev/api/v1',
+            apiKeyEnv: 'ONEENDPOINT_API_KEY',
+            models: [{ id: model }],
+          },
+        },
+      },
+    },
+    {
+      id: 'agent-default-model',
+      name: '@deepseek-ai/dsh-agent-default-model',
+      config: { provider: '1endpoint', model },
+    },
+  ];
+  return {
+    files: [{ path: overlay, content: `${JSON.stringify(patches, null, 2)}\n` }],
+    command: 'dsh',
+    args: ['--profile', profile, '--patch', overlay, ...args],
+    env: { DSH_HOME: home },
+    hints: [
+      'Set ONEENDPOINT_API_KEY in the child process environment; the key is never stored in the overlay.',
+      'DSH runs in an isolated home: existing user configuration is not read or merged. Patch config objects replace the entire entry config.',
+      'The sdk-minimal profile is unsupported because it lacks the provider and default-model plugin entries.',
+    ],
+  };
+}

package/src/catalog.mjs

@@ -0,0 +1,53 @@
+export const CATALOG_URL = 'https://1endpoint.dev/api/v1/models'
+const MAX_BYTES = 2 * 1024 * 1024
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:/+-]{0,199}$/
+export function decodeModels(payload) {
+  if (!payload || !Array.isArray(payload.data)) throw new Error('Model catalog has an invalid shape.')
+  const models = new Map()
+  for (const item of payload.data) {
+    if (!item || typeof item !== 'object' || typeof item.id !== 'string' || !SAFE_ID.test(item.id)) continue
+    if (item.type && item.type !== 'text') continue
+    if (item.modelType && item.modelType !== 'text') continue
+    const name = typeof item.name === 'string' ? item.name : typeof item.display_name === 'string' ? item.display_name : item.id
+    models.set(item.id, { id: item.id, name: name.replace(/[\x00-\x1f\x7f-\x9f]/g, '').slice(0, 200) })
+  }
+  if (!models.size) throw new Error('No compatible text models were returned by the catalog.')
+  return [...models.values()].sort((a, b) => a.name.localeCompare(b.name) || a.id.localeCompare(b.id))
+}
+export async function fetchModels({ signal, fetchImpl = globalThis.fetch } = {}) {
+  const timeout = AbortSignal.timeout(10000)
+  const combined = signal ? AbortSignal.any([signal, timeout]) : timeout
+  let response
+  try {
+    // Public catalog only: never transmit user keys, cookies or inherited auth headers.
+    response = await fetchImpl(CATALOG_URL, { signal: combined, redirect: 'error', headers: { accept: 'application/json' }, credentials: 'omit' })
+    if (!response.ok) throw new Error('catalog_status')
+    if (!/application\/json/i.test(response.headers.get('content-type') || '')) throw new Error('catalog_type')
+    if (Number(response.headers.get('content-length')) > MAX_BYTES) throw new Error('catalog_size')
+    if (!response.body) throw new Error('catalog_empty')
+    const reader = response.body.getReader()
+    const chunks = []
+    let size = 0
+    const aborted = () => { void reader.cancel().catch(() => {}) }
+    combined.addEventListener('abort', aborted, { once: true })
+    try {
+      while (true) {
+        combined.throwIfAborted()
+        const { done, value } = await reader.read()
+        if (done) break
+        size += value.byteLength
+        if (size > MAX_BYTES) throw new Error('catalog_size')
+        chunks.push(value)
+      }
+      combined.throwIfAborted()
+      return decodeModels(JSON.parse(Buffer.concat(chunks).toString('utf8')))
+    } finally {
+      combined.removeEventListener('abort', aborted)
+      void reader.cancel().catch(() => {})
+      reader.releaseLock()
+    }
+  } catch {
+    if (response?.body && !response.body.locked) void response.body.cancel().catch(() => {})
+    throw new Error('Could not load the public 1endpoint model catalog. Retry or explicitly choose manual model ID entry.')
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+import path from 'node:path'
+import fs from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { spawn } from 'node:child_process'
+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'
+
+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 doctor --tool dsh|claude
+  coding-helper run --tool dsh|claude [--profile web|headless|acp|sdk] -- [tool args]
+  coding-helper backup --tool dsh|claude
+  coding-helper --help | --version
+
+No arguments starts English/Tiếng Việt selection, then colored arrow-key action menus.
+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.
+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.
+Run is explicit opt-in to tool startup and potentially billed requests. Normal permission prompts remain.
+--update changes an existing helper-owned model only after hash validation; back up first.
+`
+function parse(argv) {
+  const args = [...argv]
+  const command = args.shift()
+  const options = {}, forwarded = []
+  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 (!['--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'] }
+  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.')
+  if (options['--profile'] && options['--tool'] !== 'dsh') throw new Error('--profile is only supported for DSH.')
+  if (options['--profile'] && !['web', 'headless', 'acp', 'sdk'].includes(options['--profile'])) throw new Error('Choose --profile web, headless, acp or sdk.')
+  return { command, options, forwarded }
+}
+async function executable(command, env) {
+  const extensions = process.platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : ['']
+  for (const directory of (env.PATH || '').split(path.delimiter)) {
+    if (!directory) continue
+    for (const suffix of extensions) {
+      const file = path.resolve(directory, command + suffix)
+      try { const stat = await fs.stat(file); if (stat.isFile()) { await fs.access(file, process.platform === 'win32' ? 0 : 1); return file } } catch {}
+    }
+  }
+  return null
+}
+async function main(argv, context = {}) {
+  if (!argv.length) return wizard({ dispatch: main })
+  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'))
+    console.log(metadata.version); return
+  }
+  const { command, options, forwarded } = parse(argv)
+  const t = (en, vi) => context.language === 'vi' ? vi : en
+  const tool = options['--tool'], stateDir = stateRoot()
+  if (command === 'remove') {
+    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 (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.'))
+    return
+  }
+  if (command === 'setup' || command === 'reconfigure') {
+    const selectedRoles = Object.fromEntries(['haiku', 'sonnet', 'opus', 'fable'].filter(role => options[`--${role}-model`]).map(role => [role, options[`--${role}-model`]]))
+    const result = await (command === 'reconfigure' ? reconfigure : setup)({ stateDir, tool, model: options['--model'] || selectedRoles.sonnet, roles: Object.keys(selectedRoles).length ? selectedRoles : undefined, dryRun: options['--dry-run'], update: options['--update'] })
+    console.log(`${result.dryRun ? t('Preview only', 'Chỉ xem trước') : result.changed ? t('Configured', 'Đã cấu hình') : t('Already configured', 'Cấu hình không thay đổi')}: ${tool}`)
+    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.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 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('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
+    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.')
+  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.') }
+  await assertSafePath(launch.env.DSH_HOME || launch.env.CLAUDE_CONFIG_DIR)
+  await fs.mkdir(launch.env.DSH_HOME || launch.env.CLAUDE_CONFIG_DIR, { recursive: true, mode: 0o700 })
+  const child = spawn(bin, launch.args, { stdio: 'inherit', env: childEnvironment(process.env, launch, key), shell: false })
+  const signals = ['SIGINT', 'SIGTERM']
+  const handlers = signals.map(signal => { const handler = () => child.kill(signal); process.on(signal, handler); return [signal, handler] })
+  await new Promise((resolve, reject) => {
+    child.once('error', () => reject(new Error('Tool launch failed. Check the executable and local runtime.')))
+    child.once('close', (code, signal) => { process.exitCode = code ?? (signal === 'SIGINT' ? 130 : 143); resolve() })
+  }).finally(() => { for (const [signal, handler] of handlers) process.off(signal, handler) })
+}
+if (process.argv[1] && await fs.realpath(path.resolve(process.argv[1])).catch(() => '') === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2)).catch(error => {
+    // Never serialize raw parser, filesystem or child error details: these can contain private bytes.
+    const safe = error.code ? 'Local filesystem operation failed. Check helper state permissions and paths.' : error.message
+    console.error(colorize('coding-helper: ' + safe, 'error', { output: process.stderr }))
+    process.exitCode = 1
+  })
+}
+export { main, parse }

package/src/state.mjs

@@ -0,0 +1,172 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+import { createHash, randomUUID } from 'node:crypto'
+import { createClaudePlan } from './adapters/claude.mjs'
+import { createDshPlan } from './adapters/dsh.mjs'
+
+export const tools = ['dsh', 'claude']
+export function stateRoot(env = process.env) {
+  return path.resolve(env.ONEENDPOINT_HELPER_HOME || path.join(os.homedir(), '.1endpoint', 'coding-helper'))
+}
+export function validateTool(tool) {
+  if (!tools.includes(tool)) throw new Error('Choose --tool dsh or --tool claude.')
+  return tool
+}
+export function validateModel(model) {
+  if (typeof model !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:/+-]{0,199}$/.test(model)) throw new Error('Provide a public model ID using --model (letters, digits, dot, slash, colon, plus, underscore or hyphen).')
+  return model
+}
+export function planFor({ stateDir, tool, model, roles }) {
+  validateTool(tool); validateModel(model)
+  if (roles !== undefined) {
+    if (tool !== 'claude' || !roles || typeof roles !== 'object' || Array.isArray(roles) || Object.keys(roles).some(key => !['haiku', 'sonnet', 'opus', 'fable'].includes(key))) throw new Error('Invalid Claude model role mapping.')
+    for (const value of Object.values(roles)) validateModel(value)
+  }
+  return (tool === 'dsh' ? createDshPlan : createClaudePlan)({ stateDir, model, roleModels: roles })
+}
+export const digest = data => createHash('sha256').update(data).digest('hex')
+
+// Reject symlinks in every existing ancestor, including an overridden state root.
+export async function assertSafePath(target) {
+  const absolute = path.resolve(target)
+  const parts = absolute.split(path.sep).filter(Boolean)
+  let current = path.parse(absolute).root
+  for (const part of parts) {
+    current = path.join(current, part)
+    try {
+      const stat = await fs.lstat(current)
+      if (stat.isSymbolicLink()) throw new Error('Refusing a symbolic link in the helper state path.')
+    } catch (error) { if (error.code !== 'ENOENT') throw error }
+  }
+}
+async function optionalRead(file) {
+  try { return await fs.readFile(file, 'utf8') } catch (error) { if (error.code === 'ENOENT') return null; throw error }
+}
+export async function loadState(stateDir, tool) {
+  validateTool(tool)
+  await assertSafePath(stateDir)
+  const file = path.join(stateDir, `${tool}.json`)
+  await assertSafePath(file)
+  const raw = await optionalRead(file)
+  if (raw === null) throw new Error('Tool is not configured. Run setup first.')
+  let state
+  try { state = JSON.parse(raw) } catch { throw new Error('Invalid helper manifest; refusing to change state.') }
+  if (!state || typeof state !== 'object' || Array.isArray(state) || !['files,model,tool', 'files,model,roles,tool'].includes(Object.keys(state).sort().join(',')) || state.tool !== tool || typeof state.model !== 'string' || !Array.isArray(state.files)) throw new Error('Invalid helper manifest.')
+  const plan = planFor({ stateDir, tool, model: state.model, roles: state.roles })
+  if (JSON.stringify(state.files) !== JSON.stringify(plan.files.map(file => ({ path: file.path, hash: digest(file.content) })))) throw new Error('Helper manifest does not match the generated plan.')
+  for (const file of plan.files) {
+    await assertSafePath(file.path)
+    const content = await optionalRead(file.path)
+    if (content === null || digest(content) !== digest(file.content)) throw new Error('Helper-owned configuration was modified. Review it before setup; refusing to overwrite or launch it.')
+  }
+  return { state, plan }
+}
+async function atomicWrite(file, content) {
+  await assertSafePath(file)
+  await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 })
+  const temp = `${file}.${randomUUID()}.tmp`
+  try {
+    await fs.writeFile(temp, content, { flag: 'wx', mode: 0o600 })
+    await fs.rename(temp, file)
+    await fs.chmod(file, 0o600)
+  } finally { await fs.unlink(temp).catch(error => { if (error.code !== 'ENOENT') throw error }) }
+}
+export async function setup({ stateDir, tool, model, roles, dryRun = false, update = false, autoBackup = false }) {
+  const plan = planFor({ stateDir, tool, model, roles })
+  await assertSafePath(stateDir)
+  const manifest = path.join(stateDir, `${tool}.json`)
+  await assertSafePath(manifest)
+  const existing = await optionalRead(manifest)
+  if (existing !== null) {
+    const loaded = await loadState(stateDir, tool)
+    if ((loaded.state.model !== model || JSON.stringify(loaded.state.roles) !== JSON.stringify(roles)) && !update) throw new Error('A different model is configured. Use --update after reviewing the change.')
+  } else {
+    for (const file of plan.files) {
+      await assertSafePath(file.path)
+      if (await optionalRead(file.path) !== null) throw new Error('Unmanaged file exists in helper state; refusing to overwrite it.')
+    }
+  }
+  if (dryRun) return { ...plan, changed: false, dryRun: true }
+  await fs.mkdir(stateDir, { recursive: true, mode: 0o700 })
+  const lock = path.join(stateDir, '.setup.lock')
+  let handle
+  try { handle = await fs.open(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 {
+    // Repeat validation after acquiring the exclusive writer lock.
+    if (await optionalRead(manifest) !== existing) throw new Error('State changed during setup; retry.')
+    if (existing !== null) await loadState(stateDir, tool)
+    const prior = []
+    for (const file of plan.files) {
+      await assertSafePath(file.path)
+      const content = await optionalRead(file.path)
+      if (existing === null && content !== null) throw new Error('Unmanaged file appeared during setup.')
+      prior.push({ path: file.path, content })
+    }
+    if (existing !== null && JSON.parse(existing).model === model && JSON.stringify(JSON.parse(existing).roles) === JSON.stringify(roles)) return { ...plan, changed: false }
+    if (existing !== null && autoBackup) {
+      const previous = await loadState(stateDir, tool)
+      await atomicWrite(path.join(stateDir, 'backups', `${tool}-${randomUUID()}.json`), JSON.stringify({ model: previous.state.model, ...(previous.state.roles ? { roles: previous.state.roles } : {}), tool, files: previous.plan.files }, null, 2) + '\n')
+    }
+    try {
+      for (const file of plan.files) await atomicWrite(file.path, file.content)
+      const state = { tool, model, ...(roles ? { roles } : {}), files: plan.files.map(file => ({ path: file.path, hash: digest(file.content) })) }
+      await atomicWrite(manifest, JSON.stringify(state, null, 2) + '\n')
+    } catch (error) {
+      for (const file of prior.reverse()) {
+        if (file.content === null) { await assertSafePath(file.path); await fs.unlink(file.path).catch(e => { if (e.code !== 'ENOENT') throw e }) }
+        else await atomicWrite(file.path, file.content)
+      }
+      throw error
+    }
+    return { ...plan, changed: true }
+  } finally { await handle.close(); await fs.unlink(lock) }
+}
+export async function reconfigure(options) {
+  return setup({ ...options, update: true, autoBackup: true })
+}
+
+export async function remove({ stateDir, tool, dryRun = false, yes = false, force = false }) {
+  validateTool(tool)
+  if (!yes && !dryRun) throw new Error('Removal requires --yes. Preview with --dry-run first.')
+  // Never trust paths from a possibly corrupt manifest, even in recovery mode.
+  const files = [...planFor({ stateDir, tool, model: 'removal-placeholder' }).files.map(file => file.path), path.resolve(stateDir, `${tool}.json`)]
+  async function inspect() {
+    await assertSafePath(stateDir)
+    const present = []
+    for (const file of files) {
+      await assertSafePath(file)
+      try {
+        const stat = await fs.lstat(file)
+        if (!stat.isFile()) throw new Error('Refusing a non-file removal target.')
+        present.push(file)
+      } catch (error) { if (error.code !== 'ENOENT') throw error }
+    }
+    if (present.length && !force) await loadState(stateDir, tool)
+    return present
+  }
+  let present = await inspect()
+  if (dryRun || !present.length) return { files: present, changed: false, dryRun, force }
+  const lock = path.join(stateDir, '.setup.lock')
+  let handle
+  try { handle = await fs.open(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 {
+    present = await inspect()
+    for (const file of present) { await assertSafePath(file); await fs.unlink(file) }
+    return { files: present, changed: present.length > 0, dryRun: false, force }
+  } finally { await handle.close(); await fs.unlink(lock) }
+}
+
+export async function backup({ stateDir, tool }) {
+  // Validate before creating anything, then serialize the snapshot with setup.
+  await loadState(stateDir, tool)
+  const lock = path.join(stateDir, '.setup.lock')
+  let handle
+  try { handle = await fs.open(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 {
+    const { state, plan } = await loadState(stateDir, tool)
+    const file = path.join(stateDir, 'backups', `${tool}-${randomUUID()}.json`)
+    await atomicWrite(file, JSON.stringify({ model: state.model, ...(state.roles ? { roles: state.roles } : {}), tool, files: plan.files }, null, 2) + '\n')
+    return file
+  } finally { await handle.close(); await fs.unlink(lock) }
+}

package/src/ui.mjs

@@ -0,0 +1,245 @@
+import { createInterface } from 'node:readline/promises'
+import { fetchModels } from './catalog.mjs'
+import * as claudeAdapter from './adapters/claude.mjs'
+
+const palette = { heading: 36, info: 34, success: 32, warning: 33, error: 31, muted: 90, selected: 35 }
+
+/** Semantic colors; NO_COLOR wins and FORCE_COLOR=0 disables colors. */
+export function colorize(text, kind, { output = process.stdout, env = process.env } = {}) {
+  const force = env.FORCE_COLOR
+  const enabled = !Object.hasOwn(env, 'NO_COLOR') && (force !== undefined ? force !== '0' : Boolean(output.isTTY))
+  const code = palette[kind]
+  return enabled && code ? `\u001b[${code}m${text}\u001b[0m` : String(text)
+}
+
+function uiError(cancelled = false) {
+  const error = new Error(cancelled ? 'Selection cancelled; no action taken.' : 'Terminal interaction failed; no action taken.')
+  error.code = cancelled ? 'UI_CANCELLED' : 'UI_TERMINAL_ERROR'
+  return error
+}
+const clean = text => String(text).replace(/[\x00-\x1f\x7f-\x9f]/g, ' ')
+
+/** Arrow-key menu. No typed answers are accepted. */
+export async function select({ message, choices, input = process.stdin, output = process.stdout, language = 'en' }) {
+  if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== 'function') {
+    throw new Error('Non-interactive setup needs setup --tool dsh|claude --model PUBLIC_MODEL.')
+  }
+  if (!Array.isArray(choices) || !choices.length || choices.some(choice => !choice || typeof choice.label !== 'string')) {
+    throw new Error('Selection requires labeled choices.')
+  }
+  const wasRaw = Boolean(input.isRaw)
+  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('')
+  }
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      clearTimeout(timer)
+      input.off('data', onData)
+      input.off('error', onFailure)
+      input.off('end', onFailure)
+      input.off('close', onFailure)
+      output.off('error', onFailure)
+      try { input.setRawMode(wasRaw) } catch {}
+      try { if (wasPaused) input.pause() } catch {}
+      try { output.write('\u001b[?25h') } catch {}
+    }
+    const finish = (error, value) => {
+      if (settled) return
+      settled = true
+      cleanup()
+      if (error) reject(error)
+      else resolve(value)
+    }
+    function onFailure() { finish(uiError()) }
+    function draw() {
+      if (rendered) output.write(`\u001b[${lines}A\r`)
+      output.write('\u001b[2K' + colorize(fit(message), 'heading', { output }) + '\n')
+      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')
+      rendered = true
+    }
+    function onData(chunk) {
+      try {
+        clearTimeout(timer)
+        buffer += chunk.toString('utf8')
+        while (buffer && !settled) {
+          if (buffer[0] === '\u0003') return finish(uiError(true))
+          if (buffer[0] === '\r' || buffer[0] === '\n') return finish(null, choices[index].value)
+          if (buffer[0] === '\u001b') {
+            if (buffer.startsWith('\u001b[A') || buffer.startsWith('\u001bOA')) {
+              index = (index + choices.length - 1) % choices.length
+              buffer = buffer.slice(3); draw(); continue
+            }
+            if (buffer.startsWith('\u001b[B') || buffer.startsWith('\u001bOB')) {
+              index = (index + 1) % choices.length
+              buffer = buffer.slice(3); draw(); continue
+            }
+            if (['\u001b', '\u001b[', '\u001bO'].includes(buffer)) {
+              timer = setTimeout(() => finish(uiError(true)), 35)
+              return
+            }
+            // Ignore other terminal navigation sequences (e.g. left/right).
+            const sequence = buffer.match(/^\u001b(?:\[[0-9;]*[A-Za-z~]|O[A-Za-z])/)
+            if (sequence) { buffer = buffer.slice(sequence[0].length); continue }
+            return finish(uiError(true))
+          }
+          buffer = buffer.slice(1) // Free text, including y/n, cannot choose anything.
+        }
+      } catch { finish(uiError()) }
+    }
+    try {
+      input.on('data', onData)
+      input.on('error', onFailure)
+      input.on('end', onFailure)
+      input.on('close', onFailure)
+      output.on('error', onFailure)
+      input.setRawMode(true)
+      output.write('\u001b[?25l')
+      draw()
+      input.resume()
+    } catch { finish(uiError()) }
+  })
+}
+
+async function modelQuestion(input, output, language = 'en') {
+  const controller = new AbortController()
+  const terminal = createInterface({ input, output, terminal: true })
+  const abort = () => controller.abort()
+  input.on('error', abort)
+  input.on('end', abort)
+  input.on('close', abort)
+  terminal.on('SIGINT', abort)
+  try {
+    const model = (await terminal.question(colorize(language === 'vi' ? 'Mã mô hình công khai: ' : 'Public model ID: ', 'heading', { output }), { signal: controller.signal })).trim()
+    if (!model || /[\x00-\x1f\x7f]/.test(model)) throw new Error(language === 'vi' ? 'Nhập mã mô hình công khai hợp lệ.' : 'Enter a valid public model ID.')
+    return model
+  } catch (error) {
+    if (controller.signal.aborted) throw uiError(true)
+    throw error
+  } finally {
+    input.off('error', abort)
+    input.off('end', abort)
+    input.off('close', abort)
+    terminal.off('SIGINT', abort)
+    terminal.close()
+  }
+}
+
+/** Gather CLI arguments only. State and tool execution belong to dispatch. */
+export async function wizard({ dispatch, input = process.stdin, output = process.stdout, loadModels = fetchModels }) {
+  if (typeof dispatch !== 'function') throw new Error('Wizard requires a CLI dispatcher.')
+  let language = 'en'
+  const t = (en, vi) => language === 'vi' ? vi : en
+  const choose = (message, choices) => select({ message, choices, input, output, language })
+  const confirm = message => choose(message, [
+    { label: t('Cancel', 'Hủy'), value: false, description: t('No changes', 'Không thay đổi') },
+    { label: t('Confirm', 'Xác nhận'), value: true }
+  ])
+  try {
+    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'), [
+      { 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' },
+      { label: t('Doctor', 'Kiểm tra'), value: 'doctor', description: t('Local checks; no network requests', 'Kiểm tra cục bộ; không gửi yêu cầu mạng') },
+      { label: t('Run', 'Chạy'), value: 'run', description: t('Starts the tool; may send billed requests', 'Khởi chạy công cụ; có thể phát sinh phí') },
+      { label: t('Exit', 'Thoát'), value: 'exit' }
+    ])
+    if (action === 'exit') return
+    const tool = await choose(t('Choose coding tool', 'Chọn công cụ lập trình'), [
+      { label: 'DSH', value: 'dsh' }, { label: 'Claude Code', value: 'claude' }
+    ])
+    const argv = [action, '--tool', tool]
+    if (action === 'setup' || action === 'reconfigure') {
+      let models, manual = false
+      while (!models && !manual) {
+        output.write(colorize(t('Loading public 1endpoint model catalog (no API key)...\n', 'Đang tải danh sách mô hình công khai từ 1endpoint (không dùng khóa API)...\n'), 'info', { output }))
+        try {
+          models = await loadModels()
+          if (!Array.isArray(models) || !models.length) throw new Error('Empty catalog')
+        } catch {
+          models = undefined
+          const recovery = await choose(t('Model catalog unavailable. Choose explicitly how to continue.', 'Không tải được danh sách mô hình. Chọn cách tiếp tục.'), [
+            { label: t('Cancel', 'Hủy'), value: 'cancel' },
+            { label: t('Retry catalog', 'Tải lại danh sách'), value: 'retry' },
+            { label: t('Manual model ID', 'Nhập mã mô hình'), value: 'manual', description: t('Enter a public model ID yourself', 'Tự nhập mã mô hình công khai') }
+          ])
+          if (recovery === 'cancel') return
+          manual = recovery === 'manual'
+        }
+      }
+      const pickModel = async label => manual
+        ? modelQuestion(input, output, language)
+        : choose(t(`Select public model for ${label}`, `Chọn mô hình công khai cho ${label}`), models.map(model => ({ label: model.name || model.id, value: model.id, description: model.name && model.name !== model.id ? model.id : undefined })))
+      if (tool === 'dsh') argv.push('--model', await pickModel('DSH'))
+      else {
+        const roles = claudeAdapter.CLAUDE_ROLES
+        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.'), [
+            { 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(', ') }
+          ])
+          if (extra) activeRoles.push(...optionalRoles)
+        }
+        const selected = {}
+        for (const role of activeRoles) {
+          const id = typeof role === 'string' ? role : role.id
+          selected[id] = await pickModel(typeof role === 'string' ? role : role.label)
+          argv.push(`--${id}-model`, selected[id])
+        }
+        argv.push('--model', selected.sonnet)
+      }
+      if (tool === 'claude') output.write(colorize(t('Claude safety: project/local settings, hooks and permissions are excluded. Managed policy remains active; no permission bypass is enabled.\n', 'An toàn Claude: không dùng cài đặt dự án/cục bộ, móc thực thi và quyền của dự án. Chính sách quản trị vẫn áp dụng; không bật bỏ qua quyền.\n'), 'warning', { output }))
+      if (!await confirm(t(`${action === 'setup' ? 'Create' : 'Update'} helper-owned ${tool} configuration? Existing user settings are not edited.`, `${action === 'setup' ? 'Tạo' : 'Cập nhật'} cấu hình riêng cho ${tool}? Không sửa cài đặt hiện có của người dùng.`))) return
+    }
+    if (action === 'run' && tool === 'dsh') {
+      const profile = await choose(t('Choose DSH launch profile', 'Chọn chế độ khởi chạy DSH'), [
+        { label: t('Default (web)', 'Mặc định (web)'), value: null },
+        ...['web', 'headless', 'acp', 'sdk'].map(value => ({ label: value, value }))
+      ])
+      if (profile) argv.push('--profile', profile)
+    }
+    if (action === 'remove') {
+      const mode = await choose(t('Remove helper configuration', 'Xóa cấu hình riêng'), [
+        { label: t('Cancel', 'Hủy'), value: 'cancel' },
+        { label: t('Normal removal', 'Xóa thông thường'), value: 'normal', description: t('Validate ownership and integrity', 'Kiểm tra quyền sở hữu và tính toàn vẹn') },
+        { label: t('Force removal recovery', 'Khôi phục bằng xóa cưỡng chế'), value: 'force', description: t('WARNING: modified fixed helper files may be deleted without backup', 'CẢNH BÁO: tệp cấu hình đã sửa có thể bị xóa mà không sao lưu') }
+      ])
+      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 }))
+      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 })
+    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`)
+    }
+    return result
+  } catch (error) {
+    if (error.code === 'UI_CANCELLED') {
+      output.write(colorize(t('Cancelled; no action taken.\n', 'Đã hủy; không thực hiện thao tác.\n'), 'warning', { output }))
+      return
+    }
+    throw error
+  }
+}