arkaos 4.3.5 → 4.4.0

package/core/knowledge/indexer.py

@@ -56,7 +56,7 @@ def index_directory(
 
         fhash = file_hash(filepath)
 
-        if skip_indexed and store.is_file_indexed(fhash):
+        if skip_indexed and store.is_file_indexed(str(filepath), fhash):
             skipped += 1
             continue
 

package/core/knowledge/vector_store.py

@@ -347,10 +347,17 @@ class VectorStore:
             for r in rows
         ]
 
-    def is_file_indexed(self, file_hash: str) -> bool:
-        """Check if a file has already been indexed."""
+    def is_file_indexed(self, source: str, file_hash: str) -> bool:
+        """Check if a file (identified by source path + content hash) is indexed.
+
+        The source path is part of the key so identical content in two
+        different locations (e.g. two npx cache directories) each gets
+        indexed — a hash-only check would skip every subsequent cache
+        and leave the new location unsearchable.
+        """
         row = self._db.execute(
-            "SELECT COUNT(*) as cnt FROM chunks WHERE file_hash = ?", (file_hash,)
+            "SELECT COUNT(*) as cnt FROM chunks WHERE source = ? AND file_hash = ?",
+            (source, file_hash),
         ).fetchone()
         return row["cnt"] > 0
 

package/core/runtime/gateway/__init__.py

@@ -0,0 +1,28 @@
+"""ArkaOS model-routing gateway.
+
+Turns the operator's ``~/.arkaos/models.yaml`` role routing into a running
+LiteLLM proxy so per-role model choices actually take effect at dispatch
+time. Claude Code points ``ANTHROPIC_BASE_URL`` at the proxy; the proxy
+fans each request out to the right upstream (Anthropic-direct or local
+Ollama) by the model name the alias slot carries.
+
+See ``docs/adr`` and the plan for why a gateway is required: Claude Code's
+``ANTHROPIC_BASE_URL`` is one endpoint per process, so honouring mixed
+providers per role in a single session needs a fan-out proxy.
+"""
+
+from core.runtime.gateway.litellm_config import (
+    GatewayPlan,
+    build_gateway_plan,
+    build_launch_env,
+    build_litellm_config,
+    role_alias,
+)
+
+__all__ = [
+    "GatewayPlan",
+    "build_gateway_plan",
+    "build_launch_env",
+    "build_litellm_config",
+    "role_alias",
+]

package/core/runtime/gateway/__main__.py

@@ -0,0 +1,30 @@
+"""CLI: render the LiteLLM gateway config from models.yaml.
+
+    arka-py -m core.runtime.gateway [--local]            # print config.yaml
+    arka-py -m core.runtime.gateway [--local] --env KEY  # print launch env
+
+``--local`` renders the keyless local-only variant (every route → local
+Ollama) for subscription users with no ANTHROPIC_API_KEY.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from core.runtime.gateway.litellm_config import build_launch_env, render_config_yaml
+
+
+def main(argv: list[str]) -> int:
+    local_only = "--local" in argv
+    argv = [a for a in argv if a != "--local"]
+    if len(argv) >= 2 and argv[0] == "--env":
+        env = build_launch_env(master_key=argv[1])
+        for key, value in env.items():
+            print(f"{key}={value}")
+        return 0
+    sys.stdout.write(render_config_yaml(local_only=local_only))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/core/runtime/gateway/litellm_config.py

@@ -0,0 +1,205 @@
+"""Render a LiteLLM proxy config + Claude Code launch env from models.yaml.
+
+Claude Code exposes at most three subagent alias slots (``opus``,
+``sonnet``, ``haiku``) plus the interactive main-loop model. The seven
+Model Fabric roles therefore collapse onto those slots by tier:
+
+    quality tier (design/review/architecture/quality_gate)  -> opus slot
+    execution                                                -> haiku slot
+    mechanical                                               -> sonnet slot
+    strategy / orchestrator                                  -> main model
+
+Each slot maps to a LiteLLM route (``arka-<slot>``) that fans out to the
+role's real upstream — Anthropic-direct or local Ollama. The launch env
+points ``ANTHROPIC_DEFAULT_<TIER>_MODEL`` at those routes, so a subagent
+dispatched with ``model: haiku`` reaches Ollama while ``model: opus``
+reaches Anthropic — in the same session. The Anthropic API key never
+enters the client env; it stays server-side in the proxy's environment.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from core.runtime.model_router import ModelsConfig, load_config, resolve
+
+# The three Claude Code subagent alias slots we can address, plus a
+# sentinel for the interactive main-loop model (not an alias).
+_SLOTS = ("opus", "sonnet", "haiku")
+_MAIN = "main"
+
+# Which alias slot each work-role dispatches through. The orchestrator
+# uses this to choose the Task `model` param per role; the launch env
+# points each slot's default model at the matching gateway route.
+ROLE_ALIAS: dict[str, str] = {
+    "design": "opus",
+    "review": "opus",
+    "architecture": "opus",
+    "quality_gate": "opus",
+    "strategy": _MAIN,
+    "execution": "haiku",
+    "mechanical": "sonnet",
+}
+
+# Representative role whose configured upstream defines each slot's route.
+# All quality roles share the opus slot, so one of them stands in.
+_SLOT_ROLE: dict[str, str] = {
+    "opus": "quality_gate",
+    "sonnet": "mechanical",
+    "haiku": "execution",
+}
+
+# runtime-tier tokens -> real Anthropic model ids the proxy calls upstream.
+# Real ids (claude-fable-5, claude-*) pass straight through.
+_RUNTIME_TO_ANTHROPIC: dict[str, str] = {
+    "opus": "claude-opus-4-8",
+    "best": "claude-opus-4-8",
+    "sonnet": "claude-sonnet-5",
+    "default": "claude-sonnet-5",
+    "haiku": "claude-haiku-4-5-20251001",
+    "fast": "claude-haiku-4-5-20251001",
+}
+
+_DEFAULT_OLLAMA_BASE = "http://localhost:11434"
+_DEFAULT_PORT = 4000
+_ANTHROPIC_KEY_REF = "os.environ/ANTHROPIC_API_KEY"
+
+
+def role_alias(role: str) -> str:
+    """Which Claude Code alias slot a role dispatches through.
+
+    Unknown roles fall back to the opus slot — never the cheap tier —
+    consistent with the model-router's quality-first posture.
+    """
+    return ROLE_ALIAS.get(role, "opus")
+
+
+class Upstream(BaseModel):
+    """A concrete backend a slot routes to."""
+
+    kind: str  # "anthropic" | "ollama"
+    model_id: str
+    api_base: str | None = None
+
+
+class GatewayPlan(BaseModel):
+    """Resolved routing: one upstream per subagent alias slot.
+
+    The strategy role rides the interactive main-loop model (set by
+    ``--model`` / the operator's ``/model``), which reaches Anthropic via
+    the wildcard passthrough route — it is not a gateway-controlled slot.
+    """
+
+    slots: dict[str, Upstream]  # keyed by "opus"/"sonnet"/"haiku"
+    source: str
+
+
+def _upstream_for(provider: str, model: str, ollama_base: str) -> Upstream:
+    if provider == "ollama":
+        return Upstream(kind="ollama", model_id=model, api_base=ollama_base)
+    # runtime + anthropic both terminate at Anthropic-direct.
+    return Upstream(kind="anthropic", model_id=_RUNTIME_TO_ANTHROPIC.get(model, model))
+
+
+def _ollama_base(config: ModelsConfig) -> str:
+    return (config.providers.get("ollama", {}) or {}).get("base_url") or _DEFAULT_OLLAMA_BASE
+
+
+def build_gateway_plan(user_path=None, local_only: bool = False) -> GatewayPlan:
+    """Resolve every alias slot to its upstream from the operator's config.
+
+    ``local_only`` (for subscription users with no ANTHROPIC_API_KEY):
+    every slot that would hit Anthropic is redirected to the local Ollama
+    model instead, so the whole session runs keyless on local models. Raises
+    if the config has no Ollama route to fall back to.
+    """
+    config, source = load_config(user_path)
+    ollama_base = _ollama_base(config)
+    slots: dict[str, Upstream] = {}
+    for slot, role in _SLOT_ROLE.items():
+        r = resolve(role, user_path)
+        slots[slot] = _upstream_for(r.provider, r.model, ollama_base)
+    if local_only:
+        fallback = _local_fallback(slots)
+        if fallback is None:
+            raise ValueError(
+                "local-only gateway requested but models.yaml has no Ollama "
+                "route to fall back to — point at least one role at ollama/<model>"
+            )
+        slots = {
+            slot: (up if up.kind == "ollama" else fallback)
+            for slot, up in slots.items()
+        }
+    return GatewayPlan(slots=slots, source=source)
+
+
+def _local_fallback(slots: dict[str, Upstream]) -> Upstream | None:
+    """The local Ollama upstream to redirect Anthropic routes to (prefer
+    execution/haiku), or None when no slot is local."""
+    if slots.get("haiku", Upstream(kind="anthropic", model_id="")).kind == "ollama":
+        return slots["haiku"]
+    for up in slots.values():
+        if up.kind == "ollama":
+            return up
+    return None
+
+
+def _litellm_params(up: Upstream) -> dict:
+    if up.kind == "ollama":
+        # ollama_chat/ enables tool-use translation; api_base points at the
+        # local daemon (which forwards :cloud models to Ollama Cloud).
+        return {"model": f"ollama_chat/{up.model_id}", "api_base": up.api_base}
+    return {"model": up.model_id, "api_key": _ANTHROPIC_KEY_REF}
+
+
+def build_litellm_config(user_path=None, local_only: bool = False) -> dict:
+    """The LiteLLM proxy config.yaml structure (regenerated per launch).
+
+    One ``arka-<slot>`` route per alias slot, plus a wildcard route for the
+    interactive main-loop model and any raw model id. In the default mixed
+    mode the wildcard forwards to Anthropic (key via ``os.environ``, never
+    inlined); in ``local_only`` mode it forwards to the local Ollama model
+    so the whole session is keyless. The client authenticates with the
+    gateway master key either way.
+    """
+    plan = build_gateway_plan(user_path, local_only=local_only)
+    model_list = [
+        {"model_name": f"arka-{slot}", "litellm_params": _litellm_params(plan.slots[slot])}
+        for slot in _SLOTS
+    ]
+    if local_only:
+        wildcard = _litellm_params(_local_fallback(plan.slots))
+    else:
+        # LiteLLM matches explicit names first; this catches the main-loop
+        # model and any raw claude-* id and forwards it to Anthropic.
+        wildcard = {"model": "anthropic/*", "api_key": _ANTHROPIC_KEY_REF}
+    model_list.append({"model_name": "*", "litellm_params": wildcard})
+    return {
+        "model_list": model_list,
+        "litellm_settings": {"drop_params": True},
+        "general_settings": {"master_key": "os.environ/ARKA_GATEWAY_KEY"},
+    }
+
+
+def build_launch_env(master_key: str, port: int = _DEFAULT_PORT, user_path=None) -> dict[str, str]:
+    """Env vars Claude Code launches with so subagent aliases hit the gateway.
+
+    ``ANTHROPIC_API_KEY`` is deliberately absent — it belongs to the proxy,
+    not the client. The client presents only the gateway master key.
+    """
+    return {
+        "ANTHROPIC_BASE_URL": f"http://127.0.0.1:{port}",
+        "ANTHROPIC_AUTH_TOKEN": master_key,
+        "ANTHROPIC_DEFAULT_OPUS_MODEL": "arka-opus",
+        "ANTHROPIC_DEFAULT_SONNET_MODEL": "arka-sonnet",
+        "ANTHROPIC_DEFAULT_HAIKU_MODEL": "arka-haiku",
+    }
+
+
+def render_config_yaml(user_path=None, local_only: bool = False) -> str:
+    """The LiteLLM config as a YAML string (what arka-claude writes to disk)."""
+    import yaml
+
+    return yaml.safe_dump(
+        build_litellm_config(user_path, local_only=local_only), sort_keys=False
+    )

package/core/runtime/model_routing_check.py

@@ -0,0 +1,71 @@
+"""Model-routing telemetry — answer "is the Model Fabric actually used?".
+
+The gateway makes per-role routing real; this module makes it *observable*.
+It reports the resolved route table, whether the LiteLLM proxy is live, and
+a best-effort count of which ``arka-<slot>`` routes actually served traffic
+(parsed from the proxy log). Everything degrades to a plain summary when the
+gateway is off, so ``/arka status`` always has a truthful line to show.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from core.runtime.gateway.litellm_config import build_gateway_plan
+
+_GATEWAY_LOG = Path.home() / ".arkaos" / "gateway" / "litellm.log"
+_DEFAULT_PORT = 4000
+_ROUTE_RE = re.compile(r"\barka-(opus|sonnet|haiku)\b")
+
+
+def resolved_routes(user_path=None) -> dict[str, str]:
+    """Alias slot -> human 'kind:model' the gateway would route it to."""
+    plan = build_gateway_plan(user_path)
+    return {
+        slot: f"{up.kind}:{up.model_id}" for slot, up in plan.slots.items()
+    }
+
+
+def gateway_healthy(port: int = _DEFAULT_PORT, timeout: float = 1.0) -> bool:
+    """True when the LiteLLM proxy answers its liveness probe."""
+    import urllib.error
+    import urllib.request
+
+    try:
+        with urllib.request.urlopen(
+            f"http://127.0.0.1:{port}/health/liveliness", timeout=timeout
+        ) as resp:
+            return resp.status == 200
+    except (urllib.error.URLError, OSError, ValueError):
+        return False
+
+
+def served_counts(log_path: Path | None = None) -> dict[str, int]:
+    """Best-effort count of arka-<slot> routes seen in the proxy log."""
+    path = log_path or _GATEWAY_LOG
+    counts: dict[str, int] = {}
+    try:
+        text = path.read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return counts
+    for match in _ROUTE_RE.finditer(text):
+        slot = match.group(1)
+        counts[slot] = counts.get(slot, 0) + 1
+    return counts
+
+
+def status_summary(port: int = _DEFAULT_PORT, user_path=None, log_path=None) -> str:
+    """One compact block for /arka status — reality, not intent."""
+    live = gateway_healthy(port)
+    routes = resolved_routes(user_path)
+    header = (
+        f"Gateway: {'LIVE' if live else 'off'} (:{port}) — per-role model routing "
+        f"{'active' if live else 'not active; honour-system context injection only'}"
+    )
+    lines = [f"  {slot} → {target}" for slot, target in sorted(routes.items())]
+    counts = served_counts(log_path)
+    if counts:
+        served = " ".join(f"{slot}={n}" for slot, n in sorted(counts.items()))
+        lines.append(f"  served: {served}")
+    return header + "\n" + "\n".join(lines)

package/core/runtime/model_routing_context.py

@@ -57,7 +57,7 @@ def routing_summary() -> str:
 
 
 def routing_directive() -> str:
-    """Full SessionStart block: the config plus how to honor it.
+    """Full SessionStart block: the config plus how to honour it.
 
     Returns '' when the config cannot be read, so the hook can skip the
     block entirely rather than inject an empty directive.
@@ -65,6 +65,26 @@ def routing_directive() -> str:
     summary = routing_summary()
     if not summary:
         return ""
+
+    # When the LiteLLM gateway is live, the alias a subagent is dispatched
+    # with is what physically selects the upstream (opus→Anthropic,
+    # haiku→Ollama for execution), so the directive names the concrete
+    # alias per role. Off, it stays advisory context injection.
+    gateway_line = ""
+    try:
+        from core.runtime.model_routing_check import gateway_healthy
+
+        if gateway_healthy():
+            gateway_line = (
+                "\nGateway LIVE: the Task model param physically routes the "
+                "upstream. Dispatch execution with model=haiku (→ Ollama), "
+                "mechanical with model=sonnet, and design/review/architecture/"
+                "quality_gate with model=opus (→ Anthropic). strategy is the "
+                "main loop model."
+            )
+    except Exception:
+        gateway_line = ""
+
     # No backticks: this string is embedded in session-start.sh which
     # passes it through $(echo -e "$MSG") — backticks would trigger shell
     # command substitution. Use plain quotes.
@@ -79,4 +99,5 @@ def routing_directive() -> str:
         "the agent YAML default. Quality roles never downgrade below the "
         "configured model (excellence-mandate). Genuinely mechanical "
         "dispatches (commit messages, formatting) use the mechanical role."
+        f"{gateway_line}"
     )

package/core/runtime/native_usage.py

@@ -33,9 +33,10 @@ from typing import Any
 from core.runtime.llm_cost_telemetry import record_cost
 from core.runtime.pricing import estimate_cost_usd
 from core.shared.safe_session_id import safe_session_id
+from core.shared.temp_paths import arkaos_temp_dir
 
 
-DEFAULT_CURSOR_DIR = Path("/tmp/arkaos-native-cost")
+DEFAULT_CURSOR_DIR = arkaos_temp_dir("arkaos-native-cost")
 
 _USAGE_KEYS = (
     "input_tokens",

package/core/shared/temp_paths.py

@@ -0,0 +1,40 @@
+"""Cross-platform base directory for ArkaOS inter-process coordination files.
+
+Several core modules and the bash hooks coordinate through small marker
+and cache files: workflow-required markers (``stop.sh`` ->
+``flow_enforcer``), the turn-scoped KB query cache
+(``user-prompt-submit.sh`` -> ``kb_cache``), hook metrics
+(``user-prompt-submit.sh`` -> ``dashboard-api``). The hooks write them
+under ``/tmp/arkaos-*``; the Python side MUST resolve to the *same*
+directory or the coordination silently breaks.
+
+Why this lives in ``core.shared``: every module that coordinates through
+these files (flow_enforcer, marker_cache, research_gate, kb_cache,
+forge.orchestrator, the consolidated hooks, native_usage, the synapse
+bridge, the dashboard API, …) used to hardcode the literal string
+``/tmp``. ``/tmp`` does not exist on Windows, so every one of those
+features failed there. A single helper keeps the resolution in one place.
+
+POSIX keeps the literal ``/tmp`` the bash hooks use (avoiding a
+``$TMPDIR`` divergence on macOS where ``tempfile.gettempdir()`` returns
+``/var/folders/...`` but the hooks still write ``/tmp``). On Windows
+there is no ``/tmp``: Git-for-Windows maps a hook's ``/tmp`` to
+``%TEMP%``, which is exactly what ``tempfile.gettempdir()`` returns, so
+both sides still meet.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+
+def arkaos_temp_dir(*parts: str) -> Path:
+    """Return ``<coordination base>/<parts...>`` (the path is not created).
+
+    POSIX -> ``/tmp/<parts>`` (matches the bash hooks verbatim).
+    Windows -> ``<%TEMP%>/<parts>`` (matches Git-for-Windows ``/tmp``).
+    """
+    base = Path(tempfile.gettempdir()) if os.name == "nt" else Path("/tmp")
+    return base.joinpath(*parts)

package/core/synapse/kb_cache.py

@@ -30,11 +30,12 @@ from pathlib import Path
 from typing import Any, Optional
 
 from core.shared import safe_session_id as _safe_session_id_module
+from core.shared.temp_paths import arkaos_temp_dir
 
 
 # Re-export for backward compatibility with any external importers.
 SAFE_SESSION_ID_RE = _safe_session_id_module.SAFE_SESSION_ID_RE
-KB_QUERY_MARKER_DIR = Path("/tmp/arkaos-kb-query")
+KB_QUERY_MARKER_DIR = arkaos_temp_dir("arkaos-kb-query")
 _MAX_QUERIES_PER_TURN = 32
 _MAX_QUERY_LEN = 512
 
@@ -159,7 +160,7 @@ class KBSessionCache:
             self._cache_dir = Path(cache_dir)
         else:
             project_hash = self._hash_project(project_path or "")
-            self._cache_dir = Path("/tmp") / f"arkaos-kb-{project_hash}"
+            self._cache_dir = arkaos_temp_dir(f"arkaos-kb-{project_hash}")
 
         self._cache_file = self._cache_dir / f"{session_id}.json"
         self._ensure_dir()

package/core/sync/agent_provisioner.py

@@ -55,7 +55,7 @@ def _extend_from_file(path: Path, agents: set[str]) -> None:
     if not path.exists():
         return
     try:
-        data = yaml.safe_load(path.read_text()) or {}
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
     except yaml.YAMLError:
         return
     for name in data.get("baseline", []) or []:
@@ -95,10 +95,10 @@ def _apply_allowlist(
             continue
 
         target = agents_dir / f"{name}.md"
-        if target.exists() and target.read_text() == rendered:
+        if target.exists() and target.read_text(encoding="utf-8") == rendered:
             unchanged.append(name)
             continue
-        target.write_text(rendered)
+        target.write_text(rendered, encoding="utf-8")
         added.append(name)
 
     return added, unchanged, errored
@@ -124,10 +124,10 @@ def _render_agent(core: Path, name: str) -> str | None:
     parts: list[str] = []
     if yaml_path is not None:
         parts.append("---")
-        parts.append(yaml_path.read_text().strip())
+        parts.append(yaml_path.read_text(encoding="utf-8").strip())
         parts.append("---")
     if md_path is not None:
-        parts.append(md_path.read_text().rstrip())
+        parts.append(md_path.read_text(encoding="utf-8").rstrip())
 
     return "\n".join(parts) + "\n"
 

package/core/sync/ai_mcp_decider.py

@@ -76,11 +76,11 @@ def _load_cache(path: Path) -> dict[str, str]:
     if not path.exists():
         return {}
     try:
-        return json.loads(path.read_text())
+        return json.loads(path.read_text(encoding="utf-8"))
     except (json.JSONDecodeError, OSError):
         return {}
 
 
 def _save_cache(path: Path, data: dict[str, str]) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(data, indent=2, sort_keys=True))
+    path.write_text(json.dumps(data, indent=2, sort_keys=True), encoding="utf-8")