@oneciel-ai/ciel-runtime 0.2.31 → 0.2.32

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 This file records stable Ciel Runtime releases. Changes are grouped by user-visible
 capability, followed by the complete commit ledger merged into each release.
 
+## 0.2.32 — 2026-08-24
+
+- Keep Z.AI Start Plan wire identity aligned with the installed ZCode app:
+  `User-Agent: ZCode/3.8.1` and the OAuth JWT in `Authorization: Bearer`, without
+  adding `X-Api-Key`.
+- Add opt-in remote CAPTCHA callback settings for browserless hosts: bind host,
+  fixed/dynamic port, public HTTP(S) origin, and timeout are configurable through
+  `ciel-runtimectl provider-options` or environment variables.
+- Preserve loopback-only behavior by default and retain the state-bound,
+  one-request CAPTCHA result receiver when remote callback access is enabled.
+
 ## 0.2.31 — 2026-08-24
 
 - Force Z.AI Start Plan OAuth through the state-bound

package/ciel_runtime_support/providers/zai.py

@@ -5,6 +5,7 @@ from typing import Any, Mapping
 
 from ..architecture import (
     ProviderCapabilities,
+    ProviderConfigurationPolicy,
     ProviderConfig,
     ProviderContextPolicy,
     ProviderModelCatalogPolicy,
@@ -13,7 +14,7 @@ from ..architecture import (
     ProviderStatusPolicy,
     MessageProtocol,
 )
-from .base import HttpBearerProviderAdapter, provider_configuration
+from .base import HttpBearerProviderAdapter, configuration_policy, provider_configuration
 from .constants import PROVIDER_DEFAULT_BASE_URLS, ZAI_MODEL_FALLBACK_IDS
 
 
@@ -354,6 +355,26 @@ class ZaiStartPlanProviderAdapter(ZaiCodingPlanProviderAdapter):
     ) -> Mapping[str, str]:
         return self.build_headers(config, api_key)
 
+    def configuration_policy(
+        self, config: ProviderConfig
+    ) -> ProviderConfigurationPolicy:
+        del config
+        return configuration_policy(
+            text_option_aliases={
+                "captcha_bind_host": "zai_captcha_bind_host",
+                "captcha_port": "zai_captcha_port",
+                "captcha_public_base_url": "zai_captcha_public_base_url",
+                "captcha_timeout_seconds": "zai_captcha_timeout_seconds",
+                "zai_captcha_bind_host": "zai_captcha_bind_host",
+                "zai_captcha_port": "zai_captcha_port",
+                "zai_captcha_public_base_url": "zai_captcha_public_base_url",
+                "zai_captcha_timeout_seconds": "zai_captcha_timeout_seconds",
+            },
+            strip_trailing_slash_fields=frozenset(
+                {"zai_captcha_public_base_url"}
+            ),
+        )
+
     def launch_api_key_error(self, config: ProviderConfig) -> str | None:
         if not config.api_keys:
             return self.api_key_launch_error_value

package/ciel_runtime_support/runtime_constants.py

@@ -87,7 +87,7 @@ OPENCODE_ENDPOINT_ALIASES = {
 }
 
 APP_NAME = "Ciel Runtime"
-VERSION = "0.2.31"
+VERSION = "0.2.32"
 CREDITS = "Credits: One Ciel LLC"
 PRELAUNCH_CANCEL = 10
 PRELAUNCH_LAUNCH_CODEX = 11

package/ciel_runtime_support/zai_start_plan_captcha.py

@@ -79,6 +79,7 @@ class _CaptchaResultReceiver:
     timeout_seconds: float
     host: str = "127.0.0.1"
     port: int = 0
+    public_base_url: str = ""
     _server: _LoopbackCaptchaServer | None = field(default=None, init=False)
     _thread: threading.Thread | None = field(default=None, init=False)
     _ready: threading.Event = field(default_factory=threading.Event, init=False)
@@ -90,7 +91,36 @@ class _CaptchaResultReceiver:
         if self._server is None:
             raise RuntimeError("Z.AI CAPTCHA receiver was not started.")
         query = urllib.parse.urlencode({"state": self.state})
-        return f"http://localhost:{self._server.server_port}{_CAPTCHA_PATH}?{query}"
+        base = self._resolved_public_base_url(self._server.server_port)
+        return f"{base}{_CAPTCHA_PATH}?{query}"
+
+    def _resolved_public_base_url(self, server_port: int) -> str:
+        configured = str(self.public_base_url or "").strip().rstrip("/")
+        if not configured:
+            return f"http://localhost:{server_port}"
+        candidate = configured.replace("{port}", str(server_port))
+        parsed = urllib.parse.urlsplit(candidate)
+        if (
+            parsed.scheme not in {"http", "https"}
+            or not parsed.hostname
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.query
+            or parsed.fragment
+            or parsed.path not in {"", "/"}
+        ):
+            raise RuntimeError(
+                "Z.AI CAPTCHA public base URL must be an HTTP(S) origin; "
+                "use {port} for the receiver port."
+            )
+        if "{port}" not in configured and parsed.port is None:
+            hostname = parsed.hostname
+            if ":" in hostname and not hostname.startswith("["):
+                hostname = f"[{hostname}]"
+            candidate = urllib.parse.urlunsplit(
+                (parsed.scheme, f"{hostname}:{server_port}", "", "", "")
+            )
+        return candidate.rstrip("/")
 
     def __enter__(self) -> "_CaptchaResultReceiver":
         receiver = self
@@ -314,13 +344,37 @@ class ZaiStartPlanCaptchaBroker:
     def headers(self, options: Mapping[str, Any]) -> dict[str, str]:
         app_version = str(options.get("zcode_app_version") or "3.8.1").strip()
         timeout = self._timeout(options)
+        bind_host = self._bind_host(options)
+        port = self._port(options)
+        public_base_url = self._public_base_url(options)
         with self._request_lock:
             config = self.fetch_config(app_version)
             state = self.random_state()
-            with self.receiver_factory(config, state, timeout) as receiver:
+            with self.receiver_factory(
+                config,
+                state,
+                timeout,
+                host=bind_host,
+                port=port,
+                public_base_url=public_base_url,
+            ) as receiver:
                 url = receiver.url
                 self.log("INFO", f"zai_start_plan_captcha_waiting url={url}")
-                if not self.open_url(url):
+                try:
+                    opened = self.open_url(url)
+                except Exception as exc:
+                    if not public_base_url:
+                        raise RuntimeError(
+                            "Could not open the Z.AI Start Plan verification page: "
+                            + url
+                        ) from exc
+                    opened = False
+                    self.log(
+                        "WARN",
+                        "zai_start_plan_captcha_browser_open_failed "
+                        f"url={url} error={type(exc).__name__}",
+                    )
+                if not opened and not public_base_url:
                     raise RuntimeError(
                         "Could not open the Z.AI Start Plan verification page: " + url
                     )
@@ -345,6 +399,35 @@ class ZaiStartPlanCaptchaBroker:
         except (TypeError, ValueError):
             return 120.0
 
+    @staticmethod
+    def _bind_host(options: Mapping[str, Any]) -> str:
+        return str(
+            options.get("zai_captcha_bind_host")
+            or os.environ.get("CIEL_RUNTIME_ZAI_CAPTCHA_BIND_HOST")
+            or "127.0.0.1"
+        ).strip()
+
+    @staticmethod
+    def _port(options: Mapping[str, Any]) -> int:
+        raw = options.get("zai_captcha_port") or os.environ.get(
+            "CIEL_RUNTIME_ZAI_CAPTCHA_PORT", "0"
+        )
+        try:
+            port = int(raw)
+        except (TypeError, ValueError) as exc:
+            raise RuntimeError("Z.AI CAPTCHA port must be an integer.") from exc
+        if port < 0 or port > 65535:
+            raise RuntimeError("Z.AI CAPTCHA port must be between 0 and 65535.")
+        return port
+
+    @staticmethod
+    def _public_base_url(options: Mapping[str, Any]) -> str:
+        return str(
+            options.get("zai_captcha_public_base_url")
+            or os.environ.get("CIEL_RUNTIME_ZAI_CAPTCHA_PUBLIC_BASE_URL")
+            or ""
+        ).strip()
+
     @staticmethod
     def _platform_key() -> str:
         system = {"Windows": "win32", "Darwin": "darwin", "Linux": "linux"}.get(

package/docs/CLI-Reference.md

@@ -108,6 +108,23 @@ ciel-runtimectl base-url [PROVIDER] [URL]
 ciel-runtimectl base-url ollama http://remote-server:11434
 ```
 
+#### `provider-options` — Z.AI Start Plan remote CAPTCHA
+
+원격 Linux 호스트에서 Z.AI Start Plan의 사람 검증 페이지를 운영자 브라우저로
+열어야 할 때는 접근 가능한 인터페이스만 명시적으로 바인딩한다. 기본값은 계속
+`127.0.0.1`이며 외부에 공개되지 않는다.
+
+```bash
+ciel-runtimectl provider-options zai-start-plan \
+  captcha_bind_host=100.95.132.58 \
+  captcha_port=42119 \
+  'captcha_public_base_url=http://100.95.132.58:{port}'
+```
+
+`captcha_public_base_url`은 `http://` 또는 `https://` origin만 허용하며,
+`{port}`는 실제 CAPTCHA 수신 포트로 치환된다. URL에는 요청마다 새로 생성되는
+state 값이 추가된다.
+
 ---
 
 ### API 키 관리

package/docs/Configuration.md

@@ -408,6 +408,34 @@ ConPTY 생성이 불가능하거나 `CIEL_RUNTIME_WINDOWS_CONPTY=0`으로 명시
 ciel-runtimectl language ko
 ```
 
+### Z.AI Start Plan remote CAPTCHA callback
+
+Z.AI Start Plan은 모델 요청 전에 공식 Aliyun CAPTCHA의 일회성 결과가 필요할 수
+있습니다. 브라우저가 없는 원격 호스트에서는 `provider-options`로 운영자
+브라우저가 접근할 callback origin을 설정할 수 있습니다.
+
+```bash
+ciel-runtimectl provider-options zai-start-plan \
+  captcha_bind_host=100.95.132.58 \
+  captcha_port=42119 \
+  'captcha_public_base_url=http://100.95.132.58:{port}' \
+  captcha_timeout_seconds=120
+```
+
+- `captcha_bind_host`: 수신 서버가 바인딩할 로컬 인터페이스입니다. 기본값은
+  `127.0.0.1`입니다.
+- `captcha_port`: 고정 포트이며 `0`이면 운영체제가 빈 포트를 선택합니다.
+- `captcha_public_base_url`: 운영자 브라우저에 표시할 HTTP(S) origin입니다.
+  `{port}` 자리표시자를 사용할 수 있습니다.
+- `captcha_timeout_seconds`: 결과 대기 시간이며 15~600초로 제한됩니다.
+
+환경 변수 `CIEL_RUNTIME_ZAI_CAPTCHA_BIND_HOST`,
+`CIEL_RUNTIME_ZAI_CAPTCHA_PORT`,
+`CIEL_RUNTIME_ZAI_CAPTCHA_PUBLIC_BASE_URL`,
+`CIEL_RUNTIME_ZAI_CAPTCHA_TIMEOUT_SECONDS`도 같은 값을 제공합니다. 공개 callback은
+state-bound 일회성 URL을 사용하지만, 신뢰하는 사설 인터페이스에만 바인딩해야
+합니다.
+
 ---
 
 ## 관련 문서

package/docs/journal/2026/08/24/mia-zai-start-plan-auth-ua-wire-verification.okf

@@ -0,0 +1,75 @@
+okf_version: "1.0"
+knowledge:
+  task:
+    id: mia-zai-start-plan-auth-ua-wire-verification-20260824
+    date: "2026-08-24"
+    objective: >-
+      Verify from evidence whether Mia's Z.AI Start Plan routed requests carry
+      the OAuth bearer credential and the exact ZCode CLI user agent, and make
+      the required human CAPTCHA reachable from a remote operator browser.
+    status: in_progress
+
+  evidence:
+    official_zcode_runtime:
+      installed_cli_package: zcode-app-cli@3.8.1-15
+      app_version: 3.8.1
+      header_builder_observation: >-
+        The bundled ZCode runtime constructs User-Agent as ZCode/<appVersion>.
+    mia_installed_ciel_runtime:
+      version: 0.2.31-nightly.20260824-143754.e0bf793
+      provider: zai-start-plan
+      model: ciel-runtime-zai-start-plan-glm-5.3-1m
+      wire_capture:
+        user_agent: ZCode/3.8.1
+        authorization_present: true
+        authorization_scheme: Bearer
+        authorization_token_matches_configured_credential: true
+        x_api_key_present: false
+      secret_handling: >-
+        The credential value was not printed; verification used equality and
+        scheme checks only.
+    connection_failure:
+      reproduced_stage: pre-request CAPTCHA header acquisition
+      elapsed_seconds: 0.759
+      browser_probe: Python webbrowser.get() could not locate a runnable browser
+      request_reached_zai_gateway: false
+      conclusion: >-
+        The observed Mia failure occurs before the Z.AI model request, so the
+        verified Authorization and User-Agent headers are not its failing stage.
+    browser_runtime:
+      headless_shell_result: interactive CAPTCHA required and timed out
+      headed_chrome_xvfb_result: interactive CAPTCHA required and timed out
+      screenshot_observation: >-
+        The official Aliyun SDK displayed a human slider puzzle; changing UA or
+        running headed Chrome did not turn it into a traceless pass.
+
+  implementation:
+    auth_and_ua_behavior_change: none
+    remote_captcha_callback:
+      default_bind_host: 127.0.0.1
+      configurable_fields:
+        - zai_captcha_bind_host
+        - zai_captcha_port
+        - zai_captcha_public_base_url
+        - zai_captcha_timeout_seconds
+      security: >-
+        External binding remains opt-in. The public URL must be an HTTP(S)
+        origin, and each request retains its random state-bound result URL.
+    regression_coverage:
+      file: tests/test_zai_provider.py
+      assertion: >-
+        A real loopback HTTP request must retain User-Agent ZCode/3.8.1 and the
+        OAuth Bearer token and must not add X-Api-Key.
+
+  verification:
+    completed:
+      - Mia installed-package wire capture
+      - ZCode CLI version comparison
+      - focused Z.AI regression tests: 32 passed
+      - full regression suite: 2769 passed and 136 skipped
+      - remote callback GET 200 and state-bound result POST 204 from operator host
+      - operator Chrome traceless verification completed with a 280-byte result
+      - verification completion screenshot captured
+    pending:
+      - real Z.AI model response after CAPTCHA
+      - main, nightly, npm, and local deployment verification

package/docs/journal/2026/08/24/zai-start-plan-localhost-oauth-routing.okf

@@ -57,4 +57,18 @@ knowledge:
       source_installed_sha256_match: true
       start_plan_credential_status: connected
     release:
-      status: pending
+      status: passed
+      commit: 47605a5b71a2fc7dd7ead93269f5cf93c56cf66c
+      branches:
+        main: pushed
+        nightly: pushed
+      github_actions:
+        main_ci: success
+        main_npm_publish: success
+        nightly_ci: success
+        nightly_npm_publish: success
+      npm:
+        latest: 0.2.31
+        nightly: 0.2.31-nightly.20260824-142935.47605a5
+        latest_npx_version_verified: true
+        nightly_npx_version_verified: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneciel-ai/ciel-runtime",
-  "version": "0.2.31",
+  "version": "0.2.32",
   "description": "Universal AI coding-agent runtime and model-routing layer for Claude, Codex, AGY, ZCode, and compatible runtimes.",
   "license": "MIT",
   "author": "One Ciel LLC",