arkaos 4.2.0 → 4.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 **The Operating System for AI Agent Teams.**
 
-82 agents. 17 departments. 267 skills. Enterprise frameworks. Multi-runtime. One install.
+82 agents. 17 departments. 268 skills. Enterprise frameworks. Multi-runtime. One install.
 
 ```bash
 npx arkaos install

package/VERSION

@@ -1 +1 @@
-4.2.0
+4.3.0

package/arka/SKILL.md

@@ -24,7 +24,7 @@ does not replace the vault.
 # ArkaOS — Main Orchestrator
 
 > **The Operating System for AI Agent Teams**
-> 82 agents. 17 departments. 267 skills. Multi-runtime. Dashboard. Knowledge RAG.
+> 82 agents. 17 departments. 268 skills. Multi-runtime. Dashboard. Knowledge RAG.
 
 ## ⛔ Evidence flow — 4 gates (NON-NEGOTIABLE)
 

package/arka/skills/fusion/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: arka-fusion
+description: >
+  Model Fabric advisor and fusion configurator. Discovers what the machine
+  can run (Ollama local models, OpenRouter/Anthropic keys), reads the
+  current role routing, interviews the user about goals and constraints,
+  and recommends — with rationale — which model should run each role and
+  which panel+judge combination to use for fusion. Applies the approved
+  configuration via `npx arkaos models`. Trigger: "/arka-fusion", "fusion",
+  "que modelos usar", "configurar modelos", "model routing".
+allowed-tools: [Read, Bash, AskUserQuestion]
+---
+
+# /arka-fusion — Model Fabric Advisor
+
+You are the Model Fabric advisor. Your job: leave the user with a role →
+model mapping and a fusion panel that fit THEIR machine, keys, and goals —
+never a generic default. Constitution `model-routing` sets the posture:
+quality-critical roles get the best model available; only genuinely
+mechanical work economises.
+
+## Phase 1 — Discover (never skip, never assume)
+
+Run and read all three:
+
+```bash
+python -m core.runtime.model_router_cli discover        # Ollama + local models
+python -m core.runtime.model_router_cli --json          # current routing
+python -m core.runtime.model_router_cli usage --period week --json
+```
+
+Also check key presence (never print values): `OPENROUTER_API_KEY` /
+`ANTHROPIC_API_KEY` in env or `~/.arkaos/keys.json`.
+
+Interpret the discovery honestly:
+- Ollama **not installed** → local lane unavailable; say what installing
+  it would unlock (free mechanical/panel calls, privacy).
+- Ollama installed but **not running** → tell the user to start it; count
+  its models as one `ollama serve` away.
+- Ollama running → classify each local model by size/family: coder models
+  (qwen-coder, deepseek-coder) suit `mechanical` + code review panels;
+  large general models (30B+, kimi cloud) qualify for panel seats;
+  sub-8B models are mechanical-only. `:cloud` models are Ollama-proxied
+  remote models — panel-grade, not privacy-local.
+
+## Phase 2 — Interview (one AskUserQuestion, then dialogue)
+
+Ask about, at most 4 questions, adapting to what discovery found:
+1. **Prioridade** — máxima qualidade custe o que custar / equilíbrio /
+   privacidade local primeiro?
+2. **Fusion** — ativar painel multi-modelo para trabalho crítico
+   (2-5× chamadas por resposta, qualidade validada acima de qualquer
+   modelo solo) ou manter single-model por agora?
+3. **OpenRouter** — se não há chave: quer criar uma? (1 chave → Kimi,
+   DeepSeek, GPT, Gemini como participantes de painel.)
+4. Qualquer ambiguidade real que a discovery levantou.
+
+## Phase 3 — Recommend (framework-backed, named tradeoffs)
+
+Produce a table: role → provider/model + ONE-line rationale each. Rules:
+- `design/review/architecture/strategy/quality_gate` → best frontier
+  model available. NEVER a local small model, even if the user leans
+  cost-sensitive — offer fusion-with-budget-panel instead (OpenRouter
+  evidence: budget panel + frontier judge beats frontier solo at ~50%
+  cost).
+- `mechanical` → cheapest competent lane: local coder model if Ollama
+  runs one, else haiku-class.
+- Fusion panel: 2-3 DIVERSE models (different families — e.g. one
+  Anthropic, one Kimi/DeepSeek, one local large) + frontier judge.
+  Homogeneous panels waste the fan-out.
+- Cite `usage` data when it argues for a change ("80% of your tokens are
+  mechanical → moving them local saves X").
+
+## Phase 4 — Apply (only after explicit approval)
+
+```bash
+npx arkaos models set <role> <provider>/<model> --effort <effort>
+```
+
+For fusion panel/judge and aliases, edit `~/.arkaos/models.yaml` directly
+(keep comments). Show the final `npx arkaos models` table as proof and
+remind: the dashboard Models page shows the same state + live usage.
+
+## Hard rules
+
+- Discovery before advice — recommending a model the machine cannot run
+  is a constitution breach (`context-verification`).
+- Never print key values. Presence only.
+- Quality roles never downgrade below frontier (`model-routing`,
+  `excellence-mandate`). Push back if asked; offer budget fusion instead.
+- Every recommendation carries a rationale the user can disagree with.

package/core/fusion/__init__.py

@@ -0,0 +1,5 @@
+"""Fusion engine — panel of models answers, a judge synthesises."""
+
+from core.fusion.engine import FusionResult, FusionUnavailable, fuse
+
+__all__ = ["FusionResult", "FusionUnavailable", "fuse"]

package/core/fusion/cli.py

@@ -0,0 +1,37 @@
+"""Fusion CLI — smoke path for the panel → judge pipeline.
+
+Usage::
+
+    python -m core.fusion.cli "your question"
+"""
+
+from __future__ import annotations
+
+import sys
+
+from core.fusion.engine import FusionUnavailable, fuse
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = argv if argv is not None else sys.argv[1:]
+    if not args:
+        print("usage: python -m core.fusion.cli \"question\"", file=sys.stderr)
+        return 1
+    prompt = " ".join(args)
+    try:
+        result = fuse(prompt)
+    except FusionUnavailable as exc:
+        print(f"  ✗ {exc}", file=sys.stderr)
+        return 1
+    seats = ", ".join(
+        f"{a.provider}/{a.model}" + (" (failed)" if a.failed else "")
+        for a in result.answers
+    )
+    print(f"\n  Fusion — judge {result.judge_provider}/{result.judge_model} "
+          f"| panel: {seats}\n")
+    print(result.text)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/core/fusion/engine.py

@@ -0,0 +1,153 @@
+"""Fusion engine — panel → judge → synthesis (Model Fabric PR-D).
+
+Pattern validated by OpenRouter's DRACO results: a panel of diverse
+models answers the same prompt in parallel; a judge model receives every
+answer, analyses consensus, contradictions and blind spots, and writes
+the final synthesis. A budget panel + frontier judge beats frontier solo
+at roughly half the cost; self-fusion alone gains several points.
+
+Configuration lives in ``models.yaml`` (``fusion.judge`` +
+``fusion.panel`` — see ``core/runtime/model_router.py``). An empty panel
+means fusion is disabled; callers get ``FusionUnavailable`` and fall
+back to single-model completion.
+
+Consumers: Forge complex/super tiers, QG adversarial review, and the
+``python -m core.fusion.cli`` smoke path used by ``/arka-fusion``.
+"""
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+
+from core.runtime.llm_provider import LLMResponse, LLMUnavailable
+from core.runtime.model_router import ModelsConfig, RoleChoice, load_config
+
+_PANEL_MAX_TOKENS = 2000
+_JUDGE_MAX_TOKENS = 3000
+
+_JUDGE_SYSTEM = (
+    "You are the judge in a model-fusion panel. You receive one question "
+    "and several independent answers from different models. Analyse them: "
+    "consensus points, contradictions, partial coverage, unique insights, "
+    "blind spots. Then write the best possible final answer grounded in "
+    "that analysis. Output ONLY the final answer — no meta-commentary "
+    "about the panel."
+)
+
+
+class FusionUnavailable(RuntimeError):
+    """Fusion cannot run: empty panel or no reachable participant."""
+
+
+@dataclass(frozen=True)
+class PanelAnswer:
+    provider: str
+    model: str
+    text: str
+    failed: bool = False
+    error: str = ""
+
+
+@dataclass(frozen=True)
+class FusionResult:
+    text: str
+    judge_provider: str
+    judge_model: str
+    answers: list[PanelAnswer] = field(default_factory=list)
+    tokens_in: int = 0
+    tokens_out: int = 0
+
+
+def _provider_for(choice: RoleChoice, config: ModelsConfig):
+    """Instantiate the LLM provider for one panel/judge seat."""
+    from core.runtime.model_router import _resolve_alias
+    model = _resolve_alias(config, choice.provider, choice.model)
+    if choice.provider == "ollama":
+        from core.runtime.ollama_provider import OllamaProvider
+        return OllamaProvider(model=model), model
+    if choice.provider == "openrouter":
+        from core.runtime.openrouter_provider import OpenRouterProvider
+        return OpenRouterProvider(model=model), model
+    # runtime / anthropic / anything else: provider chain decides; the
+    # model override is advisory (subagent uses the session model).
+    from core.runtime.llm_provider import get_llm_provider
+    return get_llm_provider(), model
+
+
+def _ask_participant(
+    choice: RoleChoice, config: ModelsConfig, prompt: str, system: str
+) -> PanelAnswer:
+    try:
+        provider, model = _provider_for(choice, config)
+        response: LLMResponse = provider.complete(
+            prompt, max_tokens=_PANEL_MAX_TOKENS, system=system
+        )
+        if not response.text.strip():
+            return PanelAnswer(choice.provider, model, "", failed=True,
+                               error="empty response")
+        return PanelAnswer(choice.provider, model, response.text)
+    except LLMUnavailable as exc:
+        return PanelAnswer(choice.provider, choice.model, "", failed=True,
+                           error=str(exc))
+    except Exception as exc:  # noqa: BLE001 — one dead seat must not kill the panel
+        return PanelAnswer(choice.provider, choice.model, "", failed=True,
+                           error=f"unexpected: {exc}")
+
+
+def _judge_prompt(prompt: str, answers: list[PanelAnswer]) -> str:
+    blocks = []
+    for i, answer in enumerate(answers, 1):
+        blocks.append(
+            f"--- Answer {i} (model: {answer.model}) ---\n{answer.text}"
+        )
+    return (
+        f"QUESTION:\n{prompt}\n\n"
+        f"PANEL ANSWERS ({len(answers)}):\n\n" + "\n\n".join(blocks)
+    )
+
+
+def fuse(
+    prompt: str,
+    *,
+    system: str = "",
+    config: ModelsConfig | None = None,
+) -> FusionResult:
+    """Run the full panel → judge → synthesis pipeline.
+
+    Raises FusionUnavailable when the panel is empty (fusion disabled in
+    models.yaml) or when every participant fails — the caller falls back
+    to a single-model completion, never to silence.
+    """
+    if config is None:
+        config, _ = load_config()
+    panel = config.fusion.panel
+    if not panel:
+        raise FusionUnavailable(
+            "fusion panel is empty — configure fusion.panel in models.yaml "
+            "(try /arka-fusion for guided setup)"
+        )
+    with ThreadPoolExecutor(max_workers=max(len(panel), 1)) as pool:
+        answers = list(pool.map(
+            lambda choice: _ask_participant(choice, config, prompt, system),
+            panel,
+        ))
+    alive = [a for a in answers if not a.failed]
+    if not alive:
+        details = "; ".join(f"{a.provider}/{a.model}: {a.error}" for a in answers)
+        raise FusionUnavailable(f"every panel participant failed — {details}")
+
+    judge_provider, judge_model = _provider_for(config.fusion.judge, config)
+    verdict = judge_provider.complete(
+        _judge_prompt(prompt, alive),
+        max_tokens=_JUDGE_MAX_TOKENS,
+        system=_JUDGE_SYSTEM,
+    )
+    return FusionResult(
+        text=verdict.text,
+        judge_provider=config.fusion.judge.provider,
+        judge_model=judge_model or verdict.model,
+        answers=answers,
+        tokens_in=verdict.tokens_in,
+        tokens_out=verdict.tokens_out,
+    )

package/core/governance/redo_counter.py

@@ -0,0 +1,81 @@
+"""Quality Gate redo-loop counter (excellence-mandate, v4.2.0).
+
+The constitution caps REJECTED redo cycles at 2 — a third REJECTED
+escalates to the operator with the full verdict instead of another
+silent retry. This module is the mechanical counter behind that rule
+(previously declarative only).
+
+State: ``~/.arkaos/quality-gate/redo-counters.json`` keyed by session id.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+REDO_CAP = 2
+
+_STATE_PATH = Path.home() / ".arkaos" / "quality-gate" / "redo-counters.json"
+
+
+@dataclass(frozen=True)
+class RedoState:
+    session_id: str
+    count: int
+    escalate: bool
+
+    def to_message(self) -> str:
+        if not self.escalate:
+            return (
+                f"[arka:qg] REJECTED — redo cycle {self.count}/{REDO_CAP}. "
+                f"Looping back to execution with the issue list."
+            )
+        return (
+            f"[arka:qg:escalate] REJECTED {self.count} times — cap of "
+            f"{REDO_CAP} redo cycles exceeded (excellence-mandate). "
+            f"STOP: present the full verdict to the operator and wait for "
+            f"a decision. Do not retry silently."
+        )
+
+
+def _load(path: Path) -> dict:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def record_rejected(session_id: str, path: Path | None = None) -> RedoState:
+    """Increment the REJECTED counter; escalate above the cap."""
+    state_path = path or _STATE_PATH
+    data = _load(state_path)
+    count = int(data.get(session_id, 0) or 0) + 1
+    data[session_id] = count
+    try:
+        state_path.parent.mkdir(parents=True, exist_ok=True)
+        state_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    except OSError:
+        pass  # counter must never block the gate itself
+    return RedoState(session_id=session_id, count=count,
+                     escalate=count > REDO_CAP)
+
+
+def reset(session_id: str, path: Path | None = None) -> None:
+    """Clear the counter — called on APPROVED."""
+    state_path = path or _STATE_PATH
+    data = _load(state_path)
+    if session_id in data:
+        del data[session_id]
+        try:
+            state_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+        except OSError:
+            pass
+
+
+def current(session_id: str, path: Path | None = None) -> RedoState:
+    """Read-only view of the counter."""
+    count = int(_load(path or _STATE_PATH).get(session_id, 0) or 0)
+    return RedoState(session_id=session_id, count=count,
+                     escalate=count > REDO_CAP)

package/core/runtime/model_router_cli.py

@@ -6,6 +6,7 @@ Usage::
     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
@@ -14,6 +15,7 @@ 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,
@@ -21,6 +23,7 @@ from core.runtime.model_router import (
     resolve_all,
     set_role,
 )
+from core.runtime.ollama_discovery import discover
 
 
 def _print_table() -> None:
@@ -37,7 +40,52 @@ def _print_table() -> None:
         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()
 
 
@@ -49,13 +97,34 @@ def _print_json() -> None:
 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"])
+                        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}")

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)

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',

package/dashboard/app/pages/models.vue

@@ -0,0 +1,404 @@
+<script setup lang="ts">
+// Model Fabric (PR-C) — who runs what, what this machine offers, where
+// tokens flow. Backed by /api/models, /api/models/role, /api/models/usage.
+
+interface ResolvedRole {
+  role: string
+  provider: string
+  model: string
+  effort: string
+  source: string
+}
+
+interface OllamaModel {
+  name: string
+  size_gb: number
+  family: string
+  parameter_size: string
+}
+
+interface ModelsOverview {
+  source: string
+  config_path: string
+  roles: ResolvedRole[]
+  providers: Record<string, { type: string }>
+  aliases: Record<string, Record<string, string>>
+  fusion: { judge: Record<string, string>, panel: Array<Record<string, string>> }
+  ollama: { installed: boolean, running: boolean, host: string, models: OllamaModel[] }
+  keys: { openrouter: boolean, anthropic: boolean }
+}
+
+interface BreakdownRow {
+  total_cost_usd: number | null
+  total_tokens_in: number
+  total_tokens_out: number
+  call_count: number
+}
+
+interface UsageSummary {
+  period: string
+  call_count: number
+  total_cost_usd: number | null
+  total_tokens_in: number
+  total_tokens_out: number
+  total_cached_tokens: number
+  by_model: Record<string, BreakdownRow>
+  by_provider: Record<string, BreakdownRow>
+}
+
+type Period = 'today' | 'week' | 'month' | 'all'
+
+const { fetchApi, apiBase } = useApi()
+const toast = useToast()
+
+const {
+  data: overview,
+  status,
+  error,
+  refresh,
+} = fetchApi<ModelsOverview>('/api/models')
+
+const period = ref<Period>('week')
+const periodOptions: { label: string, value: Period }[] = [
+  { label: 'Today', value: 'today' },
+  { label: '7 days', value: 'week' },
+  { label: '30 days', value: 'month' },
+  { label: 'All time', value: 'all' },
+]
+const { data: usage, refresh: refreshUsage } = fetchApi<UsageSummary>(
+  '/api/models/usage',
+  { query: computed(() => ({ period: period.value })) },
+)
+watch(period, () => refreshUsage())
+
+// ─── Provider lanes (signature element: live availability strip) ────────
+
+const QUALITY_ROLES = new Set(['design', 'review', 'architecture', 'strategy', 'quality_gate'])
+
+const laneStyles: Record<string, { badge: string, dot: string }> = {
+  runtime: { badge: 'text-primary bg-primary/10', dot: 'bg-primary' },
+  ollama: { badge: 'text-amber-600 dark:text-amber-400 bg-amber-500/10', dot: 'bg-amber-500' },
+  openrouter: { badge: 'text-violet-600 dark:text-violet-400 bg-violet-500/10', dot: 'bg-violet-500' },
+  anthropic: { badge: 'text-sky-600 dark:text-sky-400 bg-sky-500/10', dot: 'bg-sky-500' },
+}
+
+function laneStyle(provider: string) {
+  return laneStyles[provider] ?? { badge: 'text-muted bg-muted/10', dot: 'bg-muted' }
+}
+
+interface Lane {
+  id: string
+  label: string
+  live: boolean
+  detail: string
+}
+
+const lanes = computed<Lane[]>(() => {
+  const o = overview.value
+  if (!o) return []
+  const ollama = o.ollama ?? { installed: false, running: false, models: [] }
+  const keys = o.keys ?? { openrouter: false, anthropic: false }
+  const ollamaDetail = ollama.running
+    ? `${(ollama.models ?? []).length} local models`
+    : ollama.installed ? 'installed, not running' : 'not installed'
+  return [
+    { id: 'runtime', label: 'Runtime', live: true, detail: 'active CLI session' },
+    { id: 'ollama', label: 'Ollama', live: ollama.running, detail: ollamaDetail },
+    { id: 'openrouter', label: 'OpenRouter', live: keys.openrouter, detail: keys.openrouter ? 'key configured' : 'no key' },
+    { id: 'anthropic', label: 'Anthropic', live: keys.anthropic, detail: keys.anthropic ? 'key configured' : 'no key' },
+  ]
+})
+
+// ─── Inline role re-routing ──────────────────────────────────────────────
+
+const editingRole = ref<string | null>(null)
+const editTarget = ref('')
+const saving = ref(false)
+
+const targetOptions = computed(() => {
+  const o = overview.value
+  if (!o) return []
+  const options: { label: string, value: string }[] = []
+  for (const alias of ['best', 'default', 'fast']) {
+    options.push({ label: `runtime / ${alias}`, value: `runtime/${alias}` })
+  }
+  for (const m of o.ollama?.models ?? []) {
+    options.push({ label: `ollama / ${m.name}`, value: `ollama/${m.name}` })
+  }
+  if (o.keys?.anthropic) {
+    for (const alias of ['best', 'default', 'fast']) {
+      options.push({ label: `anthropic / ${alias}`, value: `anthropic/${alias}` })
+    }
+  }
+  if (o.keys?.openrouter) {
+    options.push({ label: 'openrouter / (type model id)', value: 'openrouter/' })
+  }
+  return options
+})
+
+function startEdit(row: ResolvedRole) {
+  editingRole.value = row.role
+  editTarget.value = `${row.provider}/${row.model}`
+}
+
+async function saveEdit(role: string) {
+  if (!editTarget.value.includes('/')) {
+    toast.add({ title: 'Target must be provider/model', color: 'error' })
+    return
+  }
+  saving.value = true
+  try {
+    await $fetch(`${apiBase.value}/api/models/role`, {
+      method: 'POST',
+      body: { role, target: editTarget.value },
+    })
+    toast.add({ title: `${role} re-routed`, description: editTarget.value, color: 'success', icon: 'i-lucide-route' })
+    editingRole.value = null
+    await refresh()
+  } catch (err) {
+    toast.add({
+      title: 'Re-route failed',
+      description: err instanceof Error ? err.message : 'unknown error',
+      color: 'error',
+    })
+  } finally {
+    saving.value = false
+  }
+}
+
+async function useForMechanical(model: OllamaModel) {
+  editTarget.value = `ollama/${model.name}`
+  await saveEdit('mechanical')
+}
+
+// ─── Usage bars ──────────────────────────────────────────────────────────
+
+const usageRows = computed<Array<[string, BreakdownRow]>>(() =>
+  Object.entries(usage.value?.by_model ?? {}).sort(
+    (a, b) => (b[1].total_tokens_in + b[1].total_tokens_out) - (a[1].total_tokens_in + a[1].total_tokens_out),
+  ).slice(0, 10),
+)
+
+const maxUsageTokens = computed(() => {
+  const max = usageRows.value.reduce(
+    (acc, [, r]) => Math.max(acc, r.total_tokens_in + r.total_tokens_out), 0,
+  )
+  return max > 0 ? max : 1
+})
+
+function formatTokens(value: number): string {
+  if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}M`
+  if (value >= 1_000) return `${(value / 1_000).toFixed(1)}K`
+  return value.toString()
+}
+
+function formatCost(value: number | null): string {
+  if (value === null || value === undefined) return 'n/a'
+  if (value === 0) return '$0'
+  if (value < 0.01) return `$${value.toFixed(4)}`
+  return `$${value.toFixed(2)}`
+}
+</script>
+
+<template>
+  <UDashboardPanel id="models">
+    <template #header>
+      <UDashboardNavbar title="Models">
+        <template #right>
+          <UButton
+            label="Refresh"
+            variant="ghost"
+            icon="i-lucide-refresh-cw"
+            size="sm"
+            @click="() => { refresh(); refreshUsage() }"
+          />
+        </template>
+      </UDashboardNavbar>
+    </template>
+
+    <template #body>
+      <DashboardState
+        :status="status"
+        :error="error"
+        loading-label="Loading model fabric"
+        :on-retry="() => refresh()"
+      >
+        <div class="space-y-6">
+          <!-- Provider lanes: live availability strip -->
+          <UCard>
+            <div class="grid grid-cols-2 md:grid-cols-4 gap-4">
+              <div
+                v-for="lane in lanes"
+                :key="lane.id"
+                class="flex items-start gap-3"
+              >
+                <span class="relative flex h-2.5 w-2.5 mt-1.5">
+                  <span
+                    v-if="lane.live"
+                    class="animate-ping absolute inline-flex h-full w-full rounded-full opacity-60 motion-reduce:hidden"
+                    :class="laneStyle(lane.id).dot"
+                  />
+                  <span
+                    class="relative inline-flex rounded-full h-2.5 w-2.5"
+                    :class="lane.live ? laneStyle(lane.id).dot : 'bg-muted/40'"
+                  />
+                </span>
+                <div>
+                  <p class="text-sm font-semibold">{{ lane.label }}</p>
+                  <p class="text-xs text-muted">{{ lane.detail }}</p>
+                </div>
+              </div>
+            </div>
+          </UCard>
+
+          <!-- Role routing -->
+          <UCard>
+            <template #header>
+              <div class="flex items-center justify-between">
+                <p class="text-xs font-semibold text-muted uppercase tracking-wider">
+                  Role routing
+                </p>
+                <p class="text-xs text-muted font-mono hidden md:block">{{ overview?.config_path }}</p>
+              </div>
+            </template>
+            <div class="divide-y divide-default">
+              <div
+                v-for="row in overview?.roles ?? []"
+                :key="row.role"
+                class="flex items-center gap-3 py-2.5"
+              >
+                <UIcon
+                  :name="QUALITY_ROLES.has(row.role) ? 'i-lucide-gem' : 'i-lucide-cog'"
+                  class="size-4 shrink-0"
+                  :class="QUALITY_ROLES.has(row.role) ? 'text-primary' : 'text-muted'"
+                />
+                <span class="w-32 shrink-0 text-sm font-medium">{{ row.role }}</span>
+                <template v-if="editingRole === row.role">
+                  <UInputMenu
+                    v-model="editTarget"
+                    :items="targetOptions"
+                    value-key="value"
+                    create-item
+                    size="sm"
+                    class="flex-1 max-w-xs"
+                    placeholder="provider/model"
+                    @create="(item: string) => { editTarget = item }"
+                  />
+                  <UButton size="xs" label="Save" :loading="saving" @click="saveEdit(row.role)" />
+                  <UButton size="xs" variant="ghost" label="Cancel" @click="editingRole = null" />
+                </template>
+                <template v-else>
+                  <span
+                    class="inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium"
+                    :class="laneStyle(row.provider).badge"
+                  >
+                    {{ row.provider }}
+                  </span>
+                  <span class="text-sm font-mono truncate">
+                    {{ row.model || '(unset)' }}
+                  </span>
+                  <UBadge variant="subtle" size="sm" color="neutral">{{ row.effort }}</UBadge>
+                  <UButton
+                    icon="i-lucide-pencil"
+                    variant="ghost"
+                    size="xs"
+                    class="ml-auto"
+                    :aria-label="`Edit ${row.role} routing`"
+                    @click="startEdit(row)"
+                  />
+                </template>
+              </div>
+            </div>
+          </UCard>
+
+          <div class="grid grid-cols-1 lg:grid-cols-2 gap-6">
+            <!-- Local Ollama models -->
+            <UCard>
+              <template #header>
+                <p class="text-xs font-semibold text-muted uppercase tracking-wider">
+                  Local models (Ollama)
+                </p>
+              </template>
+              <div v-if="overview?.ollama?.running && (overview.ollama?.models ?? []).length" class="divide-y divide-default">
+                <div
+                  v-for="m in (overview.ollama?.models ?? [])"
+                  :key="m.name"
+                  class="flex items-center gap-3 py-2"
+                >
+                  <UIcon name="i-lucide-hard-drive" class="size-4 text-amber-500 shrink-0" />
+                  <div class="min-w-0 flex-1">
+                    <p class="text-sm font-mono truncate">{{ m.name }}</p>
+                    <p class="text-xs text-muted">
+                      {{ m.family || 'unknown family' }}
+                      <template v-if="m.parameter_size"> · {{ m.parameter_size }}</template>
+                      <template v-if="m.size_gb"> · {{ m.size_gb }} GB</template>
+                      <template v-if="!m.size_gb"> · cloud-proxied</template>
+                    </p>
+                  </div>
+                  <UButton
+                    size="xs"
+                    variant="soft"
+                    label="Use for mechanical"
+                    :loading="saving"
+                    @click="useForMechanical(m)"
+                  />
+                </div>
+              </div>
+              <div v-else-if="overview?.ollama?.installed" class="py-6 text-center">
+                <p class="text-sm text-muted">Ollama is installed but not running.</p>
+                <p class="text-xs text-muted mt-1 font-mono">ollama serve</p>
+              </div>
+              <div v-else class="py-6 text-center">
+                <p class="text-sm text-muted">No local models yet.</p>
+                <p class="text-xs text-muted mt-1">
+                  Install Ollama to run free local models for mechanical work and fusion panels.
+                </p>
+              </div>
+            </UCard>
+
+            <!-- Usage by model -->
+            <UCard>
+              <template #header>
+                <div class="flex items-center justify-between">
+                  <p class="text-xs font-semibold text-muted uppercase tracking-wider">
+                    Usage by model
+                  </p>
+                  <USelect v-model="period" :items="periodOptions" size="xs" class="min-w-24" aria-label="Usage period" />
+                </div>
+              </template>
+              <div v-if="usageRows.length" class="space-y-3">
+                <div class="flex items-baseline justify-between">
+                  <p class="text-sm">
+                    <span class="font-semibold">{{ usage?.call_count ?? 0 }}</span>
+                    <span class="text-muted"> calls · </span>
+                    <span class="font-semibold">{{ formatTokens((usage?.total_tokens_in ?? 0) + (usage?.total_tokens_out ?? 0)) }}</span>
+                    <span class="text-muted"> tokens</span>
+                  </p>
+                  <p class="text-sm font-semibold">{{ formatCost(usage?.total_cost_usd ?? null) }}</p>
+                </div>
+                <div v-for="[name, row] in usageRows" :key="name" class="space-y-1">
+                  <div class="flex items-center justify-between text-xs">
+                    <span class="font-mono truncate">{{ name || '(unattributed)' }}</span>
+                    <span class="text-muted shrink-0 ml-2">
+                      {{ formatTokens(row.total_tokens_in + row.total_tokens_out) }} · {{ row.call_count }} calls
+                    </span>
+                  </div>
+                  <div class="h-1.5 rounded-full bg-muted/20 overflow-hidden">
+                    <div
+                      class="h-full rounded-full bg-primary"
+                      :style="{ width: `${Math.max(2, ((row.total_tokens_in + row.total_tokens_out) / maxUsageTokens) * 100)}%` }"
+                    />
+                  </div>
+                </div>
+              </div>
+              <div v-else class="py-6 text-center">
+                <p class="text-sm text-muted">No usage recorded for this period.</p>
+                <p class="text-xs text-muted mt-1">Calls made through the Model Fabric land here automatically.</p>
+              </div>
+            </UCard>
+          </div>
+        </div>
+      </DashboardState>
+    </template>
+  </UDashboardPanel>
+</template>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "4.2.0"
+version = "4.3.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}

package/scripts/dashboard-api.py

@@ -864,6 +864,85 @@ def commands(dept: Optional[str] = Query(None), q: Optional[str] = Query(None)):
     return {"commands": data, "total": len(data)}
 
 
+@app.get("/api/models")
+def models_overview():
+    """Model Fabric: roles, providers, Ollama discovery, key presence."""
+    from core.runtime.model_router import USER_CONFIG_PATH, load_config, resolve_all
+    from core.runtime.ollama_discovery import discover
+
+    config, source = load_config()
+    keys_path = Path.home() / ".arkaos" / "keys.json"
+    try:
+        keys = json.loads(keys_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        keys = {}
+    return {
+        "source": source,
+        "config_path": str(USER_CONFIG_PATH),
+        "roles": [item.model_dump() for item in resolve_all()],
+        "providers": {
+            name: {"type": spec.get("type", "")}
+            for name, spec in config.providers.items()
+        },
+        "aliases": config.aliases,
+        "fusion": config.fusion.model_dump(),
+        "ollama": discover().to_dict(),
+        "keys": {
+            "openrouter": bool(
+                os.environ.get("OPENROUTER_API_KEY")
+                or keys.get("OPENROUTER_API_KEY")
+            ),
+            "anthropic": bool(os.environ.get("ANTHROPIC_API_KEY")),
+        },
+    }
+
+
+@app.post("/api/models/role")
+async def models_set_role(request: Request):
+    """Re-route a role: {role, target: 'provider/model', effort?}."""
+    from core.runtime.model_router import set_role
+
+    body = await request.json()
+    role = str(body.get("role", "")).strip()
+    target = str(body.get("target", "")).strip()
+    effort = body.get("effort") or None
+    if not role or not target:
+        return JSONResponse(
+            {"error": "role and target (provider/model) are required"},
+            status_code=422,
+        )
+    try:
+        item = set_role(role, target, effort=effort)
+    except ValueError as exc:
+        return JSONResponse({"error": str(exc)}, status_code=422)
+    return item.model_dump()
+
+
+@app.get("/api/models/usage")
+def models_usage(period: str = "today"):
+    """Per-model/provider/category token + cost aggregation."""
+    from core.runtime.llm_cost_telemetry import VALID_PERIODS, summarise
+
+    if period not in VALID_PERIODS:
+        return JSONResponse(
+            {"error": f"period must be one of {list(VALID_PERIODS)}"},
+            status_code=422,
+        )
+    summary = summarise(period=period)
+    return {
+        "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,
+        "cache_hit_rate": summary.cache_hit_rate,
+        "by_model": summary.by_model,
+        "by_provider": summary.by_provider,
+        "by_category": summary.by_category,
+    }
+
+
 @app.get("/api/budget")
 def budget_all():
     mgr = _get_budget_manager()