@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/advisor_client.py

@@ -0,0 +1,193 @@
+"""Application clients for Advisor review and refinement provider calls."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+@dataclass(frozen=True, slots=True)
+class AdvisorClientPolicy:
+    model_enabled: Callable[[dict[str, Any]], str]
+    provider_supported: Callable[[str], bool]
+    upstream_model: Callable[[str, str], str]
+    provider_kind: Callable[..., str]
+    request: Callable[..., dict[str, Any]]
+    endpoint: Callable[[str, dict[str, Any]], str]
+    response_text: Callable[[str, Any], str]
+
+
+@dataclass(frozen=True, slots=True)
+class AdvisorClientIO:
+    apply_rate_limit: Callable[..., None]
+    write_activity: Callable[..., None]
+    estimate_tokens: Callable[[Any], int]
+    post_json: Callable[..., Any]
+    headers: Callable[..., dict[str, str]]
+    provider_timeout: Callable[[dict[str, Any]], float]
+    ollama_timeout: Callable[[dict[str, Any]], float]
+    log: Callable[[str, str], None]
+
+
+class AdvisorClient:
+    def __init__(self, policy: AdvisorClientPolicy, io: AdvisorClientIO) -> None:
+        self.policy = policy
+        self.io = io
+
+    def review(
+        self,
+        provider: str,
+        config: dict[str, Any],
+        body: dict[str, Any],
+        focus: str = "",
+        inbound_headers: Any | None = None,
+        *,
+        allow_rate_limit_wait: bool = True,
+        retry_rate_limits: bool = True,
+        raise_errors: bool = False,
+    ) -> str:
+        advisor_model = self.policy.model_enabled(config)
+        if not advisor_model or not self.policy.provider_supported(provider):
+            return ""
+        upstream_model = self.policy.upstream_model(provider, advisor_model)
+        request_body = self.policy.request(
+            provider, advisor_model, body, config, focus_override=focus
+        )
+        try:
+            if allow_rate_limit_wait:
+                self.io.apply_rate_limit(provider, config, upstream_model)
+            self.io.write_activity(
+                "advisor",
+                provider,
+                upstream_model,
+                tokens=self.io.estimate_tokens(request_body),
+            )
+            kind = self.policy.provider_kind(provider)
+            headers = (
+                self.io.headers(
+                    provider,
+                    config,
+                    inbound_headers,
+                    "anthropic_messages",
+                )
+                if kind == "anthropic"
+                else self.io.headers(provider, config)
+            )
+            timeout = (
+                self.io.ollama_timeout(config)
+                if kind == "ollama"
+                else self.io.provider_timeout(config)
+            )
+            data = self.io.post_json(
+                self.policy.endpoint(provider, config),
+                request_body,
+                headers,
+                timeout,
+                provider,
+                config,
+                upstream_model,
+                None,
+                retry_rate_limits=retry_rate_limits,
+            )
+            text = self.policy.response_text(provider, data)
+            if text:
+                self.io.log(
+                    "INFO",
+                    f"advisor_feedback provider={provider} "
+                    f"advisor_model={upstream_model} chars={len(text)}",
+                )
+            return text
+        except Exception as exc:
+            self.io.log(
+                "WARN",
+                f"advisor_request_failed provider={provider} "
+                f"advisor_model={upstream_model} "
+                f"error={type(exc).__name__}: {exc}",
+            )
+            self.io.write_activity(
+                "advisor_error",
+                provider,
+                upstream_model,
+                error=type(exc).__name__,
+            )
+            if raise_errors:
+                raise
+            return ""
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderChatPolicy:
+    normalize_thinking: Callable[..., dict[str, Any]]
+    normalize_tool_choice: Callable[..., dict[str, Any]]
+    provider_kind: Callable[..., str]
+    upstream_model: Callable[[str, dict[str, Any], str], str]
+    ollama_request: Callable[..., dict[str, Any]]
+    openai_request: Callable[..., dict[str, Any]]
+    ollama_response: Callable[..., dict[str, Any]]
+    openai_response: Callable[..., dict[str, Any]]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderChatIO:
+    apply_rate_limit: Callable[..., None]
+    post_json: Callable[..., Any]
+    join_url: Callable[[str, str], str]
+    request_base: Callable[[str, dict[str, Any]], str]
+    headers: Callable[..., dict[str, str]]
+    provider_timeout: Callable[[dict[str, Any]], float]
+    ollama_timeout: Callable[[dict[str, Any]], float]
+
+
+class ProviderChatExecutor:
+    def __init__(self, policy: ProviderChatPolicy, io: ProviderChatIO) -> None:
+        self.policy = policy
+        self.io = io
+
+    def execute(
+        self,
+        provider: str,
+        config: dict[str, Any],
+        body: dict[str, Any],
+        model: str,
+    ) -> dict[str, Any]:
+        body = self.policy.normalize_thinking(provider, config, body)
+        body = self.policy.normalize_tool_choice(provider, config, body)
+        transport = self.policy.provider_kind(provider, config)
+        if transport == "ollama":
+            request = self.policy.ollama_request(
+                model, body, config, stream=False, provider=provider
+            )
+            self.io.apply_rate_limit(provider, config, model)
+            data = self.io.post_json(
+                self.io.join_url(str(config.get("base_url") or "").rstrip("/"), "/api/chat"),
+                request,
+                self.io.headers(provider, config),
+                self.io.ollama_timeout(config),
+                provider,
+                config,
+                model,
+                None,
+            )
+            return self.policy.ollama_response(data, model, source_body=body)
+        if transport == "openai-compatible":
+            upstream_model = self.policy.upstream_model(provider, config, model)
+            request = self.policy.openai_request(
+                provider, upstream_model, body, config, stream=False
+            )
+            self.io.apply_rate_limit(provider, config, upstream_model)
+            data = self.io.post_json(
+                self.io.join_url(
+                    self.io.request_base(provider, config), "/v1/chat/completions"
+                ),
+                request,
+                self.io.headers(provider, config),
+                self.io.provider_timeout(config),
+                provider,
+                config,
+                upstream_model,
+                None,
+            )
+            return self.policy.openai_response(data, upstream_model, source_body=body)
+        raise RuntimeError(
+            f"Advisor refinement is not supported for provider {provider}"
+        )

package/ciel_runtime_support/advisor_policy.py

@@ -0,0 +1,320 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+@dataclass(frozen=True)
+class AdvisorTextServices:
+    content_to_text: Callable[[Any], str]
+    tool_input_for_prompt: Callable[[Any], str]
+
+
+@dataclass(frozen=True)
+class AdvisorDecisionServices:
+    advisor_enabled: Callable[[dict[str, Any]], bool]
+    is_advisor_request: Callable[[dict[str, Any]], bool]
+    completed_work: Callable[[dict[str, Any]], bool]
+    non_actionable_response: Callable[[str], bool]
+    plan_mode_active: Callable[[dict[str, Any]], bool]
+    provider_supported: Callable[[str], bool]
+
+
+@dataclass(frozen=True)
+class AdvisorServices:
+    text: AdvisorTextServices
+    decisions: AdvisorDecisionServices
+    log: Callable[[str, str], None]
+    feedback_marker: str
+
+
+@dataclass(frozen=True, slots=True)
+class AdvisorShortcutPorts:
+    should_intercept: Callable[[str, dict[str, Any]], bool]
+    is_request: Callable[[dict[str, Any]], bool]
+    provider_supported: Callable[[str], bool]
+    call_text: Callable[..., str]
+    write_anthropic: Callable[..., Any]
+    load_config: Callable[[], dict[str, Any]]
+    current_alias: Callable[[dict[str, Any]], str]
+
+
+@dataclass(frozen=True, slots=True)
+class AdvisorShortcutController:
+    ports: AdvisorShortcutPorts
+
+    def handle(
+        self,
+        handler: Any,
+        provider: str,
+        provider_config: dict[str, Any],
+        body: dict[str, Any],
+    ) -> bool:
+        if not self.ports.should_intercept(provider, provider_config):
+            return False
+        if not self.ports.is_request(body):
+            return False
+        advisor_model = str(provider_config.get("advisor_model") or "").strip()
+        stream = bool(body.get("stream", True))
+        if not advisor_model:
+            model = str(
+                body.get("model")
+                or self.ports.current_alias(self.ports.load_config())
+            )
+            self.ports.write_anthropic(
+                handler,
+                model,
+                "Advisor is off. Choose an Advisor Model in the ciel-runtime launch menu (item 5), or run `ciel-runtime advisor-model <model-id>`, then use `/advisor` again.",
+                stream,
+            )
+            return True
+        if not self.ports.provider_supported(provider):
+            self.ports.write_anthropic(
+                handler,
+                advisor_model,
+                f"Advisor Model is configured as `{advisor_model}`, but ciel-runtime advisor calling is not implemented for provider `{provider}`.",
+                stream,
+            )
+            return True
+        try:
+            text = self.ports.call_text(
+                provider,
+                provider_config,
+                body,
+                inbound_headers=handler.headers,
+                allow_rate_limit_wait=False,
+                retry_rate_limits=False,
+                raise_errors=True,
+            )
+            if not text:
+                text = "Advisor returned no text."
+        except Exception as exc:
+            text = f"Advisor request failed: {type(exc).__name__}: {exc}"
+        self.ports.write_anthropic(
+            handler, advisor_model, "Advisor guidance:\n\n" + text, stream
+        )
+        return True
+
+
+def advisor_messages_and_system(
+    body: dict[str, Any], services: AdvisorServices
+) -> tuple[list[dict[str, Any]], list[str]]:
+    messages: list[dict[str, Any]] = []
+    system_texts: list[str] = []
+    for message in body.get("messages", []) or []:
+        if not isinstance(message, dict):
+            continue
+        role = str(message.get("role") or "").strip()
+        text = services.text.content_to_text(message.get("content")).strip()
+        if role == "system":
+            if text:
+                system_texts.append(text)
+        elif role in {"user", "assistant"}:
+            messages.append(message)
+        elif text:
+            messages.append(
+                {
+                    "role": "user",
+                    "content": [{"type": "text", "text": f"[{role or 'unknown'} message]\n{text}"}],
+                }
+            )
+    return messages, system_texts
+
+
+def advisor_tool_schema() -> dict[str, Any]:
+    return {
+        "name": "advisor",
+        "description": (
+            "Consult a second, stronger advisor model for an independent review before you make an important "
+            "plan, architecture, debugging, or final-completion decision. Use this when additional scrutiny could "
+            "catch gaps, risks, or better next steps."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "question": {
+                    "type": "string",
+                    "description": "The specific decision, plan, code path, or risk you want the advisor to review.",
+                }
+            },
+            "required": ["question"],
+        },
+    }
+
+
+def body_with_advisor_tool(
+    body: dict[str, Any], provider_config: dict[str, Any], services: AdvisorServices
+) -> dict[str, Any]:
+    if not services.decisions.advisor_enabled(provider_config):
+        return body
+    tools = body.get("tools") if isinstance(body.get("tools"), list) else []
+    if any(isinstance(tool, dict) and str(tool.get("name") or "") == "advisor" for tool in tools):
+        return body
+    output = dict(body)
+    output["tools"] = [*tools, advisor_tool_schema()]
+    return output
+
+
+def is_claude_code_advisor_server_tool(tool: Any) -> bool:
+    return bool(
+        isinstance(tool, dict)
+        and str(tool.get("name") or "") == "advisor"
+        and str(tool.get("type") or "").startswith("advisor_")
+    )
+
+
+def strip_autonomous_advisor_server_tools(
+    body: dict[str, Any],
+    services: AdvisorServices,
+    *,
+    server_tool_supported: bool,
+) -> dict[str, Any]:
+    if server_tool_supported or services.decisions.is_advisor_request(body):
+        return body
+    if body_has_advisor_feedback(body, services):
+        return body
+    tools = body.get("tools")
+    if not isinstance(tools, list) or not tools:
+        return body
+    kept = [tool for tool in tools if not is_claude_code_advisor_server_tool(tool)]
+    removed = len(tools) - len(kept)
+    if not removed:
+        return body
+    output = dict(body)
+    output["tools"] = kept
+    services.log("INFO", f"stripped autonomous advisor server tool count={removed}")
+    return output
+
+
+def advisor_tool_focus_from_message(message: dict[str, Any]) -> str | None:
+    content = message.get("content")
+    if not isinstance(content, list):
+        return None
+    for block in content:
+        if not isinstance(block, dict) or block.get("type") != "tool_use":
+            continue
+        if str(block.get("name") or "") != "advisor":
+            continue
+        tool_input = block.get("input")
+        if isinstance(tool_input, dict):
+            for key in ("question", "prompt", "focus", "task"):
+                value = tool_input.get(key)
+                if isinstance(value, str) and value.strip():
+                    return value.strip()
+        return "advisor tool call"
+    return None
+
+
+def tool_review_context_from_message(
+    message: dict[str, Any], trigger: str, services: AdvisorServices
+) -> str:
+    content = message.get("content")
+    if not isinstance(content, list):
+        return ""
+    sections: list[str] = []
+    for block in content:
+        if not isinstance(block, dict) or block.get("type") != "tool_use":
+            continue
+        name = str(block.get("name") or "").strip()
+        if not name or name == "advisor":
+            continue
+        input_text = services.text.tool_input_for_prompt(block.get("input"))
+        if name == "ExitPlanMode":
+            sections.append(
+                "Review target: ExitPlanMode plan before user approval.\n"
+                "The executor is about to submit this plan. Review the actual plan/tool input below.\n"
+                f"Tool input:\n{input_text}"
+            )
+        elif trigger:
+            sections.append(f"Review target tool: {name} ({trigger}).\nTool input:\n{input_text}")
+    return "\n\n".join(sections)
+
+
+def advisor_focus_for_message(
+    message: dict[str, Any], trigger: str | None, services: AdvisorServices
+) -> tuple[str | None, str | None]:
+    explicit_focus = advisor_tool_focus_from_message(message)
+    if explicit_focus:
+        return "advisor tool call", explicit_focus
+    if not trigger:
+        return None, None
+    review_context = tool_review_context_from_message(message, trigger, services)
+    return trigger, review_context or trigger
+
+
+def assistant_tool_call_summary_for_prompt(
+    message: dict[str, Any], services: AdvisorServices
+) -> str:
+    content = message.get("content")
+    if not isinstance(content, list):
+        return ""
+    sections: list[str] = []
+    for block in content:
+        if not isinstance(block, dict) or block.get("type") != "tool_use":
+            continue
+        name = str(block.get("name") or "tool").strip() or "tool"
+        if name != "advisor":
+            sections.append(
+                f"Pending Claude Code tool call: {name}\nTool input:\n"
+                f"{services.text.tool_input_for_prompt(block.get('input'))}"
+            )
+    return "\n\n".join(sections)
+
+
+def body_has_advisor_feedback(body: dict[str, Any], services: AdvisorServices) -> bool:
+    for message in reversed(body.get("messages") or []):
+        if not isinstance(message, dict):
+            continue
+        if services.feedback_marker in services.text.content_to_text(message.get("content")):
+            return True
+    return False
+
+
+def anthropic_message_tool_names(message: dict[str, Any]) -> list[str]:
+    content = message.get("content")
+    if not isinstance(content, list):
+        return []
+    names: list[str] = []
+    for block in content:
+        if isinstance(block, dict) and block.get("type") == "tool_use":
+            name = block.get("name")
+            if isinstance(name, str) and name:
+                names.append(name)
+    return names
+
+
+def advisor_trigger_for_message(
+    body: dict[str, Any], message: dict[str, Any], services: AdvisorServices
+) -> str | None:
+    names = set(anthropic_message_tool_names(message))
+    if "ExitPlanMode" in names:
+        return "before ExitPlanMode plan approval"
+    if names:
+        return None
+    text = services.text.content_to_text(message.get("content")).strip()
+    if (
+        text
+        and message.get("stop_reason") == "end_turn"
+        and services.decisions.completed_work(body)
+        and not services.decisions.non_actionable_response(text)
+    ):
+        return "before completion/final response"
+    return None
+
+
+def advisor_gate_reason_for_body(
+    provider: str,
+    provider_config: dict[str, Any],
+    body: dict[str, Any],
+    services: AdvisorServices,
+) -> str:
+    decisions = services.decisions
+    if not decisions.advisor_enabled(provider_config) or not decisions.provider_supported(provider):
+        return ""
+    if decisions.is_advisor_request(body) or body_has_advisor_feedback(body, services):
+        return ""
+    if decisions.plan_mode_active(body):
+        return "plan_mode"
+    if decisions.completed_work(body):
+        return "completed_work"
+    return ""

package/ciel_runtime_support/advisor_refinement.py

@@ -0,0 +1,160 @@
+"""Apply Advisor feedback as a bounded refinement decorator around a response."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class AdvisorRefinementText:
+    content_text: Callable[[Any], str]
+    tool_names: Callable[[dict[str, Any]], list[str]]
+    tool_summary: Callable[[dict[str, Any]], str]
+    compact_text: Callable[[str], str]
+    prepend_text: Callable[[dict[str, Any], str], dict[str, Any]]
+
+
+@dataclass(frozen=True, slots=True)
+class AdvisorRefinementPolicy:
+    model_enabled: Callable[[dict[str, Any]], bool]
+    provider_supported: Callable[[str], bool]
+    is_advisor_request: Callable[[dict[str, Any]], bool]
+    has_feedback: Callable[[dict[str, Any]], bool]
+    trigger: Callable[[dict[str, Any], dict[str, Any]], str]
+    focus: Callable[[dict[str, Any], str], tuple[str, str]]
+
+
+@dataclass(frozen=True, slots=True)
+class AdvisorRefinementIO:
+    call_advisor: Callable[..., str]
+    call_provider: Callable[..., dict[str, Any]]
+    log: Callable[[str, str], None]
+    write_activity: Callable[..., None]
+
+
+class AdvisorRefinementService:
+    def __init__(
+        self,
+        feedback_marker: str,
+        text: AdvisorRefinementText,
+        policy: AdvisorRefinementPolicy,
+        io: AdvisorRefinementIO,
+    ) -> None:
+        self.feedback_marker = feedback_marker
+        self.text = text
+        self.policy = policy
+        self.io = io
+
+    def body_with_feedback(
+        self,
+        body: dict[str, Any],
+        assistant_message: dict[str, Any],
+        advisor_text: str,
+        trigger: str,
+    ) -> dict[str, Any]:
+        messages = [item for item in body.get("messages", []) if isinstance(item, dict)]
+        assistant_text = self.text.content_text(assistant_message.get("content")).strip()
+        tool_names = self.text.tool_names(assistant_message)
+        tool_summary = self.text.tool_summary(assistant_message)
+        if assistant_text:
+            summary = self.text.compact_text(assistant_text)
+        elif tool_summary:
+            summary = self.text.compact_text(tool_summary)
+        elif tool_names:
+            summary = (
+                "I was about to call Claude Code tool(s): "
+                + ", ".join(tool_names)
+                + "."
+            )
+        else:
+            summary = ""
+        if summary:
+            messages.append(
+                {"role": "assistant", "content": [{"type": "text", "text": summary}]}
+            )
+        feedback = (
+            f"{self.feedback_marker}\n"
+            f"Advisor review trigger: {trigger}.\n\n"
+            f"{advisor_text}\n\n"
+            "Apply this advisor feedback now. If the plan is still ready, call "
+            "ExitPlanMode with the improved plan. If the task is complete, provide "
+            "the final answer. If the advisor found a gap, continue with concrete "
+            "Claude Code tool calls instead of stopping after an announcement."
+        )
+        messages.append(
+            {"role": "user", "content": [{"type": "text", "text": feedback}]}
+        )
+        projected = dict(body)
+        projected["messages"] = messages
+        projected.pop("tool_choice", None)
+        return projected
+
+    @staticmethod
+    def visible_summary(advisor_text: str, trigger: str, limit: int = 700) -> str:
+        text = re.sub(r"\s+", " ", str(advisor_text or "")).strip()
+        if not text:
+            return ""
+        if len(text) > limit:
+            text = text[: max(0, limit - 1)].rstrip() + "…"
+        return f"Advisor review ({trigger}): {text}\n\n"
+
+    def refine(
+        self,
+        provider: str,
+        config: dict[str, Any],
+        original_body: dict[str, Any],
+        message: dict[str, Any],
+        main_model: str,
+    ) -> dict[str, Any]:
+        if not self.policy.model_enabled(config):
+            return message
+        if not self.policy.provider_supported(provider):
+            return message
+        if self.policy.is_advisor_request(original_body) or self.policy.has_feedback(
+            original_body
+        ):
+            return message
+        trigger = self.policy.trigger(original_body, message)
+        trigger, advisor_focus = self.policy.focus(message, trigger)
+        if not trigger:
+            return message
+        advisor_text = self.io.call_advisor(
+            provider,
+            config,
+            original_body,
+            focus=advisor_focus or trigger,
+        )
+        if not advisor_text:
+            return message
+        follow_body = self.body_with_feedback(
+            original_body, message, advisor_text, trigger
+        )
+        summary = self.visible_summary(advisor_text, trigger)
+        try:
+            self.io.log(
+                "INFO",
+                f"advisor_refinement_call trigger={trigger} main_model={main_model}",
+            )
+            refined = self.io.call_provider(provider, config, follow_body, main_model)
+            self.io.log(
+                "INFO",
+                f"advisor_refinement_done trigger={trigger} "
+                f"stop_reason={refined.get('stop_reason')}",
+            )
+            return self.text.prepend_text(refined, summary)
+        except Exception as exc:
+            self.io.log(
+                "WARN",
+                f"advisor_refinement_failed trigger={trigger} model={main_model} "
+                f"error={type(exc).__name__}: {exc}",
+            )
+            self.io.write_activity(
+                "advisor_refinement_error",
+                provider,
+                main_model,
+                error=type(exc).__name__,
+            )
+            return self.text.prepend_text(message, summary)