arkaos 4.1.0 → 4.2.0

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/installer/autostart.js

@@ -29,6 +29,9 @@ export function unitFor(os, { repoRoot, home }) {
   if (os === "darwin") {
     const startScript = `${repoRoot}/scripts/start-dashboard.sh`;
     const log = `${home}/.arkaos/logs/dashboard-autostart.log`;
+    // AbandonProcessGroup: the launcher backgrounds the API/UI and exits;
+    // without it launchd kills the whole process group on exit and the
+    // dashboard dies seconds after boot. `ensure` keeps re-loads idempotent.
     const content = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -39,14 +42,19 @@ export function unitFor(os, { repoRoot, home }) {
   <array>
     <string>/bin/bash</string>
     <string>${startScript}</string>
+    <string>ensure</string>
   </array>
   <key>EnvironmentVariables</key>
   <dict>
     <key>ARKAOS_ROOT</key>
     <string>${repoRoot}</string>
+    <key>ARKAOS_NO_BROWSER</key>
+    <string>1</string>
   </dict>
   <key>RunAtLoad</key>
   <true/>
+  <key>AbandonProcessGroup</key>
+  <true/>
   <key>StandardOutPath</key>
   <string>${log}</string>
   <key>StandardErrorPath</key>
@@ -63,14 +71,19 @@ export function unitFor(os, { repoRoot, home }) {
 
   if (os === "linux") {
     const startScript = `${repoRoot}/scripts/start-dashboard.sh`;
+    // oneshot + RemainAfterExit: the launcher backgrounds the API/UI and
+    // exits; Type=simple would mark the unit dead on exit and systemd would
+    // reap the children with the cgroup. `ensure` keeps restarts idempotent.
     const content = `[Unit]
 Description=ArkaOS Dashboard (Python API + UI)
 After=network.target
 
 [Service]
-Type=simple
+Type=oneshot
+RemainAfterExit=yes
 Environment=ARKAOS_ROOT=${repoRoot}
-ExecStart=/bin/bash ${startScript}
+Environment=ARKAOS_NO_BROWSER=1
+ExecStart=/bin/bash ${startScript} ensure
 Restart=on-failure
 
 [Install]
@@ -87,6 +100,7 @@ WantedBy=default.target
     const ps1 = join(repoRoot, "scripts", "start-dashboard.ps1");
     const content = `@echo off
 rem ArkaOS dashboard autostart (login).
+set ARKAOS_NO_BROWSER=1
 powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "${ps1}"
 `;
     return {

package/installer/cli.js

@@ -25,6 +25,9 @@ const { values, positionals } = parseArgs({
     // `values.fix` rather than as a free positional under strict:false.
     // Eliminates the dead-branch fallback flagged by Marta in PR2's QG.
     fix: { type: "boolean" },
+    // Model Fabric PR-A — `npx arkaos models [--json] [set ... --effort max]`
+    json: { type: "boolean" },
+    effort: { type: "string" },
   },
   allowPositionals: true,
   strict: false,
@@ -51,6 +54,8 @@ Usage:
   npx arkaos dashboard        Start monitoring dashboard
   npx arkaos autostart <enable|disable|status>  Start dashboard on boot
   npx arkaos keys             Manage API keys (OpenAI, fal.ai, etc.)
+  npx arkaos models           Model Fabric: which model runs each role
+  npx arkaos models set <role> <provider>/<model>  Re-route a role
   npx arkaos doctor           Run health checks
   npx arkaos uninstall        Remove ArkaOS
 
@@ -154,6 +159,24 @@ async function main() {
       break;
     }
 
+    case "models": {
+      const { execSync } = await import("node:child_process");
+      const repoRootModels = join(__dirname, "..");
+      const pyModels = getArkaosPython();
+      if (!pyModels) { console.error("No Python found. Run: npx arkaos install"); process.exit(1); }
+      const modelArgs = positionals.slice(1).map((a) => `"${a}"`).join(" ");
+      const effortFlag = values.effort ? ` --effort "${values.effort}"` : "";
+      const jsonFlag = values.json ? " --json" : "";
+      try {
+        execSync(`"${pyModels}" -m core.runtime.model_router_cli ${modelArgs}${effortFlag}${jsonFlag}`, {
+          stdio: "inherit",
+          cwd: repoRootModels,
+          env: { ...process.env, ARKAOS_ROOT: repoRootModels, PYTHONPATH: repoRootModels },
+        });
+      } catch { process.exit(1); }
+      break;
+    }
+
     case "index": {
       const { execSync } = await import("node:child_process");
       const indexArgs = positionals.slice(1).join(" ");

package/installer/keys.js

@@ -6,6 +6,7 @@ const KEYS_PATH = join(homedir(), ".arkaos", "keys.json");
 
 const PROVIDERS = {
   OPENAI_API_KEY: { name: "OpenAI", used_for: "Whisper transcription, embeddings, GPT" },
+  OPENROUTER_API_KEY: { name: "OpenRouter", used_for: "Model Fabric: one key, hundreds of models (Kimi, DeepSeek, GPT, Gemini) for roles + fusion" },
   GOOGLE_API_KEY: { name: "Google", used_for: "Gemini API, Nano Banana, Google Cloud AI" },
   FAL_API_KEY: { name: "fal.ai", used_for: "Image generation, video generation" },
   MAGIC_API_KEY: { name: "21st.dev Magic", used_for: "Frontend UI/UX component generation (Magic MCP)" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "4.1.0",
+  "version": "4.2.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.1.0"
+version = "4.2.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}
@@ -35,6 +35,8 @@ knowledge = [
 dashboard = [
     "fastapi>=0.115.0",
     "uvicorn>=0.32.0",
+    "python-multipart>=0.0.9",
+    "websockets>=12.0",
 ]
 ingest = [
     "yt-dlp>=2024.0",

package/scripts/start-dashboard.sh

@@ -10,6 +10,30 @@ VENV_PYTHON="$HOME/.arkaos/venv/bin/python"
 
 mkdir -p "$HOME/.arkaos"
 
+# ── Args ──
+# `ensure`       — idempotent mode: exit 0 if API+UI already healthy,
+#                  otherwise fall through to a full start. Safe to call from
+#                  SessionStart hooks and launchd/systemd boot units.
+# `--no-browser` — do not open the browser after start (also via
+#                  ARKAOS_NO_BROWSER=1 env, for boot/hook contexts).
+MODE="start"
+for arg in "$@"; do
+  case "$arg" in
+    ensure) MODE="ensure" ;;
+    --no-browser) ARKAOS_NO_BROWSER=1 ;;
+  esac
+done
+
+if [ "$MODE" = "ensure" ] && [ -f "$PORT_FILE" ]; then
+  # shellcheck disable=SC1090
+  source "$PORT_FILE"
+  if curl -sf --max-time 2 "http://localhost:${API_PORT:-0}/api/overview" >/dev/null 2>&1 \
+     && curl -sf --max-time 2 "http://localhost:${UI_PORT:-0}/" >/dev/null 2>&1; then
+    echo "  ✓ Dashboard already running (API :${API_PORT}, UI :${UI_PORT})"
+    exit 0
+  fi
+fi
+
 # ── Venv guard (PR2 v3.73.1 — Force Specialist Dispatch dogfood) ──
 # Previously the dashboard fell back to ambient `python3` when the venv
 # wasn't available. That hid broken-venv conditions (Homebrew patch
@@ -133,7 +157,7 @@ echo "        or kill \$(cat $PID_FILE)"
 echo ""
 
 # Wait for UI to be ready
-if [ -n "$UI_PID" ]; then
+if [ -n "$UI_PID" ] && [ -z "${ARKAOS_NO_BROWSER:-}" ]; then
   sleep 5
   # Open browser
   if command -v open >/dev/null 2>&1; then