loki-mode 6.81.1 → 6.83.0

package/mcp/server.py

@@ -1005,6 +1005,111 @@ async def loki_consolidate_memory(since_hours: int = 24) -> str:
         return json.dumps({"error": str(e)})
 
 
+@mcp.tool()
+async def loki_complete_task(
+    completion_statement: str,
+    evidence: str,
+    confidence: str = "medium",
+) -> str:
+    """
+    Declare that the current PRD / task is complete.
+
+    Replaces the legacy 'COMPLETION PROMISE FULFILLED: ...' prose string with a
+    structured tool call. The orchestrator (run.sh) detects this via a signal
+    file and stops the iteration loop gracefully.
+
+    Args:
+        completion_statement: A short statement of what is complete (for example,
+            "PRD requirements implemented, all tests passing, checklist 100%").
+        evidence: Concrete evidence supporting the claim -- tests that passed,
+            checklist items verified, files created/modified, metrics hit.
+        confidence: One of 'high', 'medium', 'low' (default 'medium').
+            'low' signals the orchestrator should still run the completion council.
+
+    Returns:
+        JSON: {"recorded": true, "path": ".loki/events.jsonl"} on success,
+        {"error": "..."} otherwise.
+    """
+    _emit_tool_event_async(
+        'loki_complete_task', 'start',
+        parameters={
+            'confidence': confidence,
+            'statement_len': len(completion_statement or ''),
+            'evidence_len': len(evidence or ''),
+        },
+    )
+
+    # Validate inputs
+    if not completion_statement or not completion_statement.strip():
+        _emit_tool_event_async(
+            'loki_complete_task', 'complete',
+            result_status='error', error='completion_statement required')
+        return json.dumps({"error": "completion_statement is required"})
+    if not evidence or not evidence.strip():
+        _emit_tool_event_async(
+            'loki_complete_task', 'complete',
+            result_status='error', error='evidence required')
+        return json.dumps({"error": "evidence is required"})
+
+    confidence_norm = (confidence or 'medium').strip().lower()
+    if confidence_norm not in ('high', 'medium', 'low'):
+        confidence_norm = 'medium'
+
+    timestamp = datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z')
+
+    payload = {
+        'type': 'task_completion_claim',
+        'statement': completion_statement.strip(),
+        'evidence': evidence.strip(),
+        'confidence': confidence_norm,
+        'timestamp': timestamp,
+    }
+
+    # Wrap event record with timestamp and type at the outer level so it matches
+    # the shape of other events in .loki/events.jsonl.
+    event_record = {
+        'timestamp': timestamp,
+        'type': 'task_completion_claim',
+        'data': payload,
+    }
+
+    try:
+        # Ensure .loki/ and .loki/signals/ exist under the project root
+        loki_dir = safe_path_join('.loki')
+        os.makedirs(loki_dir, exist_ok=True)
+        signals_dir = safe_path_join('.loki', 'signals')
+        os.makedirs(signals_dir, exist_ok=True)
+
+        events_path = safe_path_join('.loki', 'events.jsonl')
+        with safe_open(events_path, 'a') as f:
+            f.write(json.dumps(event_record) + '\n')
+
+        signal_path = safe_path_join('.loki', 'signals', 'TASK_COMPLETION_CLAIMED')
+        with safe_open(signal_path, 'w') as f:
+            f.write(json.dumps(payload, indent=2))
+
+        _emit_tool_event_async(
+            'loki_complete_task', 'complete', result_status='success')
+        return json.dumps({
+            "recorded": True,
+            "path": ".loki/events.jsonl",
+            "signal": ".loki/signals/TASK_COMPLETION_CLAIMED",
+            "confidence": confidence_norm,
+        })
+    except PathTraversalError as e:
+        logger.error(f"Path traversal attempt blocked in loki_complete_task: {e}")
+        _emit_tool_event_async(
+            'loki_complete_task', 'complete',
+            result_status='error', error='Access denied')
+        return json.dumps({"error": "Access denied"})
+    except Exception as e:
+        logger.error(f"loki_complete_task failed: {e}")
+        _emit_tool_event_async(
+            'loki_complete_task', 'complete',
+            result_status='error', error=str(e))
+        return json.dumps({"error": str(e)})
+
+
 # ============================================================
 # RESOURCES - Data that can be read
 # ============================================================

package/memory/managed_memory/__init__.py

@@ -0,0 +1,113 @@
+"""
+Loki Managed Agents Memory package (v6.83.0 Phase 1).
+
+Opt-in integration with Claude Managed Agents memory stores. All behavior in
+this package is gated on the two environment variables:
+
+    LOKI_MANAGED_AGENTS   parent switch (default: false)
+    LOKI_MANAGED_MEMORY   child switch  (default: false)
+
+Both must be "true" for any API call to be issued. If the child is "true" while
+the parent is "false", the loki runner fails fast at startup (see
+autonomy/run.sh). If the flags are off, every exported function is a cheap
+no-op -- importing this package will NOT trigger any network or SDK import
+side-effects.
+
+This package is intentionally the ONLY place in the codebase that imports the
+`anthropic` SDK. A CI test (tests/managed_memory/test_sdk_isolation.sh)
+enforces that invariant.
+
+Exports:
+    is_enabled()                - bool, True iff both flags are on
+    ManagedDisabled             - raised when callers try to force an op while off
+    shadow_write_verdict(path)  - shadow-write a council verdict JSON to the store
+    shadow_write_pattern(obj)   - shadow-write a semantic pattern dict
+    retrieve_related_verdicts(q, top_k=3, store_id=None)
+                                - return list of related prior verdicts
+    hydrate_patterns(mtime_floor)
+                                - pull recent patterns and merge locally
+    probe_beta_header()         - return the active beta header string
+    emit_managed_event(type, payload)
+                                - low-level event writer
+
+None of these functions raise on SDK or network errors. They return empty /
+None and log one WARN line. Real SDK errors surface through
+`.loki/managed/events.ndjson`.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from ._beta import BETA_HEADER
+from .events import emit_managed_event
+
+
+class ManagedDisabled(Exception):
+    """Raised when a managed-memory operation is attempted while flags are off."""
+
+
+def is_enabled() -> bool:
+    """True iff LOKI_MANAGED_AGENTS=true AND LOKI_MANAGED_MEMORY=true."""
+    parent = os.environ.get("LOKI_MANAGED_AGENTS", "").strip().lower() == "true"
+    child = os.environ.get("LOKI_MANAGED_MEMORY", "").strip().lower() == "true"
+    return parent and child
+
+
+def probe_beta_header() -> str:
+    """Return the pinned managed-agents beta header."""
+    return BETA_HEADER
+
+
+# Lazy re-exports. Importing the top-level package MUST NOT import the
+# anthropic SDK, so we defer the real imports until the functions are called.
+
+
+def shadow_write_verdict(verdict_json_path: str) -> None:
+    """Shadow-write a council verdict file to the managed store (opt-in)."""
+    if not is_enabled():
+        return None
+    from . import shadow_write as _sw  # local import: gated on flags
+    return _sw.shadow_write_verdict(verdict_json_path)
+
+
+def shadow_write_pattern(pattern: dict) -> None:
+    """Shadow-write a semantic pattern dict to the managed store (opt-in)."""
+    if not is_enabled():
+        return None
+    from . import shadow_write as _sw
+    return _sw.shadow_write_pattern(pattern)
+
+
+def retrieve_related_verdicts(
+    query: str,
+    top_k: int = 3,
+    store_id: Optional[str] = None,
+):
+    """Return related verdicts from the managed store; [] when disabled or on error."""
+    if not is_enabled():
+        return []
+    from . import retrieve as _r
+    return _r.retrieve_related_verdicts(query, top_k=top_k, store_id=store_id)
+
+
+def hydrate_patterns(local_mtime_floor: float):
+    """Pull semantic patterns updated after floor; no-op when disabled."""
+    if not is_enabled():
+        return None
+    from . import retrieve as _r
+    return _r.hydrate_patterns(local_mtime_floor)
+
+
+__all__ = [
+    "BETA_HEADER",
+    "ManagedDisabled",
+    "emit_managed_event",
+    "hydrate_patterns",
+    "is_enabled",
+    "probe_beta_header",
+    "retrieve_related_verdicts",
+    "shadow_write_pattern",
+    "shadow_write_verdict",
+]

package/memory/managed_memory/_beta.py

@@ -0,0 +1,11 @@
+"""
+Loki Managed Agents Memory - Beta Header (v6.83.0 Phase 1).
+
+Single source of truth for the anthropic-beta header required by Claude
+Managed Agents. All callers in memory/managed_memory/ import BETA_HEADER
+from here. Update this constant to roll to a new beta.
+"""
+
+# Pin to the public Managed Agents beta channel current as of v6.83.0.
+# This value is sent as the `anthropic-beta` HTTP header on every request.
+BETA_HEADER = "managed-agents-2026-04-01"

package/memory/managed_memory/client.py

@@ -0,0 +1,210 @@
+"""
+Loki Managed Agents Memory - Client wrapper (v6.83.0 Phase 1).
+
+Thin wrapper around the `anthropic` SDK. This is the ONLY file in the codebase
+that imports `anthropic`. A CI invariant test enforces that.
+
+The wrapper:
+    - Sets anthropic-beta: managed-agents-2026-04-01 on every request.
+    - Reads ANTHROPIC_API_KEY from env. Absence raises ManagedDisabled.
+    - Wraps every SDK call in a 10s hard timeout. Timeouts are treated as
+      recoverable: the caller decides whether to fall back.
+    - Never retries inside the client (no retry-storm). Callers implement
+      bounded retry (e.g. 409 precondition merge-and-retry-once).
+
+NOTE on API surface: the exact Managed Agents memory endpoints are under a
+beta channel. This wrapper implements a minimal, forward-compatible subset --
+stores_list, stores_get_or_create, memory_create, memory_read, memories_list.
+If the SDK version installed does not expose `beta.memory`, calls raise an
+AttributeError which the callers translate into a ManagedDisabled/fallback.
+
+Not tested end-to-end against a live ANTHROPIC_API_KEY in CI. Automated tests
+use memory/managed_memory/fakes.py.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import threading
+from typing import Any, Dict, List, Optional
+
+from . import ManagedDisabled
+from ._beta import BETA_HEADER
+
+_DEFAULT_TIMEOUT = 10.0  # seconds
+
+
+def _check_flags_or_raise() -> None:
+    parent = os.environ.get("LOKI_MANAGED_AGENTS", "").strip().lower() == "true"
+    child = os.environ.get("LOKI_MANAGED_MEMORY", "").strip().lower() == "true"
+    if not (parent and child):
+        raise ManagedDisabled(
+            "managed memory flags are off "
+            "(LOKI_MANAGED_AGENTS and LOKI_MANAGED_MEMORY must both be 'true')"
+        )
+
+
+def _require_api_key() -> str:
+    key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
+    if not key:
+        raise ManagedDisabled("ANTHROPIC_API_KEY is not set")
+    return key
+
+
+def compute_sha256(content: str) -> str:
+    """Stable content hash used as an optimistic precondition on writes."""
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+class ManagedClient:
+    """
+    Thin SDK wrapper. Instantiating this class imports anthropic and validates
+    credentials; callers should construct it lazily inside flag-gated paths.
+    """
+
+    def __init__(self, timeout: float = _DEFAULT_TIMEOUT) -> None:
+        _check_flags_or_raise()
+        api_key = _require_api_key()
+        # Import lazily so the top-level package stays SDK-free.
+        try:
+            import anthropic  # noqa: F401  (imported for side-effects + symbol)
+        except ImportError as e:  # pragma: no cover - import surface
+            raise ManagedDisabled(f"anthropic SDK not installed: {e}")
+
+        self._anthropic = anthropic
+        self._client = anthropic.Anthropic(
+            api_key=api_key,
+            timeout=timeout,
+            default_headers={"anthropic-beta": BETA_HEADER},
+        )
+        self._timeout = timeout
+
+    # ---------- helpers -------------------------------------------------
+
+    def _beta(self):
+        """Return the beta namespace, if the SDK exposes it.
+
+        Newer SDK versions expose `client.beta.memory.*`. If the attribute
+        path is missing we raise ManagedDisabled so callers can fall back.
+        """
+        beta = getattr(self._client, "beta", None)
+        if beta is None:
+            raise ManagedDisabled("anthropic SDK missing `beta` namespace")
+        return beta
+
+    # ---------- stores --------------------------------------------------
+
+    def stores_list(self) -> List[Dict[str, Any]]:
+        """List managed memory stores on this account (may be empty)."""
+        beta = self._beta()
+        stores = getattr(beta, "memory_stores", None) or getattr(beta, "stores", None)
+        if stores is None or not hasattr(stores, "list"):
+            raise ManagedDisabled("memory_stores API not available in SDK")
+        result = stores.list()
+        # SDK returns a pydantic model; normalize to list of dicts.
+        data = getattr(result, "data", result)
+        return [self._to_dict(x) for x in (data or [])]
+
+    def stores_get_or_create(
+        self, name: str, description: str = "", scope: str = "project"
+    ) -> Dict[str, Any]:
+        """Return existing store with `name` or create it."""
+        existing = [s for s in self.stores_list() if s.get("name") == name]
+        if existing:
+            return existing[0]
+        beta = self._beta()
+        stores = getattr(beta, "memory_stores", None) or getattr(beta, "stores", None)
+        if stores is None or not hasattr(stores, "create"):
+            raise ManagedDisabled("memory_stores.create not available in SDK")
+        created = stores.create(name=name, description=description, scope=scope)
+        return self._to_dict(created)
+
+    # ---------- memories ------------------------------------------------
+
+    def memory_create(
+        self,
+        store_id: str,
+        path: str,
+        content: str,
+        sha256_precondition: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Create a memory entry at `path` in `store_id`.
+
+        When sha256_precondition is supplied, this is an optimistic
+        concurrency hint: if the store already holds a different hash the
+        SDK is expected to surface a 409-shaped error. Callers handle the
+        409 by re-reading, merging, and retrying once.
+        """
+        beta = self._beta()
+        memories = getattr(beta, "memories", None)
+        if memories is None or not hasattr(memories, "create"):
+            raise ManagedDisabled("memories.create not available in SDK")
+        kwargs: Dict[str, Any] = {
+            "store_id": store_id,
+            "path": path,
+            "content": content,
+        }
+        if sha256_precondition:
+            kwargs["if_match_sha256"] = sha256_precondition
+        created = memories.create(**kwargs)
+        return self._to_dict(created)
+
+    def memory_read(self, store_id: str, memory_id: str) -> Dict[str, Any]:
+        beta = self._beta()
+        memories = getattr(beta, "memories", None)
+        if memories is None or not hasattr(memories, "retrieve"):
+            raise ManagedDisabled("memories.retrieve not available in SDK")
+        got = memories.retrieve(store_id=store_id, memory_id=memory_id)
+        return self._to_dict(got)
+
+    def memories_list(
+        self, store_id: str, path_prefix: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        beta = self._beta()
+        memories = getattr(beta, "memories", None)
+        if memories is None or not hasattr(memories, "list"):
+            raise ManagedDisabled("memories.list not available in SDK")
+        kwargs: Dict[str, Any] = {"store_id": store_id}
+        if path_prefix:
+            kwargs["path_prefix"] = path_prefix
+        result = memories.list(**kwargs)
+        data = getattr(result, "data", result)
+        return [self._to_dict(x) for x in (data or [])]
+
+    # ---------- internal ------------------------------------------------
+
+    @staticmethod
+    def _to_dict(obj: Any) -> Dict[str, Any]:
+        """Best-effort pydantic-or-dict to dict conversion."""
+        if isinstance(obj, dict):
+            return obj
+        to_dict = getattr(obj, "model_dump", None) or getattr(obj, "dict", None)
+        if callable(to_dict):
+            try:
+                return to_dict()
+            except TypeError:
+                return to_dict()
+        return {"raw": str(obj)}
+
+
+# Optional helper for callers that want a thread-safe singleton.
+_singleton: Optional[ManagedClient] = None
+_singleton_lock = threading.Lock()
+
+
+def get_client() -> ManagedClient:
+    """Return a lazily-constructed singleton. Raises ManagedDisabled if off."""
+    global _singleton
+    with _singleton_lock:
+        if _singleton is None:
+            _singleton = ManagedClient()
+        return _singleton
+
+
+def reset_client() -> None:
+    """Test hook: drop the cached singleton so tests can swap implementations."""
+    global _singleton
+    with _singleton_lock:
+        _singleton = None

package/memory/managed_memory/events.py

@@ -0,0 +1,79 @@
+"""
+Loki Managed Agents Memory - Event emission (v6.83.0 Phase 1).
+
+Appends structured JSONL events to .loki/managed/events.ndjson. Single-writer
+convention: only code in memory/managed_memory/ writes to this file. Rotates
+when the file exceeds 10MB.
+
+Events are used to record fallbacks, shadow-write successes/failures, and
+retrieve hits. The file is safe to tail for observability during development.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+# 10 MB rotation threshold. Keeping rotation simple: rename to .<YYYYMMDD>.
+_ROTATE_BYTES = 10 * 1024 * 1024
+
+
+def _events_dir(target_dir: Optional[str] = None) -> Path:
+    base = target_dir or os.environ.get("LOKI_TARGET_DIR") or os.getcwd()
+    return Path(base) / ".loki" / "managed"
+
+
+def _maybe_rotate(path: Path) -> None:
+    """Rotate the events file if it has exceeded the size threshold."""
+    try:
+        if path.exists() and path.stat().st_size >= _ROTATE_BYTES:
+            stamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+            rotated = path.with_suffix(path.suffix + f".{stamp}")
+            # Best-effort rename; if another writer got there first, move on.
+            try:
+                path.rename(rotated)
+            except OSError:
+                pass
+    except OSError:
+        # If stat fails, skip rotation; next write will retry.
+        pass
+
+
+def emit_managed_event(
+    event_type: str,
+    payload: Dict[str, Any],
+    target_dir: Optional[str] = None,
+) -> None:
+    """
+    Append a managed-memory event to .loki/managed/events.ndjson.
+
+    Never raises: on any I/O error the function silently returns. Callers
+    rely on this to keep the main RARV-C loop unblocked.
+
+    Args:
+        event_type: short tag, e.g. "managed_agents_fallback",
+            "managed_memory_retrieve", "managed_memory_shadow_write".
+        payload: JSON-serializable context for the event.
+        target_dir: optional project root override. Defaults to
+            LOKI_TARGET_DIR env or cwd.
+    """
+    try:
+        dir_path = _events_dir(target_dir)
+        dir_path.mkdir(parents=True, exist_ok=True)
+        path = dir_path / "events.ndjson"
+        _maybe_rotate(path)
+
+        record = {
+            "ts": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+            "type": event_type,
+            "payload": payload,
+        }
+        # Line-buffered append; JSONL.
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(record, default=str) + "\n")
+    except Exception:
+        # Never raise from the event emitter.
+        return

package/memory/managed_memory/fakes.py

@@ -0,0 +1,120 @@
+"""
+Loki Managed Agents Memory - FakeManagedClient for CI tests (v6.83.0 Phase 1).
+
+Implements the same surface as ManagedClient but keeps state in memory and
+returns deterministic responses keyed on input path. Used by
+tests/managed_memory/test_*_mock.py so CI does not call the real API.
+
+This file is importable without the `anthropic` SDK installed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any, Dict, List, Optional
+
+
+class _Conflict(Exception):
+    """Simulated 409 raised by memory_create on sha256 mismatch."""
+
+    status_code = 409
+
+
+class FakeManagedClient:
+    """In-memory fake matching ManagedClient's public interface."""
+
+    def __init__(self) -> None:
+        self.stores: Dict[str, Dict[str, Any]] = {}
+        # memories keyed by (store_id, path) -> dict(content, sha, version)
+        self.memories: Dict[tuple, Dict[str, Any]] = {}
+        self.calls: List[Dict[str, Any]] = []
+
+    # ---------- stores --------------------------------------------------
+
+    def stores_list(self) -> List[Dict[str, Any]]:
+        self.calls.append({"op": "stores_list"})
+        return list(self.stores.values())
+
+    def stores_get_or_create(
+        self, name: str, description: str = "", scope: str = "project"
+    ) -> Dict[str, Any]:
+        self.calls.append({"op": "stores_get_or_create", "name": name})
+        for s in self.stores.values():
+            if s.get("name") == name:
+                return s
+        store_id = f"store_{len(self.stores) + 1:04d}"
+        store = {
+            "id": store_id,
+            "name": name,
+            "description": description,
+            "scope": scope,
+        }
+        self.stores[store_id] = store
+        return store
+
+    # ---------- memories ------------------------------------------------
+
+    def memory_create(
+        self,
+        store_id: str,
+        path: str,
+        content: str,
+        sha256_precondition: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        self.calls.append(
+            {
+                "op": "memory_create",
+                "store_id": store_id,
+                "path": path,
+                "sha256_precondition": sha256_precondition,
+            }
+        )
+        key = (store_id, path)
+        sha = hashlib.sha256(content.encode("utf-8")).hexdigest()
+        existing = self.memories.get(key)
+        if existing is not None and sha256_precondition is not None:
+            if existing["sha"] != sha256_precondition:
+                # Simulated 409: caller must re-read + merge + retry.
+                raise _Conflict(
+                    f"sha256 mismatch for {path}: "
+                    f"have={existing['sha']}, want={sha256_precondition}"
+                )
+        version = (existing.get("version", 0) + 1) if existing else 1
+        entry = {
+            "id": f"mem_{abs(hash(key)) % 10**8:08d}",
+            "store_id": store_id,
+            "path": path,
+            "content": content,
+            "sha": sha,
+            "version": version,
+        }
+        self.memories[key] = entry
+        return entry
+
+    def memory_read(self, store_id: str, memory_id: str) -> Dict[str, Any]:
+        self.calls.append({"op": "memory_read", "memory_id": memory_id})
+        for entry in self.memories.values():
+            if entry.get("id") == memory_id:
+                return entry
+        raise KeyError(memory_id)
+
+    def memories_list(
+        self, store_id: str, path_prefix: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        self.calls.append(
+            {"op": "memories_list", "store_id": store_id, "path_prefix": path_prefix}
+        )
+        out = []
+        for (sid, path), entry in self.memories.items():
+            if sid != store_id:
+                continue
+            if path_prefix and not path.startswith(path_prefix):
+                continue
+            out.append(entry)
+        return out
+
+
+# Helper exported for tests that need to simulate the 409 without
+# importing the private _Conflict class directly.
+def make_conflict_error() -> Exception:
+    return _Conflict("forced conflict for tests")