arkaos 2.21.0 → 2.22.1

package/VERSION

@@ -1 +1 @@
-2.21.0
+2.22.1

package/arka/SKILL.md

@@ -109,7 +109,8 @@ violation (squad-routing, arka-supremacy, spec-driven, mandatory-qa).
 
 | Command | Description |
 |---------|-------------|
-| `/arka status` | System status (version, departments, agents, active projects) |
+| `/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")`. |
+| `/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 `python -m core.runtime.llm_cost_telemetry_cli <period>`. |
 | `/arka standup` | Daily standup (projects, priorities, blockers, updates) |
 | `/arka monitor` | System health monitoring |
 | `/arka onboard <path>` | Onboard an existing project into ArkaOS |

package/arka/skills/costs/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: arka-costs
+description: >
+  LLM cost visibility — aggregates `~/.arkaos/telemetry/llm-cost.jsonl` by
+  day/week/month/all, breaks down by provider/model/session, surfaces top
+  expensive sessions and cache hit rate. Visibility-only per ADR-011;
+  never imposes hard caps.
+allowed-tools: [Bash, Read]
+---
+
+# /arka costs — LLM cost visibility
+
+Aggregates runtime-agnostic LLM call telemetry written by
+`core/runtime/llm_cost_telemetry.record_cost`. Per ADR-011, token
+budgets are **informational, not restrictive** — this command only
+surfaces usage and emits soft advisories. It never blocks a call.
+
+## Usage
+
+| Command | What it shows |
+| --- | --- |
+| `/arka costs` | Today (UTC midnight → now) |
+| `/arka costs today` | Same as above |
+| `/arka costs week` | Rolling last 7 days |
+| `/arka costs month` | Rolling last 30 days |
+| `/arka costs all` | Entire history in the JSONL |
+| `/arka costs sessions` | Top 10 most expensive sessions (all time) |
+
+## Output
+
+- Total cost (USD, `n/a` when all entries are unpriced models)
+- Total tokens in / out, plus cached tokens
+- Cache hit rate (`cached / tokens_in`)
+- Breakdown by provider
+- Breakdown by model (`<unknown>` bucket for calls with no model)
+- Top 10 sessions sorted by cost
+- Advisories — a soft line per session that crossed the
+  `advisory_threshold_usd` (default $5 per session)
+
+## Implementation
+
+This skill shells out to the Python CLI:
+
+```bash
+python -m core.runtime.llm_cost_telemetry_cli <period>
+```
+
+Source:
+- `core/runtime/llm_cost_telemetry.py` — `summarise`, `list_expensive_sessions`
+- `core/runtime/llm_cost_telemetry_cli.py` — markdown renderer
+
+## Data source
+
+`~/.arkaos/telemetry/llm-cost.jsonl` (override with `ARKA_LLM_COST_PATH`).
+One JSONL line per LLM call, written by every provider adapter.
+Malformed lines are skipped and counted, never raised.
+
+## Non-negotiables
+
+1. Read-only. This skill never edits state.
+2. No hard budget caps — advisories are strings, not errors.
+3. No external dependencies; stdlib only.

package/core/cognition/auto_documentor.py

@@ -5,14 +5,15 @@ synthesises learnings about external sources consulted, decisions made,
 and deliverables produced, then invokes the Obsidian cataloger + relator
 (Task #4 modules) to file structured, wikilinked notes into the vault.
 
-Model routing is dynamic: a complexity heuristic over the learning
-content chooses haiku / sonnet / opus. Nothing is hardcoded per task
-type. The actual LLM call is abstracted behind `_call_llm` and falls
-back to a deterministic template when no SDK is wired — this keeps the
-module testable and unblocks the SDK integration as a follow-up.
+The synthesis step is runtime- and model-agnostic: it delegates to the
+active `LLMProvider` (see `core.runtime.llm_provider`). This module
+NEVER picks a model — the provider / runtime / env does. When no
+provider is available or the call fails, it falls through to a
+deterministic template synthesiser that preserves every extracted fact.
 
 ADR/Plan references:
 - ~/.arkaos/plans/2026-04-20-intelligence-v2.md (Task #7 — Épico B)
+- ~/.arkaos/plans/2026-04-20-llm-agnostic.md (Task #12/#13 — LLMProvider)
 - core/obsidian/cataloger.py, core/obsidian/relator.py (Task #4)
 """
 
@@ -20,26 +21,29 @@ from __future__ import annotations
 
 import json
 import re
+from contextlib import contextmanager
 from dataclasses import dataclass, field
-from datetime import date
+from datetime import datetime, timezone
 from pathlib import Path
-from typing import Iterable, Optional
+from typing import Iterable
 
 from core.obsidian import cataloger as _cataloger
 from core.obsidian import relator as _relator
 from core.obsidian.writer import ObsidianWriter
+from core.shared import safe_session_id as _safe_session_id_module
 
+try:
+    import fcntl  # POSIX only
+    _HAS_FLOCK = True
+except ImportError:
+    _HAS_FLOCK = False
 
-SAFE_SESSION_ID_RE = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
 
-_ARCHITECTURAL_KEYWORDS = (
-    "architecture", "adr", "decision", "trade-off", "tradeoff",
-    "design pattern", "refactor", "migration", "schema", "bounded context",
-)
-_ANALYSIS_KEYWORDS = (
-    "analysis", "investigation", "compare", "benchmark", "evaluate",
-    "profile", "review", "audit",
-)
+# Re-export for backward compatibility with any external importers.
+SAFE_SESSION_ID_RE = _safe_session_id_module.SAFE_SESSION_ID_RE
+
+AUTO_DOC_TELEMETRY_PATH = Path.home() / ".arkaos" / "telemetry" / "auto_doc.jsonl"
+
 _URL_RE = re.compile(r"https?://[^\s\)\]\"']+")
 _FILE_PATH_RE = re.compile(r"(?:^|[\s`'])(/[A-Za-z0-9_./\-]+\.[A-Za-z0-9]+)")
 _ROUTING_MARKER_RE = re.compile(
@@ -58,8 +62,17 @@ _EXTERNAL_RESEARCH_TOOLS = frozenset({
     "mcp__firecrawl__firecrawl_extract",
 })
 
-_HAIKU_MAX_CHARS = 600
-_OPUS_MIN_CHARS = 4000
+_AUTO_DOC_SUFFIX = "Auto-documented by ArkaOS"
+_LLM_MAX_TOKENS = 1500
+
+_SYSTEM_PROMPT = (
+    "You are ArkaOS's auto-documentor. Produce a concise knowledge note "
+    "(150-300 words) summarising the session. Structure: short intro, "
+    "then markdown sections for Key Facts, Decisions, and Sources. "
+    "Preserve every URL and file path verbatim. Use Obsidian wikilinks "
+    "([[Topic]]) for reusable concepts. Do not include preamble, sign-off, "
+    "or meta commentary about the model or prompt. Output only markdown."
+)
 
 
 @dataclass
@@ -264,65 +277,129 @@ def _dedupe_keep_order(items: Iterable[str]) -> list[str]:
     return out
 
 
-# ─── Model routing ─────────────────────────────────────────────────────
-
-
-def choose_model(learning: Learning) -> str:
-    """Return 'haiku' | 'sonnet' | 'opus' based on content complexity."""
-    low = learning.content.lower()
-    length = len(learning.content)
-    if any(kw in low for kw in _ARCHITECTURAL_KEYWORDS):
-        return "opus"
-    if length >= _OPUS_MIN_CHARS and len(learning.decisions) >= 3:
-        return "opus"
-    if length <= _HAIKU_MAX_CHARS and len(learning.decisions) <= 1:
-        return "haiku"
-    if any(kw in low for kw in _ANALYSIS_KEYWORDS):
-        return "sonnet"
-    if length >= _HAIKU_MAX_CHARS:
-        return "sonnet"
-    return "haiku"
-
-
 # ─── Synthesis ─────────────────────────────────────────────────────────
 
 
-def synthesize(learning: Learning, model_hint: str) -> str:
+def synthesize(learning: Learning) -> str:
     """Produce a markdown body for the learning.
 
-    Calls `_call_llm` when a real LLM integration is wired; otherwise
-    falls back to a deterministic template that preserves all extracted
-    information. The template path is what ships in Task #7.
+    Delegates to the active `LLMProvider` via `_call_llm`. If the
+    provider is unavailable, returns empty text, or raises, falls
+    through to a deterministic template that preserves every extracted
+    fact. No model name ever crosses this boundary.
     """
-    llm_out = _call_llm(learning, model_hint)
+    llm_out = _call_llm(learning)
     if llm_out:
         return llm_out
-    return _template_synthesize(learning, model_hint)
+    return _template_synthesize(learning)
+
+
+def _call_llm(learning: Learning) -> str:
+    from core.runtime import get_llm_provider
+    from core.runtime.llm_provider import LLMUnavailable
+
+    try:
+        provider = get_llm_provider()
+        if not provider.is_available():
+            return ""
+        prompt = _build_synthesis_prompt(learning)
+        response = provider.complete(
+            prompt, max_tokens=_LLM_MAX_TOKENS, system=_SYSTEM_PROMPT
+        )
+        return response.text.strip()
+    except LLMUnavailable:
+        return ""
+    except Exception:  # noqa: BLE001 — LLM path must never crash the doc job
+        return ""
 
 
-def _call_llm(learning: Learning, model_hint: str) -> str:
-    return ""
+def _build_synthesis_prompt(learning: Learning) -> str:
+    lines = [f"Topic: {learning.topic}", ""]
+    if learning.content.strip():
+        lines.append("Session blob:")
+        lines.append(learning.content.strip())
+        lines.append("")
+    if learning.sources:
+        lines.append("Sources consulted:")
+        for src in learning.sources[:20]:
+            lines.append(f"- {src}")
+        lines.append("")
+    if learning.decisions:
+        lines.append("Decisions recorded:")
+        for dec in learning.decisions[:10]:
+            lines.append(f"- {dec}")
+        lines.append("")
+    if learning.metadata:
+        meta_pairs = sorted(learning.metadata.items())
+        lines.append("Metadata:")
+        for key, value in meta_pairs:
+            lines.append(f"- {key}: {value}")
+        lines.append("")
+    lines.append(
+        "Write the note now. Obey the system prompt. Output only markdown."
+    )
+    return "\n".join(lines)
+
+
+def _extract_key_facts(learning: Learning, limit: int = 5) -> list[str]:
+    """Pull 3-5 bullet candidates from the learning content.
+
+    Used by the template fallback so both the LLM and template paths
+    produce a ``## Key Facts`` section in the same order as
+    ``_SYSTEM_PROMPT`` requires.
+    """
+    text = (learning.content or "").strip()
+    if not text:
+        return []
+    paragraphs = [p.strip() for p in re.split(r"\n\s*\n", text) if p.strip()]
+    bullets: list[str] = []
+    for para in paragraphs:
+        for raw in para.splitlines():
+            line = raw.strip().lstrip("-*• ").strip()
+            # Skip markdown section headings; they aren't facts.
+            if not line or line.startswith("#"):
+                continue
+            if line.startswith(">") or line.startswith("`"):
+                continue
+            if len(line) < 8:
+                continue
+            bullets.append(line[:240])
+            if len(bullets) >= limit:
+                return bullets
+        if len(bullets) >= limit:
+            break
+    return bullets
 
 
-def _template_synthesize(learning: Learning, model_hint: str) -> str:
-    parts = [f"# {learning.topic}", ""]
-    parts.append(f"> Auto-documented via ArkaOS ({model_hint}).")
+def _template_synthesize(learning: Learning) -> str:
+    # Section order mirrors _SYSTEM_PROMPT: Key Facts → Decisions →
+    # Sources. Keeping both synthesis paths aligned means downstream
+    # consumers (MOC generation, relator) never branch on provider.
+    parts: list[str] = [f"# {learning.topic}", ""]
+    parts.append(f"> {_AUTO_DOC_SUFFIX}.")
     parts.append("")
     if learning.content.strip():
         parts.append(learning.content.strip())
         parts.append("")
-    if learning.sources:
-        parts.append("## Sources")
+    key_facts = _extract_key_facts(learning)
+    if key_facts:
+        parts.append("## Key Facts")
         parts.append("")
-        for src in learning.sources[:20]:
-            parts.append(f"- {src}")
+        for fact in key_facts:
+            parts.append(f"- {fact}")
         parts.append("")
     if learning.decisions:
-        parts.append("## Key decisions")
+        parts.append("## Decisions")
         parts.append("")
         for dec in learning.decisions[:10]:
             parts.append(f"- {dec}")
         parts.append("")
+    if learning.sources:
+        parts.append("## Sources")
+        parts.append("")
+        for src in learning.sources[:20]:
+            parts.append(f"- {src}")
+        parts.append("")
     return "\n".join(parts).rstrip() + "\n"
 
 
@@ -358,23 +435,86 @@ def _document_one(
     writer: ObsidianWriter,
     vault_path: Path,
     session_id: str,
-) -> Optional[Path]:
-    model_hint = choose_model(learning)
-    body = synthesize(learning, model_hint)
+) -> Path | None:
+    body = synthesize(learning)
     meta = dict(learning.metadata)
     meta.setdefault("title", learning.topic[:80])
     meta.setdefault("session", session_id)
     meta.setdefault("auto_documented", True)
-    meta.setdefault("model_hint", model_hint)
     try:
         plan = _cataloger.plan(body, meta)
-    except ValueError:
+    except ValueError as exc:
+        _log_auto_doc_event(
+            session_id=session_id,
+            event="classification-failed",
+            topic=learning.topic,
+            reason=str(exc),
+        )
+        return None
+    if plan is None:
+        _log_auto_doc_event(
+            session_id=session_id,
+            event="succeeded-empty",
+            topic=learning.topic,
+            reason="cataloger returned no plan",
+        )
         return None
     note_path = _cataloger.execute(plan, body, writer)
     _relate_note(note_path, body, vault_path, plan)
+    _log_auto_doc_event(
+        session_id=session_id,
+        event="succeeded-wrote-note",
+        topic=learning.topic,
+        reason=str(note_path),
+    )
     return note_path
 
 
+@contextmanager
+def _locked_append(path: Path):
+    """Append to ``path`` under an exclusive advisory lock (POSIX flock).
+
+    Mirrors the pattern in ``core/workflow/flow_enforcer._locked_append``
+    — see that module for the platform-fallback rationale.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fh = path.open("a", encoding="utf-8")
+    try:
+        if _HAS_FLOCK:
+            fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
+        yield fh
+    finally:
+        if _HAS_FLOCK:
+            try:
+                fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
+            except OSError:
+                pass
+        fh.close()
+
+
+def _log_auto_doc_event(
+    *,
+    session_id: str,
+    event: str,
+    topic: str,
+    reason: str,
+) -> None:
+    """Append a structured auto-doc telemetry entry, degrade silently."""
+    entry = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "session_id": session_id,
+        "event": event,
+        "topic": topic[:120],
+        "reason": reason[:240],
+    }
+    try:
+        with _locked_append(AUTO_DOC_TELEMETRY_PATH) as fh:
+            fh.write(json.dumps(entry) + "\n")
+    except OSError:
+        # Telemetry failures must never break the doc job.
+        return
+
+
 def _relate_note(note_path: Path, body: str, vault_path: Path, plan) -> None:
     try:
         related = _relator.find_related(
@@ -405,6 +545,4 @@ def _append_related_block(note_path: Path, related) -> None:
 
 
 def _safe_session_id(session_id: str) -> bool:
-    if not isinstance(session_id, str) or not session_id:
-        return False
-    return bool(SAFE_SESSION_ID_RE.match(session_id))
+    return _safe_session_id_module.safe_session_id(session_id) is not None

package/core/jobs/auto_doc_worker.py

@@ -28,7 +28,6 @@ from __future__ import annotations
 import argparse
 import json
 import os
-import re
 import sys
 import time
 import uuid
@@ -36,9 +35,12 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
+from core.shared import safe_session_id as _safe_session_id_module
+
 
 MAX_ATTEMPTS = 3
-SAFE_SESSION_ID_RE = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
+# Re-export for backward compatibility with any external importers.
+SAFE_SESSION_ID_RE = _safe_session_id_module.SAFE_SESSION_ID_RE
 _QUEUE_SUBDIRS = ("pending", "processing", "completed", "failed")
 
 
@@ -77,7 +79,7 @@ def enqueue_job(
     """Write a pending job file. Returns the job id."""
     root = queue_root or _queue_root()
     _ensure_queue(root)
-    safe = session_id if SAFE_SESSION_ID_RE.match(session_id or "") else "unknown"
+    safe = _safe_session_id_module.safe_session_id(session_id or "") or "unknown"
     job_id = f"{int(time.time())}-{uuid.uuid4().hex[:12]}"
     payload = {
         "job_id": job_id,

package/core/runtime/__init__.py

@@ -2,5 +2,26 @@
 
 from core.runtime.base import RuntimeAdapter, RuntimeConfig
 from core.runtime.registry import get_adapter, detect_runtime
+from core.runtime.llm_provider import (
+    AnthropicDirectProvider,
+    LLMProvider,
+    LLMResponse,
+    LLMUnavailable,
+    StubProvider,
+    SubagentProvider,
+    get_llm_provider,
+)
 
-__all__ = ["RuntimeAdapter", "RuntimeConfig", "get_adapter", "detect_runtime"]
+__all__ = [
+    "AnthropicDirectProvider",
+    "LLMProvider",
+    "LLMResponse",
+    "LLMUnavailable",
+    "RuntimeAdapter",
+    "RuntimeConfig",
+    "StubProvider",
+    "SubagentProvider",
+    "detect_runtime",
+    "get_adapter",
+    "get_llm_provider",
+]

package/core/runtime/base.py

@@ -11,7 +11,10 @@ knowing which runtime is active. Each adapter handles the translation.
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from core.runtime.llm_provider import LLMResponse
 
 
 @dataclass
@@ -141,3 +144,29 @@ class RuntimeAdapter(ABC):
             "mcp": config.supports_mcp,
         }
         return feature_map.get(feature, False)
+
+    def headless_supported(self) -> bool:
+        """Whether this adapter can perform a headless CLI completion.
+
+        Default: False. Override in adapters that implement
+        `headless_complete`. `SubagentProvider` consults this before
+        attempting a call so the factory can fall back cleanly.
+        """
+        return False
+
+    def headless_complete(
+        self,
+        prompt: str,
+        *,
+        max_tokens: int = 2000,
+        system: str = "",
+    ) -> "LLMResponse":
+        """Run a one-shot headless completion via this runtime's CLI.
+
+        Default implementation raises NotImplementedError — adapters
+        that do not have a headless CLI mode (e.g. Cursor) inherit this
+        behaviour. Never hardcodes a model.
+        """
+        raise NotImplementedError(
+            f"{self.get_config().name} does not support headless LLM completion"
+        )

package/core/runtime/claude_code.py

@@ -4,11 +4,18 @@ Claude Code is the primary and most capable runtime for ArkaOS.
 It supports hooks, subagents (Agent tool), MCP servers, and worktrees.
 """
 
+import json
+import shutil
+import subprocess
 from pathlib import Path
 from os.path import expanduser
+from typing import TYPE_CHECKING
 
 from core.runtime.base import RuntimeAdapter, RuntimeConfig, AgentContext, AgentResult
 
+if TYPE_CHECKING:
+    from core.runtime.llm_provider import LLMResponse
+
 
 class ClaudeCodeAdapter(RuntimeAdapter):
     """Adapter for Anthropic's Claude Code CLI."""
@@ -102,3 +109,70 @@ class ClaudeCodeAdapter(RuntimeAdapter):
     def supports_feature(self, feature: str) -> bool:
         """Claude Code supports all features."""
         return True
+
+    def headless_supported(self) -> bool:
+        return shutil.which("claude") is not None
+
+    def headless_complete(
+        self,
+        prompt: str,
+        *,
+        max_tokens: int = 2000,
+        system: str = "",
+    ) -> "LLMResponse":
+        from core.runtime.llm_provider import LLMUnavailable
+
+        binary = shutil.which("claude")
+        if binary is None:
+            raise NotImplementedError(
+                "claude CLI not found on PATH — install Claude Code to enable "
+                "headless completion via this adapter."
+            )
+        cmd = [binary, "-p", prompt, "--output-format", "json"]
+        if system:
+            cmd.extend(["--append-system-prompt", system])
+        proc = _run_claude_cli(cmd)
+        if proc.returncode != 0:
+            raise LLMUnavailable(
+                f"claude CLI exited {proc.returncode}: {proc.stderr.strip()[:200]}"
+            )
+        return _parse_claude_cli_output(proc.stdout)
+
+
+def _run_claude_cli(cmd: list[str]) -> subprocess.CompletedProcess:
+    from core.runtime.llm_provider import LLMUnavailable
+
+    try:
+        return subprocess.run(
+            cmd, capture_output=True, text=True, timeout=60, check=False
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise LLMUnavailable("claude CLI timed out after 60s") from exc
+    except OSError as exc:
+        raise LLMUnavailable(f"claude CLI subprocess failed: {exc}") from exc
+
+
+def _parse_claude_cli_output(stdout: str) -> "LLMResponse":
+    from core.runtime.llm_provider import LLMResponse
+
+    payload = json.loads(stdout) if stdout.strip() else {}
+    text = str(payload.get("result") or payload.get("response") or "")
+    usage = payload.get("usage") or {}
+    tokens_in = int(usage.get("input_tokens") or 0)
+    tokens_out = int(usage.get("output_tokens") or 0)
+    cache_read = int(usage.get("cache_read_input_tokens") or 0)
+    cache_write = int(usage.get("cache_creation_input_tokens") or 0)
+    total_input = tokens_in + cache_read + cache_write
+    model = str(payload.get("model") or "")
+    return LLMResponse(
+        text=text,
+        tokens_in=total_input,
+        tokens_out=tokens_out,
+        cached_tokens=cache_read,
+        model=model,
+    )
+
+
+# Backward compatibility alias — tests and external importers that used
+# the old helper name continue to work without modification.
+_parse_claude_json = _parse_claude_cli_output