@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/slash_command_assets.py

@@ -0,0 +1,211 @@
+"""Static Claude slash-command documents installed by Ciel Runtime."""
+
+VERSION_SLASH_COMMAND = """---
+description: Show ciel-runtime version
+argument-hint: [ignored]
+---
+
+CIEL_RUNTIME_VERSION_STATUS
+
+Show the running ciel-runtime version for this session. This command is handled locally by the ciel-runtime router and must not be forwarded upstream.
+"""
+
+ADVISOR_SLASH_COMMAND = """---
+description: Run the selected ciel-runtime Advisor Model
+argument-hint: [question or focus]
+---
+
+CIEL_RUNTIME_ADVISOR_CALL
+
+Focus: $ARGUMENTS
+
+Use the Advisor Model selected in the ciel-runtime launch menu. If the Advisor Model is off, explain how to enable it. Otherwise review the current conversation, tool history, and task state. Return concise guidance with the blocker, next concrete action, and validation step.
+"""
+
+
+ADVISOR_NATIVE_DISABLED_SLASH_COMMAND = """---
+description: Ciel Runtime Advisor unavailable in Claude Native mode
+argument-hint: [ignored]
+---
+
+Ciel Runtime Advisor is unavailable in direct Claude Native mode.
+
+Do not run tools, shell commands, file searches, config scans, or environment checks for this command. Reply immediately with this exact status and the short enablement hint below.
+
+This session bypasses the ciel-runtime router, so /advisor cannot call the configured Advisor Model here. To use /advisor, launch a non-native provider or enable Anthropic routed mode in ciel-runtime.
+"""
+
+
+ROUTER_DEBUG_SLASH_COMMAND = """---
+description: Toggle ciel-runtime router external debug access
+argument-hint: [on|off|status]
+---
+
+CIEL_RUNTIME_ROUTER_DEBUG_ACCESS
+
+Value: $ARGUMENTS
+
+Toggle ciel-runtime router debug external access. With no argument, this toggles the current state. Use `on`, `off`, or `status` for explicit control.
+"""
+
+
+ROUTER_DEBUG_NATIVE_DISABLED_SLASH_COMMAND = """---
+description: ciel-runtime router debug unavailable in Claude Native mode
+argument-hint: [ignored]
+---
+
+ciel-runtime router debug controls are unavailable in direct Claude Native mode.
+
+Do not run tools, shell commands, file searches, config scans, or environment checks for this command. Reply immediately with this exact status and the short enablement hint below.
+
+This session bypasses the ciel-runtime router. Launch a non-native provider or enable Anthropic routed mode to use /router-debug.
+"""
+
+
+LLM_SLIDER_SLASH_COMMAND = """---
+description: Move/select ciel-runtime live LLM preset slider
+argument-hint: [left|right|status|list|restore|preset-id]
+---
+
+CIEL_RUNTIME_LIVE_LLM_OPTIONS
+
+Value: $0
+Arguments: $ARGUMENTS
+
+Use one compact ciel-runtime live LLM preset control. With no argument, show the current slider. Use `left` or `right` to move one preset, `restore` to return to captured options, or a preset id/alias such as `coding`, `300k`, `512k`, or `1m`.
+"""
+
+
+LLM_OPTIONS_SLASH_COMMAND = """---
+description: Show or change ciel-runtime live LLM options
+argument-hint: [left|right|status|list|restore|preset-id]
+---
+
+CIEL_RUNTIME_LIVE_LLM_OPTIONS
+
+Value: $0
+Arguments: $ARGUMENTS
+
+Show or change the live ciel-runtime LLM preset for this routed session. With no argument, show status and the compact preset slider. Use `left` or `right` to move one preset, `restore` to return to captured options, or a preset id/alias such as `coding`, `300k`, `512k`, or `1m`.
+"""
+
+
+LLM_RESTORE_SLASH_COMMAND = """---
+description: Restore ciel-runtime live LLM options
+argument-hint: [ignored]
+---
+
+CIEL_RUNTIME_LIVE_LLM_OPTIONS
+
+Value: restore
+
+Restore the LLM options captured before the first live preset change in this routed session.
+"""
+
+
+CHANNEL_CLEAR_SLASH_COMMAND = """---
+description: Discard pending ciel-runtime external channel backlog
+argument-hint: [all|status]
+---
+
+CIEL_RUNTIME_CHANNEL_CLEAR_BACKLOG
+
+Value: $ARGUMENTS
+
+Discard pending ciel-runtime external channel backlog without sending it to the model. Use `status` to show pending counts without clearing.
+"""
+
+
+API_KEYS_SLASH_COMMAND = """---
+description: Set/show ciel-runtime live API key(s)
+argument-hint: [status|clear|KEY|KEY1,KEY2]
+---
+
+Set API key(s) for the current ciel-runtime provider without restarting Claude Code. With no argument, show masked key status. Use `clear` or `unset` to remove keys for only the current provider. Multiple keys may be comma-, semicolon-, or newline-separated and are used round-robin. Never print raw keys.
+
+CIEL_RUNTIME_LIVE_API_KEYS
+
+Value: $0
+Arguments:
+$ARGUMENTS
+"""
+
+
+IMPORT_SESSION_SLASH_COMMAND = """---
+description: Import a Claude/Codex session transcript into this session
+argument-hint: Codex|Claude [transcript-path]
+---
+
+CIEL_RUNTIME_IMPORT_SESSION
+
+Target: $1
+Path: $2
+Arguments: $ARGUMENTS
+
+Import a session transcript into the current Ciel Runtime-routed session. `Target` names the source transcript format and must be `Codex` or `Claude`.
+"""
+
+
+LEGACY_MARKER_PREFIX = "CLAUDE" + "_ANY"
+LEGACY_ADVISOR_CALL_MARKER = LEGACY_MARKER_PREFIX + "_ADVISOR_CALL"
+LEGACY_ROUTER_DEBUG_ACCESS_MARKER = LEGACY_MARKER_PREFIX + "_ROUTER_DEBUG_ACCESS"
+LEGACY_LIVE_LLM_OPTIONS_MARKER = LEGACY_MARKER_PREFIX + "_LIVE_LLM_OPTIONS"
+LEGACY_CHANNEL_CLEAR_BACKLOG_MARKER = LEGACY_MARKER_PREFIX + "_CHANNEL_CLEAR_BACKLOG"
+LEGACY_LIVE_API_KEYS_MARKER = LEGACY_MARKER_PREFIX + "_LIVE_API_KEYS"
+
+ADVISOR_REQUEST_MARKERS = ("CIEL_RUNTIME_ADVISOR_CALL", LEGACY_ADVISOR_CALL_MARKER)
+ROUTER_DEBUG_REQUEST_MARKERS = (
+    "CIEL_RUNTIME_ROUTER_DEBUG_ACCESS",
+    LEGACY_ROUTER_DEBUG_ACCESS_MARKER,
+)
+VERSION_REQUEST_MARKERS = ("CIEL_RUNTIME_VERSION_STATUS",)
+LIVE_LLM_OPTIONS_REQUEST_MARKERS = (
+    "CIEL_RUNTIME_LIVE_LLM_OPTIONS",
+    LEGACY_LIVE_LLM_OPTIONS_MARKER,
+)
+CHANNEL_CLEAR_REQUEST_MARKERS = (
+    "CIEL_RUNTIME_CHANNEL_CLEAR_BACKLOG",
+    LEGACY_CHANNEL_CLEAR_BACKLOG_MARKER,
+)
+LIVE_API_KEYS_REQUEST_MARKERS = (
+    "CIEL_RUNTIME_LIVE_API_KEYS",
+    LEGACY_LIVE_API_KEYS_MARKER,
+)
+IMPORT_SESSION_REQUEST_MARKERS = ("CIEL_RUNTIME_IMPORT_SESSION",)
+
+CIEL_RUNTIME_ADVISOR_COMMAND_MARKERS = (
+    "CIEL_RUNTIME_ADVISOR_CALL",
+    "Run the selected ciel-runtime Advisor Model",
+    "Ciel Runtime Advisor is unavailable in direct Claude Native mode",
+    LEGACY_ADVISOR_CALL_MARKER,
+)
+CIEL_RUNTIME_ROUTER_DEBUG_COMMAND_MARKERS = (
+    "CIEL_RUNTIME_ROUTER_DEBUG_ACCESS",
+    "Toggle ciel-runtime router external debug access",
+    "ciel-runtime router debug controls are unavailable in direct Claude Native mode",
+    LEGACY_ROUTER_DEBUG_ACCESS_MARKER,
+)
+CIEL_RUNTIME_VERSION_COMMAND_MARKERS = (
+    "CIEL_RUNTIME_VERSION_STATUS",
+    "Show ciel-runtime version",
+)
+CIEL_RUNTIME_LLM_OPTIONS_COMMAND_MARKERS = (
+    "CIEL_RUNTIME_LIVE_LLM_OPTIONS",
+    "Show or change ciel-runtime live LLM options",
+    "Restore ciel-runtime live LLM options",
+    LEGACY_LIVE_LLM_OPTIONS_MARKER,
+)
+CIEL_RUNTIME_CHANNEL_CLEAR_COMMAND_MARKERS = (
+    "CIEL_RUNTIME_CHANNEL_CLEAR_BACKLOG",
+    "Discard pending ciel-runtime external channel backlog",
+    LEGACY_CHANNEL_CLEAR_BACKLOG_MARKER,
+)
+CIEL_RUNTIME_API_KEYS_COMMAND_MARKERS = (
+    "CIEL_RUNTIME_LIVE_API_KEYS",
+    "Set/show ciel-runtime live API key(s)",
+    LEGACY_LIVE_API_KEYS_MARKER,
+)
+CIEL_RUNTIME_IMPORT_SESSION_COMMAND_MARKERS = (
+    "CIEL_RUNTIME_IMPORT_SESSION",
+    "Import a Claude/Codex session transcript",
+)

package/ciel_runtime_support/sse_stream.py

@@ -0,0 +1,57 @@
+"""Reusable Server-Sent Events stream parser and dispatch loop."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+@dataclass(frozen=True, slots=True)
+class SseStreamServices:
+    should_continue: Callable[[], bool]
+    dispatch: Callable[[str, list[str], str | None], Any]
+    invalid_retry: Callable[[str], Any]
+
+
+@dataclass(slots=True)
+class SseRetryState:
+    seconds: float
+
+
+def consume_sse_stream(
+    response: Any,
+    retry: SseRetryState,
+    end_message: str,
+    services: SseStreamServices,
+) -> None:
+    event_name = "message"
+    event_id: str | None = None
+    data_lines: list[str] = []
+    while services.should_continue():
+        raw = response.readline()
+        if raw == b"":
+            raise ConnectionError(end_message)
+        line = raw.decode("utf-8", errors="replace").rstrip("\r\n")
+        if not line:
+            if data_lines:
+                services.dispatch(event_name, data_lines, event_id)
+            event_name = "message"
+            event_id = None
+            data_lines = []
+            continue
+        if line.startswith(":"):
+            continue
+        field, _, value = line.partition(":")
+        if value.startswith(" "):
+            value = value[1:]
+        if field == "event":
+            event_name = value or "message"
+        elif field == "data":
+            data_lines.append(value)
+        elif field == "id":
+            event_id = value
+        elif field == "retry":
+            try:
+                retry.seconds = max(1.0, min(60.0, int(value) / 1000.0))
+            except (TypeError, ValueError):
+                services.invalid_retry(value)

package/ciel_runtime_support/sse_trace.py

@@ -0,0 +1,225 @@
+"""Bounded SSE event tracing and tool-call JSONL observability."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class SseTraceConfig:
+    config_dir: Path
+    last_path: Path
+    trace_path: Path
+    tool_call_path: Path
+    event_limit: int
+    payload_limit: int
+    max_bytes: int
+
+
+@dataclass(frozen=True, slots=True)
+class SseTracePorts:
+    enabled: Callable[[], bool]
+    truncate: Callable[[str, int], str]
+    log: Callable[[str, str], None]
+
+
+def summarize_payload(
+    payload: dict[str, Any], truncate: Callable[[str, int], str]
+) -> dict[str, Any]:
+    summary: dict[str, Any] = {"type": payload.get("type")}
+    if "index" in payload:
+        summary["index"] = payload.get("index")
+    payload_type = payload.get("type")
+    if payload_type == "message_start":
+        message = payload.get("message") if isinstance(payload.get("message"), dict) else {}
+        summary["message"] = {
+            "id": message.get("id"),
+            "model": message.get("model"),
+            "role": message.get("role"),
+            "content_len": len(message.get("content") or []),
+            "usage": message.get("usage"),
+        }
+    elif payload_type == "message_delta":
+        summary["delta"] = payload.get("delta")
+        summary["usage"] = payload.get("usage")
+    elif payload_type == "content_block_start":
+        block = payload.get("content_block") if isinstance(payload.get("content_block"), dict) else {}
+        block_summary = {"type": block.get("type")}
+        if block.get("type") == "tool_use":
+            block_summary.update(
+                {"id": block.get("id"), "name": block.get("name"), "input": block.get("input")}
+            )
+        elif block.get("type") == "text":
+            block_summary["text_len"] = len(str(block.get("text") or ""))
+        else:
+            block_summary["keys"] = sorted(str(key) for key in block)
+        summary["content_block"] = block_summary
+    elif payload_type == "content_block_delta":
+        delta = payload.get("delta") if isinstance(payload.get("delta"), dict) else {}
+        delta_type = delta.get("type")
+        delta_summary: dict[str, Any] = {"type": delta_type}
+        if delta_type == "text_delta":
+            text = str(delta.get("text") or "")
+            delta_summary.update({"text_len": len(text), "text": truncate(text, 500)})
+        elif delta_type == "input_json_delta":
+            partial = str(delta.get("partial_json") or "")
+            delta_summary.update(
+                {
+                    "partial_json_len": len(partial),
+                    "partial_json": truncate(partial, 1000),
+                }
+            )
+        else:
+            delta_summary["keys"] = sorted(str(key) for key in delta)
+        summary["delta"] = delta_summary
+    else:
+        summary["keys"] = sorted(str(key) for key in payload)
+    return summary
+
+
+class SseTraceRepository:
+    def __init__(self, config: SseTraceConfig, ports: SseTracePorts) -> None:
+        self.config = config
+        self.ports = ports
+
+    def begin(
+        self,
+        provider: str,
+        model: str,
+        source: str,
+        source_body: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return {
+            "time": time.strftime("%Y-%m-%dT%H:%M:%S"),
+            "provider": provider,
+            "model": model,
+            "source": source,
+            "stream": True,
+            "messages_count": len(source_body.get("messages") or [])
+            if isinstance(source_body, dict)
+            else None,
+            "tools_count": len(source_body.get("tools") or [])
+            if isinstance(source_body, dict)
+            else None,
+            "metadata_keys": sorted(str(key) for key in (source_body.get("metadata") or {}))
+            if isinstance(source_body, dict) and isinstance(source_body.get("metadata"), dict)
+            else [],
+            "event_count": 0,
+            "events_truncated": False,
+            "events": [],
+        }
+
+    def record(
+        self, trace: dict[str, Any] | None, event_name: str, payload: dict[str, Any]
+    ) -> None:
+        if not isinstance(trace, dict):
+            return
+        try:
+            trace["event_count"] = int(trace.get("event_count") or 0) + 1
+            events = trace.get("events")
+            if not isinstance(events, list):
+                events = []
+                trace["events"] = events
+            if len(events) >= self.config.event_limit:
+                trace["events_truncated"] = True
+                return
+            raw = ""
+            if self.ports.enabled():
+                try:
+                    encoded = json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+                    raw = self.ports.truncate(encoded, self.config.payload_limit)
+                except (TypeError, ValueError, OverflowError) as exc:
+                    self.ports.log(
+                        "WARN",
+                        f"sse_trace_payload_encode_failed event={event_name} "
+                        f"error={type(exc).__name__}: {exc}",
+                    )
+            event = {
+                "n": trace["event_count"],
+                "event": event_name,
+                "payload": summarize_payload(payload, self.ports.truncate),
+            }
+            if raw:
+                event["raw"] = raw
+            events.append(event)
+        except Exception as exc:
+            self.ports.log(
+                "WARN",
+                f"sse_trace_event_record_failed event={event_name} "
+                f"error={type(exc).__name__}: {exc}",
+            )
+
+    def finish(self, trace: dict[str, Any] | None, **outcome: Any) -> None:
+        if not isinstance(trace, dict):
+            return
+        try:
+            trace.update({"finished_at": time.strftime("%Y-%m-%dT%H:%M:%S"), **outcome})
+            self.config.config_dir.mkdir(parents=True, exist_ok=True)
+            temporary = self.config.last_path.with_name(
+                f"{self.config.last_path.name}.{os.getpid()}.{time.time_ns()}.tmp"
+            )
+            encoded = json.dumps(trace, ensure_ascii=False, separators=(",", ":"))
+            temporary.write_text(encoded, encoding="utf-8")
+            temporary.replace(self.config.last_path)
+            if self.ports.enabled():
+                self._rotate(self.config.trace_path, self.config.max_bytes)
+                with self.config.trace_path.open("a", encoding="utf-8") as stream:
+                    stream.write(encoded + "\n")
+        except Exception as exc:
+            self.ports.log(
+                "WARN",
+                f"sse_trace_finish_failed outcome={outcome.get('outcome')} "
+                f"error={type(exc).__name__}: {exc}",
+            )
+
+    def finish_stream(
+        self,
+        trace: dict[str, Any] | None,
+        *,
+        outcome: str,
+        text_len: int = 0,
+        tool_call_count: int = 0,
+        chunks: int = 0,
+        stop_reason: str | None = None,
+        error: str | None = None,
+    ) -> None:
+        result: dict[str, Any] = {
+            "outcome": outcome,
+            "text_len": text_len,
+            "tool_call_count": tool_call_count,
+            "chunks": chunks,
+            "stop_reason": stop_reason,
+        }
+        if error:
+            result["error"] = error
+        self.finish(trace, **result)
+
+    def append_tool_call(self, event: str, payload: dict[str, Any]) -> None:
+        try:
+            self.config.config_dir.mkdir(parents=True, exist_ok=True)
+            self._rotate(self.config.tool_call_path, 2_000_000)
+            record = {
+                "time": time.strftime("%Y-%m-%dT%H:%M:%S"),
+                "event": event,
+                **payload,
+            }
+            with self.config.tool_call_path.open("a", encoding="utf-8") as stream:
+                stream.write(
+                    json.dumps(record, ensure_ascii=False, separators=(",", ":")) + "\n"
+                )
+        except Exception as exc:
+            self.ports.log(
+                "WARN",
+                f"tool_call_log_write_failed event={event} error={type(exc).__name__}: {exc}",
+            )
+
+    @staticmethod
+    def _rotate(path: Path, max_bytes: int) -> None:
+        if path.exists() and path.stat().st_size > max_bytes:
+            path.replace(path.with_suffix(".jsonl.1"))