@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/cli_parser.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from typing import Any, Callable
+
+CliHandler = Callable[[argparse.Namespace], Any]
+
+
+@dataclass(frozen=True)
+class CliParserLaunch:
+    cli: CliHandler
+    launch: CliHandler
+    launch_codex: CliHandler
+    launch_codex_app_server: CliHandler
+    launch_agy: CliHandler
+    serve: CliHandler
+
+
+@dataclass(frozen=True)
+class CliParserRuntime:
+    version: CliHandler
+    status: CliHandler
+    env: CliHandler
+    stop: CliHandler
+    test: CliHandler
+
+
+@dataclass(frozen=True)
+class CliParserSettings:
+    language: CliHandler
+    web_search: CliHandler
+    web_fetch: CliHandler
+    log_level: CliHandler
+    channels: CliHandler
+    channel_delivery: CliHandler
+
+
+@dataclass(frozen=True)
+class CliParserProvider:
+    ollama_native: CliHandler
+    ollama_options: CliHandler
+    provider_options: CliHandler
+    ollama_catalog: CliHandler
+    provider: CliHandler
+    api_key: CliHandler
+    set_api_key: CliHandler
+    set_api_keys: CliHandler
+    base_url: CliHandler
+    copilot_oauth: CliHandler
+
+
+@dataclass(frozen=True)
+class CliParserModels:
+    model: CliHandler
+    advisor_model: CliHandler
+    models: CliHandler
+
+
+@dataclass(frozen=True)
+class CliParserServices:
+    launch: CliParserLaunch
+    runtime: CliParserRuntime
+    settings: CliParserSettings
+    provider: CliParserProvider
+    models: CliParserModels
+
+
+def build_cli_parser(services: CliParserServices) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="ciel-runtimectl")
+    commands = parser.add_subparsers(dest="cmd", required=True)
+    _add_remainder_command(commands, "cli", services.launch.cli)
+    _add_remainder_command(commands, "launch", services.launch.launch)
+    _add_remainder_command(commands, "launch-codex", services.launch.launch_codex)
+    _add_remainder_command(
+        commands,
+        "launch-codex-app-server",
+        services.launch.launch_codex_app_server,
+    )
+    _add_remainder_command(commands, "launch-agy", services.launch.launch_agy)
+    commands.add_parser("serve").set_defaults(func=services.launch.serve)
+    commands.add_parser("version").set_defaults(func=services.runtime.version)
+    commands.add_parser("status").set_defaults(func=services.runtime.status)
+    commands.add_parser("env").set_defaults(func=services.runtime.env)
+    commands.add_parser("stop").set_defaults(func=services.runtime.stop)
+    _add_optional_value_command(commands, "language", services.settings.language)
+    _add_optional_value_command(commands, "web-search", services.settings.web_search)
+    _add_optional_value_command(commands, "web-fetch", services.settings.web_fetch)
+    _add_optional_value_command(commands, "log-level", services.settings.log_level)
+    channels = commands.add_parser("channels")
+    channels.add_argument("values", nargs="*")
+    channels.set_defaults(func=services.settings.channels)
+    _add_optional_value_command(commands, "channel-delivery", services.settings.channel_delivery)
+    _add_optional_value_command(commands, "ollama-native", services.provider.ollama_native)
+    _add_values_command(commands, "ollama-options", services.provider.ollama_options)
+    _add_values_command(commands, "provider-options", services.provider.provider_options)
+    ollama_catalog = commands.add_parser("ollama-catalog")
+    ollama_catalog.add_argument("--no-contexts", action="store_true")
+    ollama_catalog.add_argument("--timeout", type=float, default=10.0)
+    ollama_catalog.set_defaults(func=services.provider.ollama_catalog)
+    test = commands.add_parser("test")
+    test.add_argument("timeout", nargs="?", type=float, default=120.0)
+    test.add_argument("mode", nargs="?", choices=("auto", "quick", "smoke", "full"), default="auto")
+    test.set_defaults(func=services.runtime.test)
+    provider = commands.add_parser("provider")
+    provider.add_argument("name", nargs="?")
+    provider.set_defaults(func=services.provider.provider)
+    api_key = commands.add_parser("api-key")
+    api_key.add_argument("provider", nargs="?")
+    api_key.add_argument("action", nargs="?")
+    api_key.set_defaults(func=services.provider.api_key)
+    set_api_key = commands.add_parser("set-api-key")
+    set_api_key.add_argument("provider")
+    set_api_key.add_argument("key")
+    set_api_key.set_defaults(func=services.provider.set_api_key)
+    set_api_keys = commands.add_parser("set-api-keys")
+    set_api_keys.add_argument("provider")
+    set_api_keys.add_argument("keys", nargs="+")
+    set_api_keys.set_defaults(func=services.provider.set_api_keys)
+    base_url = commands.add_parser("base-url")
+    base_url.add_argument("provider")
+    base_url.add_argument("url")
+    base_url.set_defaults(func=services.provider.base_url)
+    copilot_oauth = commands.add_parser("copilot-oauth")
+    copilot_oauth.add_argument(
+        "action",
+        nargs="?",
+        choices=("login", "status", "logout"),
+        default="status",
+    )
+    copilot_oauth.set_defaults(func=services.provider.copilot_oauth)
+    _add_values_command(commands, "model", services.models.model, argument_name="value")
+    _add_values_command(commands, "advisor-model", services.models.advisor_model, argument_name="value")
+    models = commands.add_parser("models")
+    models.add_argument("provider", nargs="?")
+    models.set_defaults(func=services.models.models)
+    return parser
+
+
+def _add_remainder_command(
+    commands: Any,
+    name: str,
+    handler: CliHandler,
+) -> None:
+    command = commands.add_parser(name, add_help=False)
+    command.add_argument("argv", nargs=argparse.REMAINDER)
+    command.set_defaults(func=handler)
+
+
+def _add_optional_value_command(commands: Any, name: str, handler: CliHandler) -> None:
+    command = commands.add_parser(name)
+    command.add_argument("value", nargs="?")
+    command.set_defaults(func=handler)
+
+
+def _add_values_command(
+    commands: Any,
+    name: str,
+    handler: CliHandler,
+    *,
+    argument_name: str = "values",
+) -> None:
+    command = commands.add_parser(name)
+    command.add_argument(argument_name, nargs="*")
+    command.set_defaults(func=handler)

package/ciel_runtime_support/cli_usage.py

@@ -0,0 +1,100 @@
+"""User-facing command-line usage presentation."""
+
+def cli_usage_text() -> str:
+    return """Usage:
+  ciel-runtime                         Launch Claude Code through ciel-runtime router
+  ciel-runtime codex [args...]         Launch Codex through ciel-runtime router
+  ciel-runtime codex-app-server [args...]  Launch Codex app-server through ciel-runtime
+  ciel-runtime agy [args...]           Launch Google Antigravity CLI through ciel-runtime
+  ciel-runtime resume                  Resume Codex/AGY when that runtime provider is selected
+
+Control plane, runs before Claude Code and does not require LLM connectivity:
+  ciel-runtime version                 Print ciel-runtime version
+  ciel-runtime language [en|ko|ja|zh] Set display language
+  ciel-runtime provider                Pick provider with arrow-key TUI
+  ciel-runtime provider list           List providers
+  ciel-runtime provider PROVIDER       Set provider
+  ciel-runtime base-url PROVIDER URL   Set provider base URL
+  ciel-runtime model MODEL_ID          Set current provider model
+  ciel-runtime advisor-model MODEL_ID  Set current provider advisor model (off disables)
+  ciel-runtime models [PROVIDER]       List models
+  ciel-runtime api-key PROVIDER        Store API key securely
+  ciel-runtime api-key PROVIDER clear  Clear stored API key(s)
+  ciel-runtime set-api-key PROVIDER KEY
+  ciel-runtime set-api-keys PROVIDER KEY1,KEY2
+  ciel-runtime web-search [on|off]     Auto-attach DuckDuckGo MCP for non-native providers
+  ciel-runtime web-fetch [on|off]      Auto-attach fetch MCP for web page content
+  ciel-runtime log-level [LEVEL]       Show or set router log level
+  ciel-runtime channels [cmd]          Configure external channel specs
+  ciel-runtime channel-delivery [stdin|native]
+                                      Select PTY wake proxy or native claude/channel bridge
+  ciel-runtime ollama-native [on|off]  Use Ollama's official Claude Code env path
+  ciel-runtime ollama-options [provider] [key=value ...]
+                                      Set Ollama num_ctx/options/keep_alive/think
+  ciel-runtime provider-options [provider] [key=value ...]
+                                      Set vLLM/NIM/NVIDIA output/context/timeouts
+  ciel-runtime ollama-catalog          Download Ollama model/context catalog
+  ciel-runtime test [seconds] [mode]   Test compatibility; mode is auto, quick, smoke, or full
+  ciel-runtime stop                    Stop router/proxy
+
+Headless setup flags, namespaced to avoid Claude CLI collisions:
+  ciel-runtime --ca-web-address HOST  Bind the web/router server to HOST for this launch
+  ciel-runtime --ca-web-port PORT     Select the web/router port for this launch
+  ciel-runtime --ca-tailscale-https[=PORT]
+                                      Publish localhost through Tailscale Serve HTTPS
+  ciel-runtime --ca-provider PROVIDER  Set provider, then launch
+  ciel-runtime --ca-env-file PATH      Load CIEL_RUNTIME_* values from a .env file
+  ciel-runtime --ca-runtime claude|codex|codex-app-server|agy
+                                      Select Claude Code, Codex, Codex app-server, or AGY for this launch
+  ciel-runtime --ca-menu               Apply setup values, then open the menu
+  ciel-runtime --ca-language en|ko|ja|zh
+  ciel-runtime --ca-base-url URL       Set current provider base URL, then launch
+  ciel-runtime --ca-model MODEL_ID     Set provider model, then launch
+  ciel-runtime --ca-advisor-model MODEL_ID
+  ciel-runtime --ca-auto-llm-options [MODEL_ID]
+                                      Apply recommended LLM options for MODEL_ID or the saved model
+  ciel-runtime --ca-api-key KEY        Set current provider API key, then launch
+  ciel-runtime --ca-api-key clear      Clear current provider API key(s), then launch
+  ciel-runtime --ca-api-key-env ENVVAR Set current provider API key from env, then launch
+  ciel-runtime --ca-api-keys KEY1,KEY2 Set current provider API keys with round-robin
+  ciel-runtime --ca-api-keys-env ENVVAR
+                                      Set current provider API keys from env, then launch
+  ciel-runtime --ca-set-api-key PROVIDER KEY
+  ciel-runtime --ca-set-api-key-env PROVIDER ENVVAR
+  ciel-runtime --ca-set-api-keys PROVIDER KEY1,KEY2
+  ciel-runtime --ca-set-api-keys-env PROVIDER ENVVAR
+  ciel-runtime --ca-provider-option KEY=VALUE
+                                      Set a provider option for the current provider
+  ciel-runtime --ca-set-provider-option PROVIDER KEY=VALUE
+                                      Set a provider option for a specific provider
+  ciel-runtime --ca-ollama-num-ctx VALUE
+  ciel-runtime --ca-ollama-ctx-range MIN MAX
+  ciel-runtime --ca-ollama-option KEY=VALUE
+  ciel-runtime --ca-max-output-tokens VALUE
+  ciel-runtime --ca-context-window VALUE
+  ciel-runtime --ca-request-timeout-ms VALUE
+  ciel-runtime --ca-stream-idle-timeout-ms VALUE
+  ciel-runtime --ca-rate-limit-rpm VALUE
+  ciel-runtime --ca-rate-limit-status on|off
+  ciel-runtime --ca-stream on|off
+  ciel-runtime --ca-stream-word-chunking on|off
+  ciel-runtime --ca-log-level LEVEL    Set router log level: SILENT, ERROR, WARN, INFO, DEBUG, TRACE
+  ciel-runtime --ca-web-search         Force DuckDuckGo MCP for this launch
+  ciel-runtime --ca-no-web-search      Disable DuckDuckGo MCP for this launch
+  ciel-runtime --ca-web-fetch          Enable fetch MCP
+  ciel-runtime --ca-no-web-fetch       Disable fetch MCP
+  ciel-runtime --ca-channel SPEC       Add an official/approved Claude Code channel
+  ciel-runtime --ca-channel-delivery MODE
+                                      Set channel delivery: stdin or native
+  ciel-runtime --ca-clear-channels     Clear saved channel specs
+  ciel-runtime --ca-no-self-update-check
+                                      Skip Ciel Runtime npm self-update check
+  ciel-runtime --ca-no-update-check    Skip runtime update check for this launch
+  ciel-runtime --ca-upgrade-and-exit   Update Ciel Runtime, Claude Code, Codex, and AGY without prompts, then exit
+  ciel-runtime --ca-no-launch          Apply setup flags/env values, then exit without launching a runtime
+  ciel-runtime --ca-stop               Stop router/proxy
+  ciel-runtime --                      Pass all following args directly to the selected runtime
+
+Provider names: agy, agy-routed, anthropic, ollama, ollama-cloud, deepseek, opencode, opencode-go, kimi, z.ai, vllm, lm-studio, nvidia-hosted, self-hosted-nim, openrouter, fireworks
+Any other arguments are passed through to the selected runtime. Use -- before runtime
+flags that collide with ciel-runtime setup flags."""

package/ciel_runtime_support/codex_app_server.py

@@ -144,17 +144,32 @@ class CodexAppServerClient:
         with self._lock:
             return self._state
 
-    def close(self) -> None:
+    def close(self, timeout: float = 2.0) -> None:
+        """Close pipes and reap the child, surfacing cleanup failures."""
+
+        errors: list[str] = []
         try:
             if self.process.stdin is not None:
                 self.process.stdin.close()
-        except Exception:
-            pass
+        except Exception as exc:
+            errors.append(f"stdin close failed: {type(exc).__name__}: {exc}")
         if self.process.poll() is None:
             try:
                 self.process.terminate()
-            except Exception:
-                pass
+            except Exception as exc:
+                errors.append(f"terminate failed: {type(exc).__name__}: {exc}")
+            try:
+                self.process.wait(timeout=max(0.0, timeout))
+            except subprocess.TimeoutExpired:
+                try:
+                    self.process.kill()
+                    self.process.wait(timeout=max(0.0, timeout))
+                except Exception as exc:
+                    errors.append(f"kill failed: {type(exc).__name__}: {exc}")
+            except Exception as exc:
+                errors.append(f"wait failed: {type(exc).__name__}: {exc}")
+        if errors:
+            raise CodexAppServerError("; ".join(errors))
 
     def initialize(
         self,

package/ciel_runtime_support/codex_channel_sse_launch.py

@@ -0,0 +1,87 @@
+"""Codex MCP channel SSE launch ownership and capability policy."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class CodexChannelSseQueryPorts:
+    delivery_mode: Callable[[dict[str, Any]], str]
+    channel_specs: Callable[[dict[str, Any], list[str]], list[str]]
+    server_names: Callable[[Iterable[str]], list[str]]
+    capable_names: Callable[[dict[str, Any], Path], list[str]]
+    dedupe: Callable[[Iterable[str]], list[str]]
+
+
+@dataclass(frozen=True, slots=True)
+class CodexChannelSseEffects:
+    auto_start: Callable[..., list[dict[str, Any]]]
+    log: Callable[[str, str], None]
+
+
+@dataclass(frozen=True, slots=True)
+class CodexChannelSseLaunchService:
+    query: CodexChannelSseQueryPorts
+    effects: CodexChannelSseEffects
+    native_channel_names: frozenset[str]
+
+    def start(
+        self,
+        config: dict[str, Any],
+        mcp_config: Path | None,
+        allowed_server_names: Iterable[str] | None = None,
+    ) -> list[dict[str, Any]]:
+        if not mcp_config or self.query.delivery_mode(config) != "llm":
+            return []
+        if not mcp_config.exists() or not mcp_config.is_file():
+            return []
+        explicit = {
+            name
+            for name in self.query.server_names(
+                self.query.channel_specs(config, [])
+            )
+            if name.strip().casefold() not in self.native_channel_names
+        }
+        if allowed_server_names is None:
+            names = self.query.capable_names(config, mcp_config)
+        else:
+            names = self.query.dedupe(
+                str(name or "").strip()
+                for name in allowed_server_names
+                if str(name or "").strip()
+                and str(name or "").strip().casefold()
+                not in self.native_channel_names
+            )
+        names = [name for name in names if name not in explicit]
+        if not names:
+            self.effects.log(
+                "INFO",
+                "codex_channel_sse_skipped "
+                "reason=no_capable_unowned_codex_mcp "
+                "allowed=%s explicit=%s"
+                % (
+                    ",".join(names) or "-",
+                    ",".join(sorted(explicit)) or "-",
+                ),
+            )
+            return []
+        started = self.effects.auto_start(
+            [],
+            extra_config_paths=[mcp_config],
+            allowed_server_names=names,
+            include_default_paths=False,
+        )
+        self.effects.log(
+            "INFO",
+            "codex_channel_sse_started count=%d servers=%s"
+            % (
+                len(started),
+                ",".join(str(item.get("name") or "") for item in started)
+                or "-",
+            ),
+        )
+        return started

package/ciel_runtime_support/codex_cli.py

@@ -72,11 +72,16 @@ CODEX_CLAUDE_ONLY_VALUE_FLAGS = {
 
 
 def codex_passthrough_first_non_option_arg(passthrough: list[str]) -> str:
+    index = codex_passthrough_first_non_option_index(passthrough)
+    return str(passthrough[index]) if index >= 0 else ""
+
+
+def codex_passthrough_first_non_option_index(passthrough: list[str]) -> int:
     i = 0
     while i < len(passthrough):
         arg = str(passthrough[i])
         if arg == "--":
-            return str(passthrough[i + 1]) if i + 1 < len(passthrough) else ""
+            return i + 1 if i + 1 < len(passthrough) else -1
         if arg.startswith("--") and "=" in arg:
             i += 1
             continue
@@ -86,14 +91,46 @@ def codex_passthrough_first_non_option_arg(passthrough: list[str]) -> str:
         if arg.startswith("-") and arg != "-":
             i += 1
             continue
-        return arg
-    return ""
+        return i
+    return -1
 
 
 def codex_passthrough_has_command(passthrough: list[str]) -> bool:
     return codex_passthrough_first_non_option_arg(passthrough) in CODEX_COMMAND_NAMES
 
 
+def codex_resume_picker_requested(passthrough: list[str]) -> bool:
+    command_index = codex_passthrough_first_non_option_index(passthrough)
+    if command_index < 0 or str(passthrough[command_index]) != "resume":
+        return False
+    i = command_index + 1
+    while i < len(passthrough):
+        arg = str(passthrough[i])
+        if arg in ("--last", "--all") or arg.startswith(("--last=", "--all=")):
+            i += 1
+            continue
+        if arg.startswith("--") and "=" in arg:
+            i += 1
+            continue
+        if arg in CODEX_OPTIONS_WITH_VALUE:
+            i += 2 if i + 1 < len(passthrough) else 1
+            continue
+        if arg.startswith("-") and arg != "-":
+            i += 1
+            continue
+        return False
+    return "--last" not in passthrough and not any(str(arg).startswith("--last=") for arg in passthrough)
+
+
+def codex_resume_with_session_id(passthrough: list[str], session_id: str) -> list[str]:
+    command_index = codex_passthrough_first_non_option_index(passthrough)
+    if command_index < 0 or str(passthrough[command_index]) != "resume":
+        return list(passthrough)
+    out = list(passthrough)
+    out.insert(command_index + 1, session_id)
+    return out
+
+
 def _codex_consume_optional_value(passthrough: list[str], index: int) -> tuple[str, int]:
     if index + 1 < len(passthrough):
         value = str(passthrough[index + 1])
@@ -298,6 +335,5 @@ def codex_passthrough_args_for_launch(passthrough: list[str]) -> tuple[list[str]
         out.append(arg)
         i += 1
 
-    if mapped_command and not existing_codex_command:
-        return [*mapped_command, *out], notes
-    return out, notes
+    result = [*mapped_command, *out] if mapped_command and not existing_codex_command else out
+    return result, notes