arkaos 4.1.1 → 4.3.0

package/core/runtime/openrouter_provider.py

@@ -0,0 +1,172 @@
+"""OpenRouter provider — one API key, hundreds of models.
+
+Model Fabric PR-B. One of the backends behind the ``LLMProvider``
+Protocol in ``core/runtime/llm_provider.py``; callers go through
+``get_llm_provider()`` or pass an explicit model resolved by
+``core/runtime/model_router.py`` (e.g. role ``review`` →
+``openrouter/deepseek/deepseek-v4-pro``).
+
+OpenAI-compatible ``/api/v1/chat/completions`` via stdlib ``urllib`` —
+no extra dependencies, mirroring ``ollama_provider.py``. Key resolution:
+``OPENROUTER_API_KEY`` env, then ``~/.arkaos/keys.json``. Model from
+constructor, then ``OPENROUTER_MODEL`` env, then
+``models.yaml`` alias ``openrouter.default``.
+
+OpenRouter returns token usage (and native cached-token counts for
+providers that support caching) in the ``usage`` block; both are
+forwarded so cost telemetry stays accurate.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from core.runtime.llm_provider import LLMResponse, LLMUnavailable
+
+_API_BASE = "https://openrouter.ai/api/v1"
+_TIMEOUT_S = 180  # frontier models on long prompts; fusion panels wait
+_KEYS_PATH = Path.home() / ".arkaos" / "keys.json"
+
+# Attribution headers — OpenRouter ranks apps by these; harmless otherwise.
+_APP_HEADERS = {
+    "HTTP-Referer": "https://github.com/andreagroferreira/arka-os",
+    "X-Title": "ArkaOS",
+}
+
+
+def _read_key_from_keys_json() -> str:
+    try:
+        data = json.loads(_KEYS_PATH.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return ""
+    value = data.get("OPENROUTER_API_KEY", "")
+    return value.strip() if isinstance(value, str) else ""
+
+
+def _default_model_from_fabric() -> str:
+    """Resolve the `openrouter.default` alias from models.yaml, if set."""
+    try:
+        from core.runtime.model_router import load_config
+        config, _ = load_config()
+    except Exception:
+        return ""
+    return config.aliases.get("openrouter", {}).get("default", "")
+
+
+class OpenRouterProvider:
+    """Provider that hits the OpenRouter chat-completions API."""
+
+    ENV_KEY = "OPENROUTER_API_KEY"
+    ENV_MODEL = "OPENROUTER_MODEL"
+
+    def __init__(self, model: str | None = None, api_base: str | None = None) -> None:
+        self._model_override = model
+        self._api_base = (api_base or _API_BASE).rstrip("/")
+
+    def name(self) -> str:
+        return "openrouter"
+
+    def _resolve_key(self) -> str:
+        env_value = os.environ.get(self.ENV_KEY, "").strip()
+        return env_value or _read_key_from_keys_json()
+
+    def _resolve_model(self) -> str:
+        if self._model_override:
+            return self._model_override
+        env_value = os.environ.get(self.ENV_MODEL, "").strip()
+        return env_value or _default_model_from_fabric()
+
+    def is_available(self) -> bool:
+        """Static capability check: a key and a model are configured.
+
+        No network probe — OpenRouter is a paid remote API and this is
+        called on every provider-chain walk; a dead network surfaces as
+        ``LLMUnavailable`` at call time and the chain moves on.
+        """
+        return bool(self._resolve_key() and self._resolve_model())
+
+    def complete(
+        self,
+        prompt: str,
+        *,
+        max_tokens: int = 2000,
+        system: str = "",
+    ) -> LLMResponse:
+        key = self._resolve_key()
+        if not key:
+            raise LLMUnavailable(
+                "OpenRouter key not configured (set OPENROUTER_API_KEY or "
+                "add it via `npx arkaos keys`)"
+            )
+        model = self._resolve_model()
+        if not model:
+            raise LLMUnavailable(
+                "OpenRouter model not configured (set OPENROUTER_MODEL, pass "
+                "model=, or set aliases.openrouter.default in models.yaml)"
+            )
+        data = self._post_chat(key, self._build_payload(model, prompt, system, max_tokens))
+        return self._to_response(data, model)
+
+    def _build_payload(
+        self, model: str, prompt: str, system: str, max_tokens: int
+    ) -> dict:
+        messages: list[dict] = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+        return {
+            "model": model,
+            "messages": messages,
+            "max_tokens": max_tokens,
+            "stream": False,
+            "usage": {"include": True},  # cost + cached tokens in response
+        }
+
+    def _post_chat(self, key: str, payload: dict) -> dict:
+        request = urllib.request.Request(
+            f"{self._api_base}/chat/completions",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {key}",
+                **_APP_HEADERS,
+            },
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=_TIMEOUT_S) as response:
+                raw = response.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")[:300]
+            raise LLMUnavailable(
+                f"OpenRouter HTTP {exc.code}: {detail}"
+            ) from exc
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            raise LLMUnavailable(f"OpenRouter request failed: {exc}") from exc
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise LLMUnavailable(f"OpenRouter returned invalid JSON: {exc}") from exc
+
+    def _to_response(self, data: dict, model: str) -> LLMResponse:
+        if data.get("error"):
+            message = data["error"].get("message", "unknown error")
+            raise LLMUnavailable(f"OpenRouter error: {message}")
+        choices = data.get("choices") or []
+        text = ""
+        if choices:
+            text = ((choices[0].get("message") or {}).get("content") or "").strip()
+        usage = data.get("usage") or {}
+        cached = int(
+            (usage.get("prompt_tokens_details") or {}).get("cached_tokens", 0) or 0
+        )
+        return LLMResponse(
+            text=text,
+            tokens_in=int(usage.get("prompt_tokens", 0) or 0),
+            tokens_out=int(usage.get("completion_tokens", 0) or 0),
+            cached_tokens=cached,
+            model=str(data.get("model") or model),
+        )

package/core/workflow/frontend_gate.py

@@ -0,0 +1,162 @@
+"""Frontend excellence gate — PreToolUse enforcement for UI file edits.
+
+Constitution: ``excellence-mandate`` (NON-NEGOTIABLE, Excellence Reform
+2026-07-05). UI work must load the frontend design skills and judge
+against a named benchmark BEFORE code is written. This gate makes that
+duty mechanical: a Write/Edit/MultiEdit touching a UI file requires an
+``[arka:design] <skills/benchmark>`` marker in the recent assistant
+messages — the same ceremony contract as ``[arka:routing]``
+(flow_enforcer) and ``[arka:dispatch]`` (specialist_enforcer).
+
+Modes via ``hooks.frontendGate`` in ``~/.arkaos/config.json``:
+
+    absent / "warn"   → nudge on stderr, allow (rollout default)
+    true / "hard"     → deny UI edits without the marker
+    false / "off"     → gate disabled
+
+Bypasses: ``[arka:trivial] <reason>`` marker (same contract as the
+evidence flow — single-file edits under 10 lines) and
+``ARKA_BYPASS_DESIGN=1`` env (logged for accountability).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from core.shared import safe_session_id as _safe_session_id_module
+from core.workflow.flow_enforcer import (
+    TRIVIAL_RE,
+    _load_last_assistant_messages,
+)
+from core.workflow.specialist_enforcer import _locked_append
+
+CONFIG_PATH = Path.home() / ".arkaos" / "config.json"
+TELEMETRY_PATH = Path.home() / ".arkaos" / "telemetry" / "frontend-gate.jsonl"
+
+ASSISTANT_WINDOW = 20
+
+DESIGN_RE = re.compile(r"\[arka:design\]\s*\S+", re.IGNORECASE)
+
+_GATED_TOOLS = frozenset({"Write", "Edit", "MultiEdit"})
+
+# Component + stylesheet extensions. Plain .ts/.js are excluded: they are
+# ambiguous (stores, utils, configs) and would flood the gate with false
+# positives — the component file is where the visual decision lands.
+UI_SUFFIXES = frozenset({
+    ".vue", ".tsx", ".jsx", ".svelte", ".astro",
+    ".css", ".scss", ".sass", ".less",
+})
+
+
+@dataclass
+class Decision:
+    """Outcome of frontend-gate evaluation."""
+
+    allow: bool
+    reason: str
+    mode: str = "warn"
+    target_file: str = ""
+    marker_found: str | None = None
+
+    def to_stderr_message(self) -> str:
+        if self.reason not in ("no-design-marker",):
+            return ""
+        head = "[arka:suggest]" if self.allow else "[ARKA:DESIGN]"
+        verb = "should" if self.allow else "MUST"
+        return (
+            f"{head} UI edit to {self.target_file or 'this file'} without "
+            f"design evidence. Frontend work {verb} load the design skills "
+            f"(frontend-design, ui-ux-pro-max, project design system) at "
+            f"maximum effort and judge against a named benchmark FIRST "
+            f"(constitution `excellence-mandate`). Emit "
+            f"`[arka:design] <skills> benchmark=<name>` before UI edits, "
+            f"or `[arka:trivial] <reason>` for sub-10-line fixes."
+        )
+
+
+def _mode() -> str:
+    """Resolve ``hooks.frontendGate`` to 'off' | 'warn' | 'hard'."""
+    if not CONFIG_PATH.exists():
+        return "warn"
+    try:
+        data = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return "warn"
+    raw = data.get("hooks", {}).get("frontendGate", "warn")
+    if raw in (False, "off", "false"):
+        return "off"
+    if raw in (True, "hard", "true"):
+        return "hard"
+    return "warn"
+
+
+def is_ui_file(file_path: str) -> bool:
+    """True when the path carries a gated UI extension."""
+    return Path(file_path).suffix.lower() in UI_SUFFIXES
+
+
+def _scan(messages: list[str]) -> str | None:
+    """Return the matched evidence marker, or None."""
+    for message in messages:
+        match = DESIGN_RE.search(message) or TRIVIAL_RE.search(message)
+        if match:
+            return match.group(0)
+    return None
+
+
+def evaluate(
+    tool_name: str,
+    transcript_path: str,
+    session_id: str,
+    cwd: str,
+    tool_input: dict,
+    messages: list[str] | None = None,
+) -> Decision:
+    """Evaluate one tool call against the frontend excellence gate."""
+    file_path = str(tool_input.get("file_path", ""))
+    if tool_name not in _GATED_TOOLS or not is_ui_file(file_path):
+        return Decision(allow=True, reason="not-ui-scope", target_file=file_path)
+    mode = _mode()
+    if mode == "off":
+        return Decision(allow=True, reason="flag-off", mode=mode,
+                        target_file=file_path)
+    if os.environ.get("ARKA_BYPASS_DESIGN") == "1":
+        return Decision(allow=True, reason="env-bypass", mode=mode,
+                        target_file=file_path)
+    if messages is None:
+        messages = _load_last_assistant_messages(
+            transcript_path, ASSISTANT_WINDOW
+        )
+    marker = _scan(messages)
+    if marker is not None:
+        return Decision(allow=True, reason="design-evidence", mode=mode,
+                        target_file=file_path, marker_found=marker)
+    return Decision(allow=(mode != "hard"), reason="no-design-marker",
+                    mode=mode, target_file=file_path)
+
+
+def record_telemetry(session_id: str, tool: str, decision: Decision) -> None:
+    """Append a structured record to the frontend-gate telemetry log.
+
+    Drops the record silently when session_id fails the safe-id check
+    (path-traversal mitigation, CWE-22). Never blocks the hook.
+    """
+    safe = _safe_session_id_module.safe_session_id(session_id)
+    if safe is None:
+        return
+    entry = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "session_id": safe,
+        "tool": tool,
+        **asdict(decision),
+    }
+    try:
+        with _locked_append(TELEMETRY_PATH) as fh:
+            fh.write(json.dumps(entry) + "\n")
+    except OSError:
+        pass

package/dashboard/app/layouts/default.vue

@@ -52,6 +52,13 @@ const links = [[{
   onSelect: () => {
     open.value = false
   }
+}, {
+  label: 'Models',
+  icon: 'i-lucide-layers',
+  to: '/models',
+  onSelect: () => {
+    open.value = false
+  }
 }, {
   label: 'Tasks',
   icon: 'i-lucide-list-checks',