@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/README.md

@@ -0,0 +1,132 @@
+# Ciel Runtime
+
+Ciel Runtime is a cross-platform launcher and local model-routing layer for AI coding agents. It can launch Claude Code, Codex, Codex App Server, or AGY and connect them to native or OpenAI-compatible model providers through one configuration.
+
+## Features
+
+- Launch Claude Code, Codex, Codex App Server, and AGY from one CLI.
+- Route Anthropic Messages, OpenAI Chat/Responses, and Ollama-compatible traffic.
+- Select models and providers without rewriting each agent's configuration.
+- Rotate API keys and observe provider rate limits.
+- Normalize tool calls, thinking blocks, streaming events, and context limits.
+- Receive external MCP channel messages and inject them into active agent sessions.
+- Run on Windows, macOS, and Linux.
+
+## Requirements
+
+- Node.js 18 or newer when installed from npm.
+- Python 3.10 or newer.
+- At least one supported coding-agent CLI or the credentials for the provider you intend to use.
+
+The npm launcher searches for `py -3`, `python`, or `python3`. Set `CIEL_RUNTIME_PYTHON` to use a specific Python executable.
+
+## Install
+
+```sh
+npm install -g @oneciel-ai/ciel-runtime
+```
+
+The package installs these commands:
+
+- `ciel-runtime` and `cielrt`: configure and launch an agent.
+- `ciel-runtimectl`: inspect or change runtime configuration.
+- `ciel-runtime-stop`: stop the managed local router.
+
+Manual installation instructions are available in [docs/Installation.md](docs/Installation.md).
+
+## Quick start
+
+Select a provider and model interactively:
+
+```sh
+ciel-runtime
+```
+
+Or configure them explicitly:
+
+```sh
+ciel-runtimectl provider openrouter
+ciel-runtimectl set-api-key openrouter YOUR_API_KEY
+ciel-runtimectl model MODEL_ID
+```
+
+Launch a specific runtime:
+
+```sh
+ciel-runtime                 # Claude Code by default
+ciel-runtime codex
+ciel-runtime agy
+ciel-runtime codex-app-server
+```
+
+Inspect the active configuration and router status:
+
+```sh
+ciel-runtimectl status
+ciel-runtimectl models
+ciel-runtimectl test
+```
+
+See [docs/CLI-Reference.md](docs/CLI-Reference.md) for the complete command reference and [docs/Providers.md](docs/Providers.md) for provider-specific options.
+
+## Native and routed modes
+
+Ciel Runtime uses a provider's native endpoint when the selected agent and provider support a direct connection. Other combinations use a local HTTP router that translates request, response, streaming, thinking, and tool-call formats.
+
+The router binds to `127.0.0.1` by default. External router access is a debugging feature and should only be enabled on a trusted network with the external access token configured. Never expose an unauthenticated development router to the public internet.
+
+Configuration is stored under `~/.config/ciel-runtime/` on macOS and Linux or `%APPDATA%\ciel-runtime\` on Windows. Override the location with `CIEL_RUNTIME_CONFIG_DIR`. Files containing credentials are written with restricted permissions where the platform supports them.
+
+## Channels and MCP
+
+Ciel Runtime can discover channel-capable MCP servers and deliver channel messages to active Claude, Codex, or AGY sessions. Channel collection, delivery acknowledgement, and terminal injection are separate layers so a failed terminal submission does not incorrectly acknowledge a message.
+
+See [docs/MCP-Channels.md](docs/MCP-Channels.md) for configuration and transport details.
+
+## Stable and nightly releases
+
+Install the stable npm release:
+
+```sh
+npm install -g @oneciel-ai/ciel-runtime@latest
+```
+
+Install the latest nightly build:
+
+```sh
+npm install -g @oneciel-ai/ciel-runtime@nightly
+```
+
+Nightly builds are intended for early validation and may change behavior before the next stable release.
+
+## Development
+
+```sh
+npm test
+npm run lint
+npm pack --dry-run
+```
+
+`npm test` compiles the Python entry points and runs the complete unittest suite. The full suite includes subprocess and channel integration tests and can take several minutes.
+
+Architecture and maintenance references:
+
+- [Architecture](docs/Architecture.md)
+- [Module map](docs/Module-Map.md)
+- [Router](docs/Router.md)
+- [Configuration](docs/Configuration.md)
+- [Observability](docs/Observability.md)
+- [Test suite](docs/Test-Suite.md)
+
+## Security
+
+- Keep provider API keys out of source control and shell history.
+- Keep the router bound to loopback unless remote debugging is explicitly required.
+- Treat request traces, response traces, transcripts, and event logs as potentially sensitive.
+- Review Tool Guard configuration before granting agents access to destructive tools.
+
+Report security issues privately to the project maintainers rather than opening a public issue with credentials or request traces.
+
+## License
+
+MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/ciel-runtime-menu.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import json
+import os
 import select
 import shutil
 import subprocess
@@ -15,6 +16,12 @@ import urllib.parse
 import urllib.request
 from pathlib import Path
 
+from ciel_runtime_support.prelaunch_launch_preference import (
+    preferred_provider_launch_action,
+    remember_launch_action,
+)
+from ciel_runtime_support.runtime_paths import CONFIG_PATH
+
 try:
     import msvcrt
     HAS_MSVCRT = True
@@ -204,7 +211,7 @@ def _write_safe(row: int, col: int, text: str, style: str = "") -> None:
 
 
 CTL = str(Path.home() / ".local/bin/ciel-runtimectl")
-CONFIG = Path.home() / ".config/ciel-runtime/config.json"
+CONFIG = CONFIG_PATH
 NCP_ENV = Path.home() / ".config/nvd-claude-proxy/.env"
 PROVIDERS = [
     ("agy:native", "AGY"),
@@ -585,10 +592,28 @@ def load_cfg() -> dict:
     return {"current_provider": "nvidia-hosted", "providers": {}}
 
 
+def persist_launch_action(action: str) -> None:
+    config = load_cfg()
+    if not remember_launch_action(config, action):
+        return
+    CONFIG.parent.mkdir(parents=True, exist_ok=True)
+    temporary = CONFIG.with_name(f".{CONFIG.name}.{os.getpid()}.tmp")
+    try:
+        temporary.write_text(json.dumps(config, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        if os.name != "nt":
+            temporary.chmod(0o600)
+        temporary.replace(CONFIG)
+    finally:
+        try:
+            temporary.unlink(missing_ok=True)
+        except Exception:
+            pass
+
+
 KNOWN_NVIDIA_MODEL_STATUS = {
     "claude-nvidia-llama-3.1-nemotron-ultra-253b-v1": ("FAIL 404", "listed but not callable for this NVIDIA account"),
 }
-DEFAULT_ADVISOR_MODELS = ["deepseek-v4-pro", "claude-opus-4-6", "claude-sonnet-4-6", "glm-5.1"]
+DEFAULT_ADVISOR_MODELS = ["claude-opus-5", "deepseek-v4-pro", "claude-opus-4-6", "claude-sonnet-4-6", "glm-5.1"]
 COMPAT_OK_TTL_SECONDS = 24 * 60 * 60
 COMPAT_FAIL_TTL_SECONDS = 5 * 60
 
@@ -701,6 +726,21 @@ def meaningful_key(value: str | None) -> bool:
     return bool(value and value not in ("dummy", "not-used", "ollama"))
 
 
+def stored_key_looks_like_error(value: str | None) -> bool:
+    text = str(value or "").strip().lower()
+    if not text:
+        return False
+    markers = (
+        "urlerror", "httperror", "http error", "<urlopen error",
+        "eof occurred in violation of protocol", "traceback (most recent call last)",
+        "connection refused", "connection reset", "timed out", "unauthorized",
+        "401 client error", "403 client error", "404 client error",
+        "500 internal server error", "502 bad gateway", "503 service unavailable",
+        "504 gateway",
+    )
+    return any(marker in text for marker in markers)
+
+
 def api_key_status(provider: str, pcfg: dict) -> str:
     if provider == "nvidia-hosted":
         return "API key: set (NVIDIA)" if meaningful_key(read_env_file(NCP_ENV).get("NVIDIA_API_KEY")) else "API key: missing (NVIDIA required)"
@@ -715,6 +755,8 @@ def api_key_status(provider: str, pcfg: dict) -> str:
             return "API key: not set (uses native Codex login/auth headers)"
         return "API key: optional fallback (uses native Codex login/config)"
     if provider == "ollama-cloud":
+        if stored_key_looks_like_error(pcfg.get("api_key")):
+            return "API key: INVALID (stored value is an error message, not a key — re-enter)"
         return "API key: set (Ollama Cloud)" if meaningful_key(pcfg.get("api_key")) else "API key: missing (Ollama Cloud required)"
     if provider == "deepseek":
         return "API key: set (DeepSeek)" if meaningful_key(pcfg.get("api_key")) else "API key: missing (DeepSeek required)"
@@ -727,7 +769,10 @@ def api_key_status(provider: str, pcfg: dict) -> str:
 
 
 def launch_requires_api_key(provider: str, pcfg: dict) -> bool:
-    return provider in ("nvidia-hosted", "ollama-cloud", "deepseek") and "missing" in api_key_status(provider, pcfg).lower()
+    if provider in ("nvidia-hosted", "ollama-cloud", "deepseek"):
+        status = api_key_status(provider, pcfg).lower()
+        return "missing" in status or "invalid" in status
+    return False
 
 
 def join_url(base: str, path: str) -> str:
@@ -1649,9 +1694,10 @@ def index_for_action(action: str) -> int:
 
 
 def default_launch_action() -> str:
-    if agy_launch_enabled(current_provider()):
-        return "launch-agy"
-    return "launch-codex" if codex_launch_enabled(current_provider()) else "launch"
+    provider = current_provider()
+    return preferred_provider_launch_action(
+        load_cfg(), provider, agy_launch_enabled, claude_launch_enabled, codex_launch_enabled
+    )
 
 
 def add(stdscr, y: int, x: int, text: str, style: str = "") -> None:
@@ -1870,6 +1916,7 @@ def main() -> int:
                         idx = index_for_action("api-key")
                         sub = None
                         continue
+                    persist_launch_action(action)
                     return PRELAUNCH_LAUNCH_CLAUDE
                 if action == "launch-agy":
                     provider, pcfg = current_provider_cfg()
@@ -1902,6 +1949,7 @@ def main() -> int:
                         idx = index_for_action("api-key")
                         sub = None
                         continue
+                    persist_launch_action(action)
                     return PRELAUNCH_LAUNCH_CODEX
                 if action == "test":
                     code, out = run_test_with_animation(idx, checks)
@@ -2121,6 +2169,7 @@ def main() -> int:
                 ]
                 idx = index_for_action("api-key")
                 continue
+            persist_launch_action(action)
             return PRELAUNCH_LAUNCH_CLAUDE
         if action == "launch-agy":
             provider, pcfg = current_provider_cfg()
@@ -2149,6 +2198,7 @@ def main() -> int:
                 ]
                 idx = index_for_action("api-key")
                 continue
+            persist_launch_action(action)
             return PRELAUNCH_LAUNCH_CODEX
         if action == "test":
             code, out = run_test_with_animation(idx, checks)