arkaos 4.1.1 → 4.3.0

package/core/hooks/pre_tool_use.py

@@ -5,10 +5,12 @@ with ONE python process. Gate order is preserved exactly:
 
     1. KB-first research gate  (core/workflow/research_gate.py)
     2. Specialist-dispatch gate (core/workflow/specialist_enforcer.py)
-    3. Fast allow for non-flow-gated tools
-    4. CostGovernor budget check (stdlib-only — MUST run even when the
+    3. Frontend excellence gate (core/workflow/frontend_gate.py — v4.2.0
+       excellence-mandate: UI edits require [arka:design] evidence)
+    4. Fast allow for non-flow-gated tools
+    5. CostGovernor budget check (stdlib-only — MUST run even when the
        yaml-needing enforcers degrade; see ADR 2026-07-04-cost-governor)
-    5. Evidence-flow gate (core/workflow/flow_enforcer.py)
+    6. Evidence-flow gate (core/workflow/flow_enforcer.py)
 
 Behavior contract (unchanged from the bash version):
     - allow  → no stdout, exit 0 (nudges/warnings on stderr)
@@ -165,6 +167,50 @@ def _specialist_gate(
     return None
 
 
+def _frontend_gate(
+    root: str,
+    tool_name: str,
+    transcript_path: str,
+    session_id: str,
+    cwd: str,
+    tool_input: dict,
+    messages: _MessagesOnce,
+) -> int | None:
+    """Frontend excellence gate (excellence-mandate). 2 on deny, None to continue."""
+    if tool_name not in _SPECIALIST_TOOLS:
+        return None
+    if not (Path(root) / "core" / "workflow" / "frontend_gate.py").is_file():
+        return None
+    try:
+        from core.workflow.frontend_gate import (
+            evaluate,
+            is_ui_file,
+            record_telemetry,
+        )
+    except Exception:
+        return None  # frontend-gate-import-failed → allow
+    # Zero-read fast path: only UI files ever need the transcript.
+    if not is_ui_file(str(tool_input.get("file_path", ""))):
+        return None
+    decision = evaluate(
+        tool_name=tool_name,
+        transcript_path=transcript_path,
+        session_id=session_id,
+        cwd=cwd,
+        tool_input=tool_input,
+        messages=messages.load(),
+    )
+    try:
+        record_telemetry(session_id=session_id, tool=tool_name, decision=decision)
+    except Exception:
+        pass
+    if not decision.allow:
+        return _deny(decision.to_stderr_message())
+    if decision.to_stderr_message():
+        print(decision.to_stderr_message(), file=sys.stderr)
+    return None
+
+
 def _budget_check(session_id: str) -> tuple[bool, str]:
     """CostGovernor gate (stdlib-only). Returns (allow, warning)."""
     try:
@@ -244,6 +290,12 @@ def main(stdin_json: dict | None = None) -> int:
     if code is not None:
         return code
 
+    code = _frontend_gate(
+        root, tool_name, transcript_path, session_id, cwd, tool_input, messages
+    )
+    if code is not None:
+        return code
+
     # Fast allow: not a flow-gated tool (Bash stays — classified per-command
     # by the enforcer via bash_is_effect()).
     if tool_name not in _FLOW_GATED_TOOLS:

package/core/runtime/llm_provider.py

@@ -32,7 +32,9 @@ from core.runtime.pricing import estimate_cost_usd
 
 
 _DEFAULT_CONFIG_PATH = Path.home() / ".arkaos" / "config.json"
-_FALLBACK_ORDER: tuple[str, ...] = ("subagent", "ollama", "anthropic-direct", "stub")
+_FALLBACK_ORDER: tuple[str, ...] = (
+    "subagent", "ollama", "openrouter", "anthropic-direct", "stub"
+)
 
 
 # ─── Public dataclass ─────────────────────────────────────────────────
@@ -330,9 +332,16 @@ def _import_ollama_provider() -> type:
     return OllamaProvider
 
 
+def _import_openrouter_provider() -> type:
+    """Lazy import to keep the OpenRouter provider optional at runtime."""
+    from core.runtime.openrouter_provider import OpenRouterProvider
+    return OpenRouterProvider
+
+
 _PROVIDERS: dict[str, type] = {
     "subagent": SubagentProvider,
     "ollama": _import_ollama_provider(),
+    "openrouter": _import_openrouter_provider(),
     "anthropic-direct": AnthropicDirectProvider,
     "stub": StubProvider,
 }

package/core/runtime/model_router.py

@@ -0,0 +1,204 @@
+"""Model Fabric router — resolve a work role to (provider, model, effort).
+
+The user owns ``~/.arkaos/models.yaml``; the packaged default ships at
+``config/models.yaml``. Roles govern everything ArkaOS dispatches
+(subagents, Quality Gate, Forge, fusion, cognition, daemons) — the
+interactive runtime keeps its own main-loop model.
+
+Constitution ``model-routing`` (Excellence Reform 2026-07-05): quality-
+critical roles (design, review, architecture, strategy, quality_gate)
+default to the best model available at maximum effort; only genuinely
+mechanical work economises. The built-in fallback used when no YAML can
+be read encodes the same posture — a missing file never silently
+downgrades a quality role.
+
+Public API::
+
+    resolve("review")          -> ResolvedModel(provider, model, effort)
+    load_config()              -> ModelsConfig
+    ensure_user_config()       -> Path (creates ~/.arkaos/models.yaml)
+    set_role("review", "anthropic/best", effort="max")
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, Field, field_validator
+
+USER_CONFIG_PATH = Path.home() / ".arkaos" / "models.yaml"
+
+QUALITY_ROLES = frozenset({
+    "design", "review", "architecture", "strategy", "quality_gate",
+})
+KNOWN_EFFORTS = ("low", "medium", "high", "max")
+
+_ALIAS_NAMES = frozenset({"best", "default", "fast"})
+
+
+class RoleChoice(BaseModel):
+    """One role entry as written in models.yaml."""
+
+    provider: str = "runtime"
+    model: str = "best"
+    effort: str = "high"
+
+    @field_validator("effort")
+    @classmethod
+    def _known_effort(cls, value: str) -> str:
+        if value not in KNOWN_EFFORTS:
+            raise ValueError(
+                f"effort must be one of {KNOWN_EFFORTS}, got {value!r}"
+            )
+        return value
+
+
+class FusionConfig(BaseModel):
+    """Judge + panel for the fusion engine (PR-D consumes this)."""
+
+    judge: RoleChoice = Field(default_factory=lambda: RoleChoice(effort="max"))
+    panel: list[RoleChoice] = Field(default_factory=list)
+
+
+class ModelsConfig(BaseModel):
+    """Validated shape of models.yaml."""
+
+    version: int = 1
+    providers: dict[str, dict] = Field(default_factory=dict)
+    aliases: dict[str, dict[str, str]] = Field(default_factory=dict)
+    roles: dict[str, RoleChoice] = Field(default_factory=dict)
+    fusion: FusionConfig = Field(default_factory=FusionConfig)
+
+
+class ResolvedModel(BaseModel):
+    """A role after alias resolution — what a dispatcher actually uses."""
+
+    role: str
+    provider: str
+    model: str
+    effort: str
+    source: str  # "user" | "packaged" | "builtin"
+
+
+def _packaged_config_path() -> Path:
+    return Path(__file__).resolve().parents[2] / "config" / "models.yaml"
+
+
+def _builtin_config() -> ModelsConfig:
+    """Quality-first posture used when no YAML is readable at all."""
+    roles = {
+        role: RoleChoice(model="best", effort="max") for role in QUALITY_ROLES
+    }
+    roles["execution"] = RoleChoice(model="default", effort="high")
+    roles["mechanical"] = RoleChoice(model="fast", effort="low")
+    return ModelsConfig(
+        providers={"runtime": {"type": "subagent"}},
+        aliases={"runtime": {"best": "opus", "default": "sonnet", "fast": "haiku"}},
+        roles=roles,
+    )
+
+
+def _read_yaml(path: Path) -> ModelsConfig | None:
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    try:
+        return ModelsConfig.model_validate(data)
+    except ValueError:
+        return None
+
+
+def load_config(user_path: Path | None = None) -> tuple[ModelsConfig, str]:
+    """Load config with provenance: user file, packaged default, builtin."""
+    path = user_path or USER_CONFIG_PATH
+    config = _read_yaml(path) if path.is_file() else None
+    if config is not None:
+        return config, "user"
+    packaged = _packaged_config_path()
+    config = _read_yaml(packaged) if packaged.is_file() else None
+    if config is not None:
+        return config, "packaged"
+    return _builtin_config(), "builtin"
+
+
+def _resolve_alias(config: ModelsConfig, provider: str, model: str) -> str:
+    if model not in _ALIAS_NAMES:
+        return model
+    return config.aliases.get(provider, {}).get(model, "") or model
+
+
+def resolve(role: str, user_path: Path | None = None) -> ResolvedModel:
+    """Resolve a role name to a concrete (provider, model, effort).
+
+    Unknown roles resolve conservatively: quality posture, not economy —
+    a typo must never silently land on the cheap tier
+    (``excellence-mandate``).
+    """
+    config, source = load_config(user_path)
+    choice = config.roles.get(role)
+    if choice is None:
+        fallback = "execution" if role not in QUALITY_ROLES else role
+        choice = config.roles.get(fallback, RoleChoice(model="best", effort="max"))
+    return ResolvedModel(
+        role=role,
+        provider=choice.provider,
+        model=_resolve_alias(config, choice.provider, choice.model),
+        effort=choice.effort,
+        source=source,
+    )
+
+
+def resolve_all(user_path: Path | None = None) -> list[ResolvedModel]:
+    """Resolve every configured role — the CLI table."""
+    config, _ = load_config(user_path)
+    return [resolve(role, user_path) for role in sorted(config.roles)]
+
+
+def ensure_user_config(user_path: Path | None = None) -> Path:
+    """Create ~/.arkaos/models.yaml from the packaged default if absent."""
+    path = user_path or USER_CONFIG_PATH
+    if path.is_file():
+        return path
+    path.parent.mkdir(parents=True, exist_ok=True)
+    packaged = _packaged_config_path()
+    if packaged.is_file():
+        shutil.copy(packaged, path)
+    else:
+        path.write_text(
+            yaml.safe_dump(_builtin_config().model_dump(), sort_keys=False),
+            encoding="utf-8",
+        )
+    return path
+
+
+def set_role(
+    role: str,
+    target: str,
+    effort: str | None = None,
+    user_path: Path | None = None,
+) -> ResolvedModel:
+    """Point a role at ``provider/model`` (e.g. ``anthropic/best``).
+
+    Writes the user file (creating it first when needed) and returns the
+    new resolution. Raises ValueError on a malformed target or effort.
+    """
+    if "/" not in target:
+        raise ValueError(
+            f"target must be provider/model (e.g. runtime/best), got {target!r}"
+        )
+    provider, model = target.split("/", 1)
+    path = ensure_user_config(user_path)
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    entry = {"provider": provider, "model": model}
+    entry["effort"] = effort or data.get("roles", {}).get(role, {}).get(
+        "effort", "max" if role in QUALITY_ROLES else "high"
+    )
+    RoleChoice.model_validate(entry)  # fail before writing anything
+    data.setdefault("roles", {})[role] = entry
+    path.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
+    return resolve(role, path)

package/core/runtime/model_router_cli.py

@@ -0,0 +1,151 @@
+"""CLI for the Model Fabric router — `npx arkaos models` delegates here.
+
+Usage::
+
+    python -m core.runtime.model_router_cli               # table of roles
+    python -m core.runtime.model_router_cli --json        # machine-readable
+    python -m core.runtime.model_router_cli init          # create user file
+    python -m core.runtime.model_router_cli set review anthropic/best --effort max
+    python -m core.runtime.model_router_cli usage --period week
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from core.runtime.llm_cost_telemetry import VALID_PERIODS, summarise
+from core.runtime.model_router import (
+    USER_CONFIG_PATH,
+    ensure_user_config,
+    load_config,
+    resolve_all,
+    set_role,
+)
+from core.runtime.ollama_discovery import discover
+
+
+def _print_table() -> None:
+    resolved = resolve_all()
+    _, source = load_config()
+    print()
+    print("  ArkaOS Model Fabric — role routing")
+    print(f"  config: {USER_CONFIG_PATH if source == 'user' else source}")
+    print()
+    header = f"  {'ROLE':<14} {'PROVIDER':<12} {'MODEL':<34} EFFORT"
+    print(header)
+    print("  " + "─" * (len(header) - 2))
+    for item in resolved:
+        model = item.model or "(unset — configure alias)"
+        print(f"  {item.role:<14} {item.provider:<12} {model:<34} {item.effort}")
+    print()
+    _print_ollama_line()
+    print("  Change: npx arkaos models set <role> <provider>/<model> [--effort max]")
+    print("  Usage:  npx arkaos models usage [--period today|week|month|all]")
+    print()
+
+
+def _print_ollama_line() -> None:
+    status = discover()
+    if status.running and status.models:
+        names = ", ".join(m.name for m in status.models[:5])
+        extra = f" (+{len(status.models) - 5} more)" if len(status.models) > 5 else ""
+        print(f"  Ollama: running — {len(status.models)} local models: {names}{extra}")
+        print("          use them: npx arkaos models set mechanical ollama/<model>")
+    elif status.installed:
+        print("  Ollama: installed but not running — start it to unlock local models")
+    else:
+        print("  Ollama: not detected — https://ollama.com for free local models")
+    print()
+
+
+def _print_usage(period: str) -> None:
+    summary = summarise(period=period)
+    total = summary.total_cost_usd
+    total_s = f"${total:.4f}" if total is not None else "—"
+    print()
+    print(f"  Model Fabric — usage ({period})")
+    print(f"  calls: {summary.call_count}  tokens in/out: "
+          f"{summary.total_tokens_in}/{summary.total_tokens_out}  "
+          f"cached: {summary.total_cached_tokens}  est. cost: {total_s}")
+    for title, group in (("BY MODEL", summary.by_model),
+                         ("BY PROVIDER", summary.by_provider)):
+        if not group:
+            continue
+        print()
+        print(f"  {title:<28} {'CALLS':>6} {'IN':>10} {'OUT':>10} {'COST':>10}")
+        print("  " + "─" * 68)
+        ranked = sorted(group.items(),
+                        key=lambda kv: kv[1].get("total_cost_usd") or 0,
+                        reverse=True)
+        for name, bucket in ranked:
+            cost = bucket.get("total_cost_usd")
+            cost_s = f"${cost:.4f}" if cost is not None else "—"
+            print(f"  {(name or '(unknown)'):<28} "
+                  f"{bucket.get('call_count', 0):>6} "
+                  f"{bucket.get('total_tokens_in', 0):>10} "
+                  f"{bucket.get('total_tokens_out', 0):>10} {cost_s:>10}")
+    print()
+
+
+def _print_json() -> None:
+    payload = [item.model_dump() for item in resolve_all()]
+    print(json.dumps(payload, indent=2))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="arkaos models")
+    parser.add_argument("action", nargs="?", default="list",
+                        choices=["list", "init", "set", "usage", "discover"])
+    parser.add_argument("role", nargs="?")
+    parser.add_argument("target", nargs="?")
+    parser.add_argument("--effort", choices=["low", "medium", "high", "max"])
+    parser.add_argument("--period", choices=list(VALID_PERIODS), default="today")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    if args.action == "usage":
+        if args.as_json:
+            summary = summarise(period=args.period)
+            print(json.dumps({
+                "period": summary.period,
+                "call_count": summary.call_count,
+                "total_cost_usd": summary.total_cost_usd,
+                "total_tokens_in": summary.total_tokens_in,
+                "total_tokens_out": summary.total_tokens_out,
+                "total_cached_tokens": summary.total_cached_tokens,
+                "by_model": summary.by_model,
+                "by_provider": summary.by_provider,
+                "by_category": summary.by_category,
+            }, indent=2))
+        else:
+            _print_usage(args.period)
+        return 0
+    if args.action == "discover":
+        print(json.dumps(discover().to_dict(), indent=2))
+        return 0
+    if args.action == "init":
+        path = ensure_user_config()
+        print(f"  ✓ Model Fabric config: {path}")
+        return 0
+    if args.action == "set":
+        if not args.role or not args.target:
+            parser.error("set requires: <role> <provider>/<model>")
+        try:
+            item = set_role(args.role, args.target, effort=args.effort)
+        except ValueError as exc:
+            print(f"  ✗ {exc}", file=sys.stderr)
+            return 1
+        print(f"  ✓ {item.role} -> {item.provider}/{item.model} "
+              f"(effort {item.effort})")
+        return 0
+    if args.as_json:
+        _print_json()
+    else:
+        _print_table()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/core/runtime/ollama_discovery.py

@@ -0,0 +1,96 @@
+"""Ollama discovery — is it installed, is it running, which models exist.
+
+Model Fabric PR-C. Feeds three consumers: the `npx arkaos models` CLI
+(show what the machine can actually run), the `/arka-fusion` advisor
+(recommend local models for panel/mechanical roles), and the dashboard
+Models page. Read-only: never starts the daemon, never pulls models.
+
+Detection is two-layered on purpose: the binary can be installed while
+the daemon is stopped (installed=True, running=False lets the advisor
+say "start Ollama to unlock N local models" instead of pretending
+Ollama does not exist).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import urllib.error
+import urllib.request
+from dataclasses import asdict, dataclass, field
+
+_DEFAULT_HOST = "http://localhost:11434"
+_TAGS_TIMEOUT_S = 2.0
+
+
+@dataclass(frozen=True)
+class OllamaModel:
+    """One locally available model as reported by /api/tags."""
+
+    name: str
+    size_gb: float
+    family: str
+    parameter_size: str
+
+
+@dataclass(frozen=True)
+class OllamaStatus:
+    """Discovery result for the local Ollama installation."""
+
+    installed: bool
+    running: bool
+    host: str
+    models: list[OllamaModel] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def _host() -> str:
+    return os.environ.get("OLLAMA_HOST", _DEFAULT_HOST).rstrip("/")
+
+
+def binary_installed() -> bool:
+    """True when the `ollama` binary is on PATH."""
+    return shutil.which("ollama") is not None
+
+
+def _fetch_tags(host: str) -> list[dict] | None:
+    """GET /api/tags; None when the daemon is unreachable."""
+    try:
+        with urllib.request.urlopen(
+            f"{host}/api/tags", timeout=_TAGS_TIMEOUT_S
+        ) as response:
+            data = json.loads(response.read().decode("utf-8"))
+    except (urllib.error.URLError, TimeoutError, OSError,
+            json.JSONDecodeError):
+        return None
+    models = data.get("models")
+    return models if isinstance(models, list) else []
+
+
+def _parse_model(record: dict) -> OllamaModel:
+    details = record.get("details") or {}
+    size_bytes = int(record.get("size", 0) or 0)
+    return OllamaModel(
+        name=str(record.get("name", "")),
+        size_gb=round(size_bytes / 1_000_000_000, 1),
+        family=str(details.get("family", "") or ""),
+        parameter_size=str(details.get("parameter_size", "") or ""),
+    )
+
+
+def discover() -> OllamaStatus:
+    """Full discovery: binary on PATH, daemon reachable, model list."""
+    host = _host()
+    tags = _fetch_tags(host)
+    if tags is None:
+        return OllamaStatus(
+            installed=binary_installed(), running=False, host=host
+        )
+    models = [_parse_model(r) for r in tags if r.get("name")]
+    models.sort(key=lambda m: m.name)
+    # Daemon answering means Ollama is effectively installed even if the
+    # binary is not on this shell's PATH (e.g. Docker deployment).
+    return OllamaStatus(installed=True, running=True, host=host, models=models)