arkaos 4.5.0 → 4.6.0

package/VERSION

@@ -1 +1 @@
-4.5.0
+4.6.0

package/arka/SKILL.md

@@ -179,9 +179,10 @@ violation (squad-routing, arka-supremacy, spec-driven, mandatory-qa).
 
 | Command | Description |
 |---------|-------------|
-| `/arka status` | System status (version, departments, agents, active projects). Includes **LLM costs (24h)** section: top-line cost + cache hit rate + call count from `core.runtime.llm_cost_telemetry.summarise(period="today")`. Also includes **Enforcement (24h)** section: total calls, block rate, top blocked tools/reasons from `core.governance.enforcement_telemetry.summarise(period="today")` (PR19 v2.41.0). Plus **Reorganization (today)** section: today's proposal path + artifact count from `core.cognition.reorganizer_scheduler.status_summary()` (PR24 v2.46.0). Plus **Model routing** section: gateway live/off + resolved per-slot routes + served counts from `core.runtime.model_routing_check.status_summary()`. |
+| `/arka status` | System status (version, departments, agents, active projects). Includes **LLM costs (24h)** section: top-line cost + cache hit rate + call count from `core.runtime.llm_cost_telemetry.summarise(period="today")`. Also includes **Enforcement (24h)** section: total calls, block rate, top blocked tools/reasons from `core.governance.enforcement_telemetry.summarise(period="today")` (PR19 v2.41.0). Plus **Reorganization (today)** section: today's proposal path + artifact count from `core.cognition.reorganizer_scheduler.status_summary()` (PR24 v2.46.0). Plus **Model routing** section: gateway live/off + resolved per-slot routes + served counts from `core.runtime.model_routing_check.status_summary()`. Plus **MCP usage (24h)** section: total calls + servers in use + top servers from `core.runtime.mcp_telemetry.summarise(period="today")`. |
 | `/arka costs [period]` | LLM cost visibility — aggregates telemetry by day/week/month/all, with top expensive sessions. See `arka/skills/costs/SKILL.md`. Shells out to `~/.arkaos/bin/arka-py -m core.runtime.llm_cost_telemetry_cli <period>`. |
 | `/arka enforcement [period]` | Enforcement compliance — aggregates flow-marker enforcement telemetry by day/week/month/all. Shows block rate, top blocked tools, top reasons. Shells out to `~/.arkaos/bin/arka-py -m core.governance.enforcement_telemetry_cli <period>`. |
+| `/arka mcps [period]` | MCP usage — aggregates the PostToolUse MCP telemetry (`~/.arkaos/telemetry/mcp-usage.jsonl`) by day/week/month/all. Shows total calls, servers in use, top servers and top tools. Shells out to `~/.arkaos/bin/arka-py -m core.runtime.mcp_telemetry_cli <period>`. |
 | `/arka compliance [period]` | Behavior compliance summary (PR29 v2.48.0) — aggregates stop-hook telemetry by day/week/month/all. Shows rates for the four contracts: closing marker, `[arka:meta]` tag, KB citation pass, sycophancy clean. Shells out to `~/.arkaos/bin/arka-py -m core.governance.compliance_telemetry_cli <period>`. |
 | `/arka reorganize [--since-days N]` | Dreaming → Agent reorganizer. Aggregates recent KB pattern/anti-pattern/lesson artifacts (default last 7 days) into a markdown proposal at `~/.arkaos/reorganize-proposals/<date>.md`. **Propose-only** — never modifies agent YAMLs. Sanitizes client identifiers from titles and body excerpts; drops `tags:` field entirely to prevent project-name leaks. **Auto-fires on session start when today's proposal is missing** (PR24 v2.46.0 stale-aware trigger, 30s timeout, background). Shells out to `~/.arkaos/bin/arka-py -m core.cognition.reorganizer_cli [--since-days N] [--dry-run]`. |
 | `/arka standup` | Daily standup (projects, priorities, blockers, updates) |

package/core/hooks/post_tool_use.py

@@ -632,6 +632,16 @@ def main(stdin_json: dict | None = None) -> int:
     # and confirm persistent authorization when a marker is present.
     _confirm_flow_authorization(session_id, transcript_path)
 
+    # MCP usage telemetry — must run BEFORE the error-signal early exit
+    # below (MCP calls normally succeed). record() is a no-op for
+    # non-MCP tools and never raises on I/O; the guard covers import
+    # failures on stripped installs.
+    try:
+        from core.runtime.mcp_telemetry import record as _record_mcp_usage
+        _record_mcp_usage(tool_name, session_id=session_id)
+    except Exception:  # noqa: BLE001 — telemetry must never break the hook
+        pass
+
     if tool_name in ("Task", "Agent"):
         subagent_type = get_str(stdin_json, "tool_input", "subagent_type")
         if subagent_type == "cqo":

package/core/runtime/mcp_telemetry.py

@@ -0,0 +1,184 @@
+"""MCP usage telemetry (audit E2E v4.3.6, P1).
+
+Writer + summarizer for ``~/.arkaos/telemetry/mcp-usage.jsonl``. The
+PostToolUse hook calls :func:`record` on every tool event; MCP tool
+names (``mcp__<server>__<tool>``) are parsed and appended as one JSONL
+line, everything else is ignored. Before this module the only usage
+signal was grepping session transcripts.
+
+Mirrors ``core.governance.enforcement_telemetry`` so periods,
+malformed-line tolerance, and zero-division safety behave the same way
+across telemetry surfaces. :func:`summarise` is read-only.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Iterable
+
+DEFAULT_PATH: Path = Path.home() / ".arkaos" / "telemetry" / "mcp-usage.jsonl"
+_VALID_PERIODS: frozenset[str] = frozenset({"today", "week", "month", "all"})
+_TOP_SERVERS: int = 10
+_TOP_TOOLS: int = 5
+_MCP_PREFIX = "mcp__"
+
+
+@dataclass(frozen=True)
+class McpUsageSummary:
+    """Aggregated MCP usage over a time slice."""
+    period: str
+    total_calls: int
+    unique_servers: int
+    top_servers: list[tuple[str, int]] = field(default_factory=list)
+    top_tools: list[tuple[str, int]] = field(default_factory=list)
+    corrupt_line_count: int = 0
+
+
+def parse_mcp_tool(tool_name: str) -> tuple[str, str] | None:
+    """Split ``mcp__<server>__<tool>`` into (server, tool).
+
+    Returns None for non-MCP tool names. Handles servers whose slug
+    contains single underscores (``claude_ai_Canva``, plugin servers
+    like ``plugin_claude-mem_mcp-search``) by splitting on the FIRST
+    double underscore after the prefix.
+    """
+    if not tool_name.startswith(_MCP_PREFIX):
+        return None
+    rest = tool_name[len(_MCP_PREFIX):]
+    server, sep, tool = rest.partition("__")
+    if not sep or not server or not tool:
+        return None
+    return server, tool
+
+
+def record(
+    tool_name: str,
+    *,
+    session_id: str = "",
+    path: Path | None = None,
+) -> bool:
+    """Append one usage line when tool_name is an MCP tool.
+
+    Never raises — the caller is a hook that must not block on
+    telemetry. Returns True when a line was written.
+    """
+    parsed = parse_mcp_tool(tool_name)
+    if parsed is None:
+        return False
+    server, tool = parsed
+    dest = path or DEFAULT_PATH
+    entry = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "server": server,
+        "tool": tool,
+        "session": session_id,
+    }
+    try:
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        with dest.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+    except OSError:
+        return False
+    return True
+
+
+def summarise(period: str, *, path: Path | None = None) -> McpUsageSummary:
+    """Return a McpUsageSummary for the requested period.
+
+    period: one of "today", "week", "month", "all".
+    path:   override telemetry source (used by tests; defaults to DEFAULT_PATH).
+    """
+    if period not in _VALID_PERIODS:
+        raise ValueError(f"invalid period: {period!r}")
+    src = path or DEFAULT_PATH
+    cutoff = _period_cutoff(period)
+    entries, corrupt = _read_jsonl(src, cutoff)
+    return _build_summary(period, entries, corrupt)
+
+
+def _period_cutoff(period: str, now: datetime | None = None) -> datetime | None:
+    ref = now or datetime.now(timezone.utc)
+    if period == "today":
+        return ref.replace(hour=0, minute=0, second=0, microsecond=0)
+    if period == "week":
+        return ref - timedelta(days=7)
+    if period == "month":
+        return ref - timedelta(days=30)
+    return None
+
+
+def _read_jsonl(src: Path, cutoff: datetime | None) -> tuple[list[dict[str, Any]], int]:
+    if not src.exists():
+        return [], 0
+    entries: list[dict[str, Any]] = []
+    corrupt = 0
+    # Line-stream to keep memory O(1) — this file grows on every MCP call.
+    try:
+        with src.open("r", encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                if not line.strip():
+                    continue
+                try:
+                    entry = json.loads(line)
+                except json.JSONDecodeError:
+                    corrupt += 1
+                    continue
+                if not isinstance(entry, dict):
+                    corrupt += 1
+                    continue
+                if cutoff is not None and not _within_cutoff(entry, cutoff):
+                    continue
+                entries.append(entry)
+    except OSError:
+        return entries, corrupt
+    return entries, corrupt
+
+
+def _within_cutoff(entry: dict[str, Any], cutoff: datetime) -> bool:
+    ts = _parse_ts(entry.get("ts"))
+    if ts is None:
+        return False
+    return ts >= cutoff
+
+
+def _parse_ts(raw: Any) -> datetime | None:
+    if not isinstance(raw, str) or not raw:
+        return None
+    try:
+        parsed = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed
+
+
+def _build_summary(
+    period: str,
+    entries: Iterable[dict[str, Any]],
+    corrupt: int,
+) -> McpUsageSummary:
+    total = 0
+    servers: Counter[str] = Counter()
+    tools: Counter[str] = Counter()
+    for entry in entries:
+        server = str(entry.get("server", ""))
+        tool = str(entry.get("tool", ""))
+        if not server:
+            continue
+        total += 1
+        servers[server] += 1
+        if tool:
+            tools[f"{server}/{tool}"] += 1
+    return McpUsageSummary(
+        period=period,
+        total_calls=total,
+        unique_servers=len(servers),
+        top_servers=servers.most_common(_TOP_SERVERS),
+        top_tools=tools.most_common(_TOP_TOOLS),
+        corrupt_line_count=corrupt,
+    )

package/core/runtime/mcp_telemetry_cli.py

@@ -0,0 +1,62 @@
+"""CLI entry for the MCP usage telemetry summarizer.
+
+Invoked as ``python -m core.runtime.mcp_telemetry_cli <period>`` where
+``<period>`` is one of: today, week, month, all (default: today).
+
+Output is plain markdown so it renders cleanly in both the terminal and
+the ``/arka status`` skill which concatenates it into its report.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from core.runtime.mcp_telemetry import McpUsageSummary, summarise
+
+
+def _sanitize_md(value: str) -> str:
+    """Strip markdown-breaking characters before rendering JSONL strings.
+
+    Telemetry is local-writer-only, but a malformed server/tool value
+    (newline, backtick) can still distort the markdown if /arka status
+    pipes the output to a UI.
+    """
+    return value.replace("\n", " ").replace("\r", " ").replace("`", "").strip()
+
+
+def _render(summary: McpUsageSummary) -> str:
+    lines = [
+        f"# MCP usage — {summary.period}",
+        "",
+        f"- Calls: **{summary.total_calls}**",
+        f"- Servers in use: **{summary.unique_servers}**",
+    ]
+    if summary.top_servers:
+        lines += ["", "## Top servers"]
+        for server, count in summary.top_servers:
+            lines.append(f"- `{_sanitize_md(server)}` — {count}")
+    if summary.top_tools:
+        lines += ["", "## Top tools"]
+        for tool, count in summary.top_tools:
+            lines.append(f"- `{_sanitize_md(tool)}` — {count}")
+    if summary.corrupt_line_count:
+        lines += ["", f"_Skipped {summary.corrupt_line_count} corrupt line(s)._"]
+    if summary.total_calls == 0:
+        lines += ["", "_No MCP calls recorded for this period._"]
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = argv if argv is not None else sys.argv[1:]
+    period = args[0] if args else "today"
+    try:
+        summary = summarise(period)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    print(_render(summary))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dashboard/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "nuxt-ui-template-dashboard",
+  "name": "arkaos-dashboard",
   "private": true,
   "type": "module",
   "scripts": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "4.5.0",
+  "version": "4.6.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.5.0"
+version = "4.6.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}