@oneciel-ai/ciel-runtime 0.2.23 → 0.2.24

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 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.24 — 2026-08-23
+
+- Added cross-platform Z.AI OAuth login through ZCode's CLI init/poll contract and
+  Coding Plan API-key resolution. Transient OAuth tokens remain in memory; Ciel
+  persists only the resolved API key through its existing credential store.
+- Added `ciel-runtimectl zai-oauth login|status|logout` with `--no-browser` support,
+  secret-free errors, and transaction-safe failure behavior.
+- Added official `glm-5.3` model metadata: 1M context, 128K maximum output, mandatory
+  thinking, and `low`/`high`/`max` reasoning-effort normalization.
+
 ## 0.2.23 — 2026-08-23
 
 This release promotes 41 commits developed and validated after `0.2.22`. The

package/README.md

@@ -163,6 +163,7 @@ Common commands:
 ciel-runtimectl provider [NAME]
 ciel-runtimectl models [PROVIDER]
 ciel-runtimectl model MODEL_ID
+ciel-runtimectl zai-oauth login
 ciel-runtimectl status
 ciel-runtimectl remote-memory
 ciel-runtimectl transcript-events

package/ciel_runtime.py

@@ -168,6 +168,7 @@ from ciel_runtime_support.credentials import resolve_anthropic_credentials
 from ciel_runtime_support.credentials import secret_fingerprint as project_secret_fingerprint
 from ciel_runtime_support.executable_discovery import ExecutableDiscovery
 from ciel_runtime_support.github_copilot_oauth_runtime import GitHubCopilotOAuthRuntime, GitHubCopilotOAuthRuntimePorts
+from ciel_runtime_support.zai_oauth import ZaiOAuthClient, ZaiOAuthHttp, ZaiOAuthRuntime, ZaiOAuthRuntimePorts, ZaiOAuthService
 from ciel_runtime_support.headless_config import HeadlessConfigCommands, HeadlessConfigServices, HeadlessEnvFileLoader, apply_headless_config
 from ciel_runtime_support.http_response import ChannelDeliveryGuard, HttpResponseAdapter
 from ciel_runtime_support.kimi_runtime_context import KimiConfigurationPorts, KimiIdentityPorts, KimiLifecyclePorts, KimiProcessPorts, KimiRuntimeCompatibilityApi, KimiRuntimeContext
@@ -3067,6 +3068,7 @@ def ensure_nvidia_hosted_base_url(pcfg: dict[str, Any]) -> bool:
 
 def nvidia_credential_repository() -> EnvCredentialRepository: return nvidia_env_credential_repository(NCP_ENV, read_env_file, parse_api_key_list, nvidia_upstream_base_url())
 def github_copilot_oauth_runtime() -> GitHubCopilotOAuthRuntime: return GitHubCopilotOAuthRuntime(CONFIG_DIR, GitHubCopilotOAuthRuntimePorts(clear_model_cache=clear_model_cache, log=router_log, provider_headers=provider_headers, network_open=provider_network.provider_urlopen))
+def zai_oauth_runtime() -> ZaiOAuthRuntime: return ZaiOAuthRuntime(ZaiOAuthService(ZaiOAuthClient(ZaiOAuthHttp())), ZaiOAuthRuntimePorts(load_config, save_config, clear_model_cache, mask_secret, secret_fingerprint, print))
 
 def provider_choice_controller() -> ProviderChoiceController:
     return ProviderChoiceController(
@@ -3185,7 +3187,7 @@ def provider_status_service() -> ProviderStatusService:
 
 def provider_administration_context() -> ProviderAdministrationContext:
     return ProviderAdministrationContext(
-        infrastructure=ProviderAdministrationInfrastructure(nvidia_credential_repository, github_copilot_oauth_runtime, print),
+        infrastructure=ProviderAdministrationInfrastructure(nvidia_credential_repository, github_copilot_oauth_runtime, zai_oauth_runtime, print),
         selection=ProviderAdministrationSelection(provider_choice_controller, provider_endpoint_service, model_selection_controller,
                                                    advisor_model_selection_controller),
         credentials=ProviderAdministrationCredentials(credential_management_service, credential_cli_controller, provider_config_api_keys,
@@ -3199,6 +3201,8 @@ clear_nvidia_api_key = _PROVIDER_ADMINISTRATION_API.clear_nvidia_api_key
 github_copilot_oauth_token = _PROVIDER_ADMINISTRATION_API.github_copilot_oauth_token
 cmd_copilot_oauth = _PROVIDER_ADMINISTRATION_API.cmd_copilot_oauth
 run_copilot_oauth_action = _PROVIDER_ADMINISTRATION_API.run_copilot_oauth_action
+cmd_zai_oauth = _PROVIDER_ADMINISTRATION_API.cmd_zai_oauth
+run_zai_oauth_action = _PROVIDER_ADMINISTRATION_API.run_zai_oauth_action
 set_provider_config = _PROVIDER_ADMINISTRATION_API.set_provider_config
 set_provider_choice_config = _PROVIDER_ADMINISTRATION_API.set_provider_choice_config
 set_base_url_config = _PROVIDER_ADMINISTRATION_API.set_base_url_config
@@ -3219,15 +3223,12 @@ def set_web_search_enabled(enabled: bool) -> None:
     cfg = load_config()
     cfg.setdefault("web_search", {})["auto_for_non_native"] = enabled
     save_config(cfg)
-
 def normalize_channel_delivery(value: Any) -> str:
     del value
     return "llm"
-
 def channel_delivery_mode(cfg: dict[str, Any] | None = None) -> str:
     del cfg
     return "llm"
-
 def channel_status_text(cfg: dict[str, Any] | None = None) -> str:
     del cfg
     return "Web Chat and explicit Ciel wake messages only"
@@ -4946,14 +4947,13 @@ def cli_services() -> cli_dispatch.CliServices:
         configuration=cli_dispatch.CliConfiguration(apply_auto_llm_options_config, apply_headless_env_config, set_advisor_model_config,
                                                     set_log_level_config, cmd_set_api_keys),
     ).services()
-
 def cli_parser_services() -> cli_parser.CliParserServices:
     return cli_assembly.CliParserAssembly(
             launch=cli_parser.CliParserLaunch(cmd_cli, cmd_launch, cmd_launch_codex, cmd_launch_codex_app_server, cmd_launch_agy, serve, cmd_launch_grok),
             runtime=cli_parser.CliParserRuntime(cmd_version, cmd_status, cmd_env, cmd_stop, cmd_test),
             settings=cli_parser.CliParserSettings(cmd_language, cmd_web_search, cmd_web_fetch, cmd_log_level, *event_settings_cli.handlers(event_settings_cli.EventSettingsCliPorts(load_config, save_config, external_event_receiver_service, lambda: set_remote_instruction_config('sync', ''), sync_all_remote_memories, print, lambda: USAGE_API_KEYS))),
             provider=cli_parser.CliParserProvider(cmd_ollama_native, cmd_ollama_options, cmd_provider_options, cmd_ollama_catalog, cmd_provider,
-                                                  cmd_api_key, cmd_set_api_key, cmd_set_api_keys, cmd_base_url, cmd_copilot_oauth),
+                                                  cmd_api_key, cmd_set_api_key, cmd_set_api_keys, cmd_base_url, {"copilot": cmd_copilot_oauth, "zai": cmd_zai_oauth}),
             models=cli_parser.CliParserModels(cmd_model, cmd_advisor_model, cmd_models),
     ).services()
 

package/ciel_runtime_support/cli_parser.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import argparse
 from dataclasses import dataclass
-from typing import Any, Callable
+from typing import Any, Callable, Mapping
 
 CliHandler = Callable[[argparse.Namespace], Any]
 
@@ -52,7 +52,7 @@ class CliParserProvider:
     set_api_key: CliHandler
     set_api_keys: CliHandler
     base_url: CliHandler
-    copilot_oauth: CliHandler
+    oauth: Mapping[str, CliHandler]
 
 
 @dataclass(frozen=True)
@@ -136,7 +136,16 @@ def build_cli_parser(services: CliParserServices) -> argparse.ArgumentParser:
         choices=("login", "status", "logout"),
         default="status",
     )
-    copilot_oauth.set_defaults(func=services.provider.copilot_oauth)
+    copilot_oauth.set_defaults(func=services.provider.oauth["copilot"])
+    zai_oauth = commands.add_parser("zai-oauth")
+    zai_oauth.add_argument(
+        "action",
+        nargs="?",
+        choices=("login", "status", "logout"),
+        default="status",
+    )
+    zai_oauth.add_argument("--no-browser", action="store_true")
+    zai_oauth.set_defaults(func=services.provider.oauth["zai"])
     _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")

package/ciel_runtime_support/provider_administration_context.py

@@ -21,6 +21,7 @@ class OAuthRuntime(Protocol):
 class ProviderAdministrationInfrastructure:
     nvidia_credentials: Callable[[], CredentialRepository]
     copilot_oauth: Callable[[], OAuthRuntime]
+    zai_oauth: Callable[[], OAuthRuntime]
     output: Callable[..., Any]
 
 
@@ -69,6 +70,19 @@ class ProviderAdministrationContext:
         for line in self.run_copilot_oauth_action(args.action):
             self.infrastructure.output(line, flush=True)
 
+    def run_zai_oauth_action(self, action: str, *, no_browser: bool = False) -> list[str]:
+        return self.infrastructure.zai_oauth().action(action, no_browser=no_browser)
+
+    def cmd_zai_oauth(self, args: argparse.Namespace) -> None:
+        try:
+            lines = self.run_zai_oauth_action(
+                args.action, no_browser=bool(getattr(args, "no_browser", False))
+            )
+        except RuntimeError as exc:
+            raise SystemExit(f"Z.AI OAuth failed: {exc}") from exc
+        for line in lines:
+            self.infrastructure.output(line, flush=True)
+
     def set_provider_config(self, provider: str) -> list[str]:
         return self.selection.provider_choice().select_standard(provider)
 
@@ -147,6 +161,12 @@ class ProviderAdministrationCompatibilityApi:
     def cmd_copilot_oauth(self, args: argparse.Namespace) -> None:
         self.context().cmd_copilot_oauth(args)
 
+    def run_zai_oauth_action(self, action: str, *, no_browser: bool = False) -> list[str]:
+        return self.context().run_zai_oauth_action(action, no_browser=no_browser)
+
+    def cmd_zai_oauth(self, args: argparse.Namespace) -> None:
+        self.context().cmd_zai_oauth(args)
+
     def set_provider_config(self, provider: str) -> list[str]:
         return self.context().set_provider_config(provider)
 

package/ciel_runtime_support/providers/constants.py

@@ -30,6 +30,8 @@ DEFAULT_REQUEST_TIMEOUT_MS = 300000
 OPENCODE_PROVIDER_NAMES = ("opencode", "opencode-go")
 
 ZAI_MODEL_FALLBACK_IDS: tuple[str, ...] = (
+    "glm-5.3[1m]",
+    "glm-5.3",
     "glm-5.2[1m]",
     "glm-5.2",
     "glm-5.1",

package/ciel_runtime_support/providers/zai.py

@@ -1,6 +1,7 @@
 """Z.AI provider adapter."""
 
 from dataclasses import dataclass, field
+from typing import Any, Mapping
 
 from ..architecture import (
     ProviderCapabilities,
@@ -21,23 +22,23 @@ class ZaiProviderAdapter(HttpBearerProviderAdapter):
     base_url: str = PROVIDER_DEFAULT_BASE_URLS["zai"]
     configuration_defaults_value: dict = field(
         default_factory=lambda: provider_configuration(
-            "glm-5.2[1m]",
+            "glm-5.3[1m]",
             custom_models=ZAI_MODEL_FALLBACK_IDS,
             native_compat=True,
             preserve_anthropic_thinking=True,
             claude_code_supported_capabilities=["effort", "thinking"],
             context_window=1000000,
             auto_compact_window=1000000,
-            max_output_tokens=8192,
-            context_reserve_tokens=8192,
+            max_output_tokens=131072,
+            context_reserve_tokens=131072,
             request_timeout_ms=3000000,
             stream_enabled=True,
             stream_word_chunking=False,
             effort_level="max",
-            opus_model="glm-5.2[1m]",
-            sonnet_model="glm-5.2[1m]",
+            opus_model="glm-5.3[1m]",
+            sonnet_model="glm-5.3[1m]",
             haiku_model="glm-4.7",
-            subagent_model="glm-5.2[1m]",
+            subagent_model="glm-5.3[1m]",
             managed_mcp=True,
         )
     )
@@ -80,6 +81,54 @@ class ZaiProviderAdapter(HttpBearerProviderAdapter):
             "sonnet_model": model_id,
         }
 
+    def model_configuration_profile(
+        self, config: ProviderConfig
+    ) -> tuple[Mapping[str, Any], str | None]:
+        model = self.normalize_model_id(config.model).split("[", 1)[0].lower()
+        if model != "glm-5.3":
+            return {}, None
+        return (
+            {
+                "context_window": 1_000_000,
+                "max_model_len": 1_000_000,
+                "auto_compact_window": 1_000_000,
+                "max_output_tokens": 131_072,
+                "context_reserve_tokens": 131_072,
+                "effort_level": "max",
+                "model_profile": "glm-5.3-1m",
+            },
+            "GLM-5.3 profile applied: 1M context, 128K maximum output, and max reasoning effort. Start a new session.",
+        )
+
+    def normalize_request_options(
+        self, config: ProviderConfig, request: Mapping[str, Any]
+    ) -> Mapping[str, Any]:
+        model = self.normalize_model_id(str(request.get("model") or config.model))
+        model = model.split("[", 1)[0].lower()
+        if model != "glm-5.3":
+            return request
+        normalized = dict(request)
+        thinking = request.get("thinking")
+        normalized["thinking"] = {
+            **(dict(thinking) if isinstance(thinking, Mapping) else {}),
+            "type": "enabled",
+        }
+        effort = str(
+            request.get("reasoning_effort")
+            or config.options.get("effort_level")
+            or "max"
+        ).strip().lower()
+        normalized["reasoning_effort"] = {
+            "none": "low",
+            "minimal": "low",
+            "medium": "high",
+            "xhigh": "max",
+            "ultra": "max",
+        }.get(effort, effort if effort in {"low", "high", "max"} else "max")
+        if "temperature" in normalized:
+            normalized["temperature"] = 1.0
+        return normalized
+
     def context_policy(self, config: ProviderConfig) -> ProviderContextPolicy:
         del config
         return ProviderContextPolicy(

package/ciel_runtime_support/runtime_constants.py

@@ -37,9 +37,9 @@ KIMI_MODEL_FALLBACK_IDS = (
     KIMI_HIGHSPEED_MODEL,
 )
 ZAI_ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic"
-ZAI_DEFAULT_MODEL = "glm-5.2[1m]"
+ZAI_DEFAULT_MODEL = "glm-5.3[1m]"
 ZAI_MODEL_CONTEXT_HINTS = (
-    ("glm-5.2", 1_000_000), ("glm-5-turbo", 200_000), ("glm-5.1", 200_000),
+    ("glm-5.3", 1_000_000), ("glm-5.2", 1_000_000), ("glm-5-turbo", 200_000), ("glm-5.1", 200_000),
     ("glm-5", 200_000), ("glm-4.7", 200_000), ("glm-4.6", 200_000),
     ("glm-4.5", 128_000), ("glm-4-32b-0414-128k", 128_000),
 )
@@ -87,7 +87,7 @@ OPENCODE_ENDPOINT_ALIASES = {
 }
 
 APP_NAME = "Ciel Runtime"
-VERSION = "0.2.23"
+VERSION = "0.2.24"
 CREDITS = "Credits: One Ciel LLC"
 PRELAUNCH_CANCEL = 10
 PRELAUNCH_LAUNCH_CODEX = 11
@@ -171,6 +171,8 @@ ROUTED_CODEX_COMPAT_PROMPT = (
 )
 LANGUAGES = {"en": "English", "ko": "한국어", "ja": "日本語", "zh": "中文"}
 MODEL_PRESETS: dict[str, dict[str, Any]] = {
+    "glm-5.3": {"compat_max_tokens": 64, "thinking": True, "num_ctx_min": 32768, "num_ctx_max": 1000000},
+    "glm-5.3:cloud": {"compat_max_tokens": 64, "thinking": True, "num_ctx_min": 32768, "num_ctx_max": 1000000},
     "deepseek-v4-flash:0731": {"compat_max_tokens": 64, "thinking": True, "num_ctx_min": 32768, "num_ctx_max": 1000000},
     "deepseek-v4-flash:0731-cloud": {"compat_max_tokens": 64, "thinking": True, "num_ctx_min": 32768, "num_ctx_max": 1000000},
     "glm-5.2": {"compat_max_tokens": 64, "thinking": True, "num_ctx_min": 32768, "num_ctx_max": 1000000},

package/ciel_runtime_support/zai_oauth.py

@@ -0,0 +1,362 @@
+"""Z.AI CLI OAuth and Coding Plan API-key resolution.
+
+The wire contract mirrors the cross-platform init/poll flow exposed by the
+ZCode runtime.  Ciel stores only the final Coding Plan API key; transient OAuth
+access tokens and ZCode JWTs are deliberately kept in memory.
+"""
+
+from __future__ import annotations
+
+import json
+import secrets
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import webbrowser
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Callable, Mapping
+
+
+ZCODE_OAUTH_BASE_URL = "https://zcode.z.ai/api/v1"
+ZAI_BUSINESS_BASE_URL = "https://api.z.ai"
+ZAI_OAUTH_PROVIDER = "zai"
+ZAI_CODING_PLAN_KEY_NAME = "zcode-api-key"
+ZAI_OAUTH_TIMEOUT_SECONDS = 300.0
+
+
+class ZaiOAuthError(RuntimeError):
+    """A bounded, secret-free OAuth diagnostic."""
+
+
+@dataclass(frozen=True, slots=True)
+class ZaiOAuthInit:
+    flow_id: str
+    authorize_url: str
+    expires_at: float
+    poll_interval_seconds: float
+
+
+@dataclass(frozen=True, slots=True)
+class ZaiOAuthResult:
+    api_key: str
+    user_id: str
+
+
+class ZaiOAuthHttp:
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        body: Mapping[str, Any] | None = None,
+        timeout: float = 30.0,
+    ) -> Any:
+        payload = (
+            json.dumps(body, separators=(",", ":")).encode("utf-8")
+            if body is not None
+            else None
+        )
+        request = urllib.request.Request(
+            url,
+            data=payload,
+            headers=dict(headers or {}),
+            method=method,
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                raw = response.read(1_048_577)
+        except urllib.error.HTTPError as exc:
+            raise ZaiOAuthError(f"Z.AI OAuth HTTP {exc.code} at {url}") from exc
+        except urllib.error.URLError as exc:
+            reason = type(exc.reason).__name__ if exc.reason is not None else "network_error"
+            raise ZaiOAuthError(f"Z.AI OAuth network error ({reason}) at {url}") from exc
+        if len(raw) > 1_048_576:
+            raise ZaiOAuthError("Z.AI OAuth response exceeded 1 MiB.")
+        try:
+            return json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise ZaiOAuthError("Z.AI OAuth returned invalid JSON.") from exc
+
+
+@dataclass(frozen=True, slots=True)
+class ZaiOAuthClient:
+    http: Any
+    oauth_base_url: str = ZCODE_OAUTH_BASE_URL
+    business_base_url: str = ZAI_BUSINESS_BASE_URL
+
+    def initialize(self, poll_token: str) -> ZaiOAuthInit:
+        data = self._oauth_data(
+            "POST",
+            f"{self.oauth_base_url.rstrip('/')}/oauth/cli/init",
+            poll_token,
+            body={"provider": ZAI_OAUTH_PROVIDER},
+        )
+        flow_id = self._required_string(data, "flow_id", "OAuth init")
+        authorize_url = self._required_string(data, "authorize_url", "OAuth init")
+        parsed = urllib.parse.urlparse(authorize_url)
+        if parsed.scheme != "https" or not parsed.netloc:
+            raise ZaiOAuthError("Z.AI OAuth init returned an unsafe authorization URL.")
+        try:
+            expires_at = float(data["expires_at"])
+            interval = max(1.0, float(data["poll_interval_sec"]))
+        except (KeyError, TypeError, ValueError) as exc:
+            raise ZaiOAuthError("Z.AI OAuth init returned invalid timing fields.") from exc
+        return ZaiOAuthInit(flow_id, authorize_url, expires_at, interval)
+
+    def poll(self, flow_id: str, poll_token: str) -> Mapping[str, Any]:
+        safe_flow_id = urllib.parse.quote(flow_id, safe="")
+        data = self._oauth_data(
+            "GET",
+            f"{self.oauth_base_url.rstrip('/')}/oauth/cli/poll/{safe_flow_id}",
+            poll_token,
+        )
+        status = str(data.get("status") or "").strip().lower()
+        if status not in {"pending", "failed", "ready"}:
+            raise ZaiOAuthError("Z.AI OAuth poll returned an invalid status.")
+        return data
+
+    def resolve_coding_plan_api_key(self, oauth_access_token: str) -> str:
+        login = self._business_data(
+            "POST",
+            "/api/auth/z/login",
+            body={"token": oauth_access_token},
+        )
+        biz_token = self._required_string(login, "access_token", "business login")
+        auth = {"Authorization": f"Bearer {biz_token}", "Content-Type": "application/json"}
+        customer = self._business_data(
+            "GET", "/api/biz/customer/getCustomerInfo", headers=auth
+        )
+        organization_id, project_id = self._organization_project(customer)
+        key_path = (
+            f"/api/biz/v1/organization/{urllib.parse.quote(organization_id, safe='')}"
+            f"/projects/{urllib.parse.quote(project_id, safe='')}/api_keys"
+        )
+        keys = self._business_data("GET", key_path, headers=auth)
+        key_id = ""
+        if isinstance(keys, list):
+            for item in keys:
+                if isinstance(item, Mapping) and item.get("name") == ZAI_CODING_PLAN_KEY_NAME:
+                    key_id = str(item.get("apiKey") or "").strip()
+                    if key_id:
+                        break
+        if not key_id:
+            created = self._business_data(
+                "POST", key_path, headers=auth, body={"name": ZAI_CODING_PLAN_KEY_NAME}
+            )
+            key_id = self._required_string(created, "apiKey", "API-key creation")
+        copied = self._business_data(
+            "GET",
+            f"{key_path}/copy/{urllib.parse.quote(key_id, safe='')}",
+            headers=auth,
+        )
+        secret = self._required_string(copied, "secretKey", "API-key copy")
+        return f"{key_id}.{secret}"
+
+    def _oauth_data(
+        self,
+        method: str,
+        url: str,
+        poll_token: str,
+        *,
+        body: Mapping[str, Any] | None = None,
+    ) -> Mapping[str, Any]:
+        response = self.http.request(
+            method,
+            url,
+            headers={
+                "Authorization": f"Bearer {poll_token}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+            body=body,
+        )
+        return self._envelope_data(response, "OAuth")
+
+    def _business_data(
+        self,
+        method: str,
+        path: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        body: Mapping[str, Any] | None = None,
+    ) -> Any:
+        response = self.http.request(
+            method,
+            f"{self.business_base_url.rstrip('/')}{path}",
+            headers=headers or {"Content-Type": "application/json"},
+            body=body,
+        )
+        return self._envelope_data(response, "business API")
+
+    @staticmethod
+    def _envelope_data(response: Any, label: str) -> Any:
+        if not isinstance(response, Mapping):
+            raise ZaiOAuthError(f"Z.AI {label} returned an invalid envelope.")
+        code = response.get("code")
+        if code not in {None, 0, 200, "0", "200"}:
+            raise ZaiOAuthError(f"Z.AI {label} rejected the request (code {code}).")
+        return response.get("data")
+
+    @staticmethod
+    def _required_string(data: Any, key: str, label: str) -> str:
+        value = data.get(key) if isinstance(data, Mapping) else None
+        text = str(value or "").strip()
+        if not text:
+            raise ZaiOAuthError(f"Z.AI {label} response is missing {key}.")
+        return text
+
+    @staticmethod
+    def _organization_project(data: Any) -> tuple[str, str]:
+        organizations = data.get("organizations") if isinstance(data, Mapping) else None
+        if not isinstance(organizations, list) or not organizations:
+            raise ZaiOAuthError("Z.AI account has no organization available for Coding Plan.")
+        organization = next(
+            (
+                item
+                for item in organizations
+                if isinstance(item, Mapping) and "默认机构" in str(item.get("organizationName") or "")
+            ),
+            organizations[0],
+        )
+        if not isinstance(organization, Mapping):
+            raise ZaiOAuthError("Z.AI organization response is invalid.")
+        projects = organization.get("projects")
+        if not isinstance(projects, list) or not projects:
+            raise ZaiOAuthError("Z.AI account has no project available for Coding Plan.")
+        project = next(
+            (
+                item
+                for item in projects
+                if isinstance(item, Mapping) and "默认项目" in str(item.get("projectName") or "")
+            ),
+            projects[0],
+        )
+        organization_id = str(organization.get("organizationId") or "").strip()
+        project_id = str(project.get("projectId") or "").strip() if isinstance(project, Mapping) else ""
+        if not organization_id or not project_id:
+            raise ZaiOAuthError("Z.AI organization/project identifiers are missing.")
+        return organization_id, project_id
+
+
+@dataclass(frozen=True, slots=True)
+class ZaiOAuthService:
+    client: ZaiOAuthClient
+    now: Callable[[], float] = time.time
+    sleep: Callable[[float], None] = time.sleep
+    open_url: Callable[[str], bool] = webbrowser.open
+    timeout_seconds: float = ZAI_OAUTH_TIMEOUT_SECONDS
+
+    def login(self, *, no_browser: bool = False, on_authorize_url: Callable[[str], None]) -> ZaiOAuthResult:
+        poll_token = secrets.token_hex(32)
+        initialized = self.client.initialize(poll_token)
+        on_authorize_url(initialized.authorize_url)
+        if not no_browser:
+            self.open_url(initialized.authorize_url)
+        deadline = min(self.now() + self.timeout_seconds, initialized.expires_at)
+        while self.now() < deadline:
+            result = self.client.poll(initialized.flow_id, poll_token)
+            status = str(result.get("status") or "")
+            if status == "failed":
+                raise ZaiOAuthError("Z.AI OAuth authorization was denied or failed.")
+            if status == "ready":
+                zai = result.get("zai")
+                access_token = (
+                    str(zai.get("access_token") or "").strip()
+                    if isinstance(zai, Mapping)
+                    else ""
+                )
+                user = result.get("user")
+                user_id = (
+                    str(user.get("user_id") or "").strip()
+                    if isinstance(user, Mapping)
+                    else ""
+                )
+                if not access_token or not user_id:
+                    raise ZaiOAuthError("Z.AI OAuth ready response is missing credentials or user identity.")
+                api_key = self.client.resolve_coding_plan_api_key(access_token)
+                return ZaiOAuthResult(api_key=api_key, user_id=user_id)
+            self.sleep(min(initialized.poll_interval_seconds, max(0.0, deadline - self.now())))
+        raise ZaiOAuthError("Z.AI OAuth authorization timed out.")
+
+
+@dataclass(frozen=True, slots=True)
+class ZaiOAuthRuntimePorts:
+    load_config: Callable[[], dict[str, Any]]
+    save_config: Callable[[dict[str, Any]], None]
+    clear_model_cache: Callable[[], None]
+    mask: Callable[[str], str]
+    fingerprint: Callable[[str], str]
+    output: Callable[..., Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ZaiOAuthRuntime:
+    service: ZaiOAuthService
+    ports: ZaiOAuthRuntimePorts
+
+    def token(self) -> str:
+        config = self.ports.load_config()
+        provider = config.get("providers", {}).get("zai", {})
+        if provider.get("credential_source") != "zai-oauth":
+            return ""
+        return str(provider.get("api_key") or "").strip()
+
+    def action(self, action: str, *, no_browser: bool = False) -> list[str]:
+        if action == "status":
+            token = self.token()
+            if not token:
+                return ["Z.AI OAuth: not connected."]
+            return [
+                "Z.AI OAuth: connected (Coding Plan API key).",
+                f"Credential: {self.ports.mask(token)}; fp {self.ports.fingerprint(token)}",
+            ]
+        if action == "logout":
+            config = self.ports.load_config()
+            provider = config.get("providers", {}).get("zai", {})
+            if provider.get("credential_source") != "zai-oauth":
+                return ["Z.AI OAuth: no OAuth-derived local credential to clear."]
+            provider.pop("api_key", None)
+            provider.pop("api_keys", None)
+            provider.pop("credential_source", None)
+            provider.pop("oauth_authenticated_at", None)
+            provider.pop("oauth_user_id", None)
+            self.ports.save_config(config)
+            self.ports.clear_model_cache()
+            return ["Z.AI OAuth-derived local credential cleared. Remote authorization was not revoked."]
+        if action != "login":
+            return [f"Unsupported Z.AI OAuth action: {action}"]
+        result = self.service.login(
+            no_browser=no_browser,
+            on_authorize_url=lambda url: self.ports.output(
+                f"Open this URL to authorize Z.AI:\n{url}", flush=True
+            ),
+        )
+        config = self.ports.load_config()
+        provider = config.setdefault("providers", {}).setdefault("zai", {})
+        provider["api_key"] = result.api_key
+        provider.pop("api_keys", None)
+        provider["credential_source"] = "zai-oauth"
+        provider["oauth_authenticated_at"] = datetime.now(timezone.utc).isoformat()
+        provider["oauth_user_id"] = result.user_id
+        config["current_provider"] = "zai"
+        self.ports.save_config(config)
+        self.ports.clear_model_cache()
+        return [
+            "Z.AI OAuth login completed; the resolved Coding Plan API key is active.",
+            f"Credential: {self.ports.mask(result.api_key)}; fp {self.ports.fingerprint(result.api_key)}",
+        ]
+
+
+__all__ = [
+    "ZaiOAuthClient",
+    "ZaiOAuthError",
+    "ZaiOAuthHttp",
+    "ZaiOAuthInit",
+    "ZaiOAuthResult",
+    "ZaiOAuthRuntime",
+    "ZaiOAuthRuntimePorts",
+    "ZaiOAuthService",
+]

package/docs/CLI-Reference.md

@@ -94,6 +94,20 @@ ciel-runtimectl base-url ollama http://remote-server:11434
 
 ### API 키 관리
 
+#### `zai-oauth`
+
+```bash
+ciel-runtimectl zai-oauth login
+ciel-runtimectl zai-oauth login --no-browser
+ciel-runtimectl zai-oauth status
+ciel-runtimectl zai-oauth logout
+```
+
+ZCode CLI의 Z.AI init/poll OAuth 흐름으로 로그인하고 Coding Plan API key를
+발급한다. `--no-browser`는 인증 URL만 출력한다. Ciel은 OAuth access token이나
+ZCode JWT를 디스크에 저장하지 않는다. `logout`은 OAuth로 만든 로컬 API key만
+지우며 원격 승인을 철회하지 않는다.
+
 #### `api-key`
 ```bash
 ciel-runtimectl api-key [PROVIDER] [KEY]

package/docs/Providers.md

@@ -182,12 +182,16 @@ Anthropic thinking 객체나 문서로 확인되지 않은 GLM-5.2 effort 문자
 ## ZAI (Z.AI GLM)
 
 - GLM 시리즈 모델 제공.
-- 기본 모델: `glm-5.2[1m]`
+- 기본 모델: `glm-5.3[1m]`
+- ZCode CLI와 동일한 init/poll OAuth 흐름: `ciel-runtimectl zai-oauth login`
+- OAuth access token과 ZCode JWT는 메모리에만 유지하고, 최종 Coding Plan API key만 기존 Ciel credential 규칙으로 저장한다.
+- GLM-5.3은 reasoning을 끌 수 없으며 `low`, `high`, `max` effort만 사용한다.
 - Managed MCP 서버 포함: `web-search-prime`, `web-reader`, `zread`
 - 컨텍스트 힌트:
 
 | 모델 접두사 | 컨텍스트 |
 |-----------|---------|
+| `glm-5.3` | 1,000,000 |
 | `glm-5.2` | 1,000,000 |
 | `glm-5-turbo` | 200,000 |
 | `glm-4.7` | 200,000 |

package/docs/journal/2026/08/23/main-0.2.23-readme-release.okf

@@ -8,7 +8,7 @@ knowledge:
       Audit every commit after 0.2.22, redesign the project README using
       verified patterns from established CLI repositories, publish grouped
       release notes, bump the version, and promote the result to main.
-    status: local-verification-complete
+    status: complete
 
   evidence:
     release_base:
@@ -75,7 +75,28 @@ knowledge:
       path: C:/Users/djlov/.local/share/ciel-runtime
       reported_version: 0.2.23
       source_hash_matches: 5
-    remaining:
-      - nightly publish and clean registry install
-      - main CI and stable npm publish
-      - rendered GitHub README screenshot
+    nightly:
+      status: passed
+      version: 0.2.23-nightly.20260824-024159.9e69d66
+      source_commit: 9e69d66883d0d0f29280a774ec7c1706cdccd9d9
+      ci_run: 32683800367
+      publish_run: 32683800229
+      registry_git_head_matched: true
+      clean_install_reported_version: 0.2.23-nightly.20260824-024159.9e69d66
+      runtime_constants_difference: nightly version substitution only
+    stable:
+      status: passed
+      version: 0.2.23
+      source_commit: 9e69d66883d0d0f29280a774ec7c1706cdccd9d9
+      ci_run: 32683988165
+      publish_run: 32683988114
+      registry_git_head_matched: true
+      clean_install_reported_version: 0.2.23
+      source_hash_matches: 7
+    rendered_readme:
+      status: passed
+      url: https://github.com/OneCielAI/ciel-runtime?tab=readme-ov-file#readme
+      visible_sections: [hero, badges, navigation, why, install]
+      npm_badge: v0.2.23
+      ci_badge: passing
+      screenshot_captured: true

package/docs/journal/2026/08/23/zcode-zai-oauth-glm53-support.okf

@@ -0,0 +1,62 @@
+{
+  "okf": "1.0",
+  "task": {
+    "id": "zcode-zai-oauth-glm53-support",
+    "date": "2026-08-23",
+    "request": "Analyze the ZCode CLI open-source implementation, add Z.AI OAuth login, and add GLM-5.3 support."
+  },
+  "evidence": {
+    "zcode_wrapper": {
+      "repository": "https://github.com/kingsword09/zcode-cli",
+      "revision": "ce2dcfbdeee3e5cca54095fbe1191fb2d03c10db",
+      "package_observed": "zcode-app-cli 3.8.1-15",
+      "status": "unofficial MIT wrapper around the bundled ZCode runtime",
+      "confirmed": [
+        "The wrapper authorization-code callback is zcode://zai-auth/callback.",
+        "The bundled runtime exposes a cross-platform oauth/cli/init and oauth/cli/poll flow.",
+        "The runtime resolves the OAuth access token into a Coding Plan API key and writes CLI configuration."
+      ]
+    },
+    "zai_official": {
+      "model_document": "https://docs.z.ai/guides/llm/glm-5.3",
+      "api_reference": "https://docs.z.ai/api-reference/llm/chat-completion",
+      "confirmed": [
+        "Model ID is glm-5.3.",
+        "Context window is 1,000,000 tokens and maximum output is 131,072 tokens.",
+        "Thinking is always enabled and reasoning_effort supports low, high, and max.",
+        "Anthropic base URL is https://api.z.ai/api/anthropic."
+      ]
+    },
+    "live_probe": {
+      "command_surface": "POST https://zcode.z.ai/api/v1/oauth/cli/init",
+      "observed_result": "HTTP 404 with an empty response on 2026-08-23 from this workstation",
+      "control": "The same result was reproduced by invoking the bundled zcode.cjs login command directly.",
+      "config_unchanged": true,
+      "conclusion": "The local implementation cannot claim a completed live login while the upstream initialization endpoint returns 404."
+    }
+  },
+  "implementation": {
+    "oauth": [
+      "Added bounded init/poll client and browser/no-browser service.",
+      "Added Coding Plan organization/project/API-key resolution.",
+      "Persists only the final API key after the complete flow succeeds.",
+      "A failed flow does not mutate configuration; logout does not remove manually configured keys."
+    ],
+    "glm_5_3": [
+      "Added catalog/default/context metadata.",
+      "Added mandatory thinking and reasoning effort normalization.",
+      "Added a 1M context and 128K output provider profile."
+    ]
+  },
+  "verification": {
+    "targeted": "33 passed",
+    "unit": "1165 passed, 44 skipped",
+    "router": "929 passed",
+    "channel": "381 passed, 80 skipped",
+    "runtime": "252 passed, 12 skipped",
+    "aggregate": "2727 passed, 136 skipped",
+    "package_dry_run": "oneciel-ai-ciel-runtime-0.2.24.tgz; 415 files; 947347 bytes packed; 4335786 bytes unpacked",
+    "local_deployment": "installed into C:\\Users\\djlov\\.local\\share\\ciel-runtime; installed wrapper reported 0.2.24 and zai-oauth status exited 0",
+    "live_oauth": "blocked by confirmed upstream HTTP 404; no local credential or config was changed"
+  }
+}

package/package.json

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