ctxora 6.2.0

package/src/harness_context/installer/models.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Mutation:
+    operation: str
+    path: str
+    before: Any
+    after: Any
+
+
+@dataclass(frozen=True)
+class MutationPlan:
+    profile: str
+    config_path: str
+    mutations: tuple[Mutation, ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)

package/src/harness_context/installer/service.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from harness_context.adapters.clients import ClientProfile, get_profile
+from harness_context.branding import CLI_NAME
+from harness_context.installer.models import Mutation, MutationPlan
+from harness_context.paths import workspace_data_dirs, workspace_installer_dir
+
+
+class ClientInstaller:
+    def __init__(self, workspace: str | Path):
+        self.workspace = Path(workspace).expanduser().resolve()
+        self.ownership_path = workspace_installer_dir(self.workspace) / "ownership.json"
+
+    def plan(self, profile_name: str, config_path: str | Path | None = None, uninstall: bool = False) -> MutationPlan:
+        profile = get_profile(profile_name)
+        path = self._config_path(profile, config_path)
+        current = self._read(profile, path)
+        before = self._owned_value(profile, current)
+        manifest = self._load_manifest().get(profile.name, {})
+        after = manifest.get("previous") if uninstall else self._server_config()
+        if uninstall and manifest and before != manifest.get("installed"):
+            return MutationPlan(profile.name, str(path), (Mutation("conflict", self._mutation_path(profile), before, after),))
+        operation = "remove" if uninstall and after is None else ("restore" if uninstall else ("replace" if before is not None else "add"))
+        mutations = () if before == after else (Mutation(operation, self._mutation_path(profile), before, after),)
+        return MutationPlan(profile.name, str(path), mutations)
+
+    def install(self, profile_name: str, config_path: str | Path | None = None, dry_run: bool = False) -> MutationPlan:
+        profile = get_profile(profile_name)
+        path = self._config_path(profile, config_path)
+        plan = self.plan(profile_name, path)
+        if dry_run or not plan.mutations:
+            return plan
+        current = self._read(profile, path)
+        updated = self._set_owned(profile, current, self._server_config())
+        self._backup(path)
+        self._write(profile, path, updated)
+        manifest = self._load_manifest()
+        manifest[profile.name] = {
+            "config_path": str(path),
+            "server_key": profile.server_key,
+            "previous": self._owned_value(profile, current),
+            "installed": self._owned_value(profile, updated),
+        }
+        self._write_json(self.ownership_path, manifest)
+        return plan
+
+    def uninstall(self, profile_name: str, config_path: str | Path | None = None, dry_run: bool = False, delete_data: bool = False) -> MutationPlan:
+        profile = get_profile(profile_name)
+        manifest = self._load_manifest()
+        owned = manifest.get(profile.name, {})
+        path = self._config_path(profile, config_path or owned.get("config_path"))
+        plan = self.plan(profile_name, path, uninstall=True)
+        conflict = any(mutation.operation == "conflict" for mutation in plan.mutations)
+        if not dry_run and plan.mutations and not conflict:
+            current = self._read(profile, path)
+            self._backup(path)
+            self._write(profile, path, self._set_owned(profile, current, owned.get("previous")))
+        if not dry_run and not conflict:
+            manifest.pop(profile.name, None)
+            if manifest:
+                self._write_json(self.ownership_path, manifest)
+            else:
+                self.ownership_path.unlink(missing_ok=True)
+            if delete_data:
+                for data_dir in workspace_data_dirs(self.workspace):
+                    shutil.rmtree(data_dir, ignore_errors=True)
+        return plan
+
+    def _server_config(self) -> dict[str, Any]:
+        command = os.environ.get("CTXORA_MCP_COMMAND", CLI_NAME)
+        prefix = json.loads(os.environ.get("CTXORA_MCP_ARGS_PREFIX", "[]"))
+        if not isinstance(prefix, list) or not all(isinstance(item, str) for item in prefix):
+            raise ValueError("CTXORA_MCP_ARGS_PREFIX must be a JSON array of strings")
+        return {
+            "command": command,
+            "args": [*prefix, "run", "--workspace", str(self.workspace), "--transport", "stdio"],
+            "env": {"CTXORA_ALLOWED_ROOTS": str(self.workspace), "PYTHONUTF8": "1"},
+        }
+
+    @staticmethod
+    def _mutation_path(profile: ClientProfile) -> str:
+        return f"mcp_servers.{profile.server_key}" if profile.config_format == "toml" else f"mcpServers.{profile.server_key}"
+
+    @staticmethod
+    def _config_path(profile: ClientProfile, config_path: str | Path | None) -> Path:
+        return Path(config_path or profile.default_config).expanduser().resolve()
+
+    @staticmethod
+    def _read(profile: ClientProfile, path: Path) -> Any:
+        if not path.exists():
+            return "" if profile.config_format == "toml" else {}
+        text = path.read_text("utf-8")
+        return text if profile.config_format == "toml" else json.loads(text or "{}")
+
+    @staticmethod
+    def _owned_value(profile: ClientProfile, current: Any) -> Any:
+        if profile.config_format == "json":
+            return current.get("mcpServers", {}).get(profile.server_key)
+        match = re.search(ClientInstaller._toml_pattern(profile), current)
+        return match.group(0).rstrip() if match else None
+
+    def _set_owned(self, profile: ClientProfile, current: Any, value: Any) -> Any:
+        if profile.config_format == "json":
+            updated = json.loads(json.dumps(current))
+            servers = updated.setdefault("mcpServers", {})
+            if value is None:
+                servers.pop(profile.server_key, None)
+                if not servers:
+                    updated.pop("mcpServers", None)
+            else:
+                servers[profile.server_key] = value
+            return updated
+        pattern = self._toml_pattern(profile)
+        cleaned = re.sub(pattern, "", current).rstrip()
+        if value is None:
+            return cleaned + ("\n" if cleaned else "")
+        if isinstance(value, str):
+            return (cleaned + "\n\n" if cleaned else "") + value.rstrip() + "\n"
+        block = [f"[mcp_servers.{profile.server_key}]", f'command = {json.dumps(value["command"])}', f'args = {json.dumps(value["args"])}', ""]
+        block.append(f"[mcp_servers.{profile.server_key}.env]")
+        block.extend(f"{key} = {json.dumps(item)}" for key, item in sorted(value["env"].items()))
+        return (cleaned + "\n\n" if cleaned else "") + "\n".join(block) + "\n"
+
+    @staticmethod
+    def _toml_pattern(profile: ClientProfile) -> str:
+        key = re.escape(profile.server_key)
+        return rf"(?ms)^\[mcp_servers\.{key}\]\n.*?(?=^\[(?!mcp_servers\.{key}(?:\.|\]))|\Z)"
+
+    def _load_manifest(self) -> dict[str, Any]:
+        if not self.ownership_path.exists():
+            return {}
+        return json.loads(self.ownership_path.read_text("utf-8"))
+
+    @staticmethod
+    def _backup(path: Path) -> None:
+        if not path.exists():
+            return
+        backup = path.with_suffix(path.suffix + ".ctxora.bak")
+        backup.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(dir=backup.parent, delete=False) as handle:
+            handle.write(path.read_bytes())
+            temporary = Path(handle.name)
+        os.replace(temporary, backup)
+
+    @staticmethod
+    def _write(profile: ClientProfile, path: Path, value: Any) -> None:
+        text = value if profile.config_format == "toml" else json.dumps(value, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+        ClientInstaller._write_text(path, text)
+
+    @staticmethod
+    def _write_json(path: Path, value: Any) -> None:
+        ClientInstaller._write_text(path, json.dumps(value, ensure_ascii=False, indent=2, sort_keys=True) + "\n")
+
+    @staticmethod
+    def _write_text(path: Path, text: str) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile("w", encoding="utf-8", dir=path.parent, delete=False) as handle:
+            handle.write(text)
+            temporary = Path(handle.name)
+        os.replace(temporary, path)

package/src/harness_context/mcp/__init__.py

@@ -0,0 +1,3 @@
+from harness_context.mcp.server import create_mcp_server
+
+__all__ = ["create_mcp_server"]

package/src/harness_context/mcp/capabilities.py

@@ -0,0 +1,11 @@
+from harness_context.branding import MCP_SERVER_NAME
+
+SERVER_NAME = MCP_SERVER_NAME
+
+TOOL_NAMES = frozenset({
+    "register_workspace", "refresh_workspace", "plan_context", "retrieve_context",
+    "prepare_context", "context_stats", "invalidate_context", "memory_save",
+    "memory_search", "memory_delete", "memory_list", "handoff_conversation",
+    "restore_conversation_handoff", "list_conversation_handoffs",
+    "delete_conversation_handoff", "purge_expired_handoffs", "ecc_status", "ecc_search",
+})

package/src/harness_context/mcp/errors.py

@@ -0,0 +1,8 @@
+from harness_context.api.v2.errors import ErrorResponse, map_exception
+
+
+def error_payload(error: Exception) -> dict:
+    return map_exception(error).to_dict()
+
+
+__all__ = ["ErrorResponse", "error_payload", "map_exception"]

package/src/harness_context/mcp/lifecycle.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import threading
+import time
+
+from mcp.server.fastmcp import FastMCP
+
+from harness_context.mcp.capabilities import SERVER_NAME
+from harness_context.mcp.middleware import RequestMiddleware
+from harness_context.mcp.tools import register_tools
+from harness_context.observability import LocalMetrics, StructuredEventSink
+
+
+class ServerLifecycle:
+    def __init__(self):
+        self._condition = threading.Condition()
+        self._ready = False
+        self._draining = False
+        self._active_requests = 0
+
+    def mark_ready(self) -> None:
+        with self._condition:
+            self._ready = True
+
+    def begin_request(self) -> bool:
+        with self._condition:
+            if not self._ready or self._draining:
+                return False
+            self._active_requests += 1
+            return True
+
+    def end_request(self) -> None:
+        with self._condition:
+            self._active_requests = max(0, self._active_requests - 1)
+            self._condition.notify_all()
+
+    def drain(self, timeout: float = 10.0) -> bool:
+        deadline = time.monotonic() + timeout
+        with self._condition:
+            self._draining = True
+            while self._active_requests and time.monotonic() < deadline:
+                self._condition.wait(max(0, deadline - time.monotonic()))
+            return self._active_requests == 0
+
+    def status(self) -> dict[str, object]:
+        with self._condition:
+            return {"ready": self._ready and not self._draining,
+                    "draining": self._draining, "active_requests": self._active_requests}
+
+
+def create_mcp_server(container, default_workspace_id: str, lifecycle=None,
+                      events=None, metrics=None) -> FastMCP:
+    server = FastMCP(SERVER_NAME)
+    register_tools(server, container, default_workspace_id)
+    lifecycle = lifecycle or ServerLifecycle()
+    events = events or StructuredEventSink(container.snapshots.state_dir / "events.jsonl")
+    metrics = metrics or LocalMetrics()
+    middleware = RequestMiddleware(lifecycle, events, metrics)
+    target = getattr(server, "middleware", None)
+    if target is None:
+        target = getattr(getattr(server, "_mcp_server", None), "middleware", None)
+    if target is not None:
+        target.append(middleware)
+    else:
+        for tool in server._tool_manager._tools.values():
+            tool.fn = middleware.wrap(tool.name, tool.fn)
+    lifecycle.mark_ready()
+    server.ctxora_lifecycle = lifecycle
+    server.ctxora_metrics = metrics
+    server.harness_lifecycle = lifecycle
+    server.harness_metrics = metrics
+    return server

package/src/harness_context/mcp/middleware.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import time
+import uuid
+from functools import wraps
+
+
+class RequestMiddleware:
+    def __init__(self, lifecycle, events, metrics):
+        self.lifecycle = lifecycle
+        self.events = events
+        self.metrics = metrics
+
+    async def __call__(self, context, call_next):
+        request_id = uuid.uuid4().hex
+        method = str(getattr(context, "method", "unknown"))
+        started = time.monotonic()
+        if not self.lifecycle.begin_request():
+            self._complete(request_id, method, "rejected", started)
+            raise RuntimeError("server is draining")
+        try:
+            result = await call_next(context)
+        except Exception:
+            self._complete(request_id, method, "error", started)
+            raise
+        else:
+            self._complete(request_id, method, "ok", started)
+            return result
+        finally:
+            self.lifecycle.end_request()
+
+    def wrap(self, method: str, function):
+        @wraps(function)
+        def tracked(*args, **kwargs):
+            request_id = uuid.uuid4().hex
+            started = time.monotonic()
+            if not self.lifecycle.begin_request():
+                self._complete(request_id, method, "rejected", started)
+                raise RuntimeError("server is draining")
+            try:
+                result = function(*args, **kwargs)
+            except Exception:
+                self._complete(request_id, method, "error", started)
+                raise
+            else:
+                self._complete(request_id, method, "ok", started)
+                return result
+            finally:
+                self.lifecycle.end_request()
+
+        return tracked
+
+    def _complete(self, request_id: str, method: str, outcome: str, started: float) -> None:
+        duration = int((time.monotonic() - started) * 1000)
+        self.metrics.record_request(outcome, duration)
+        self.events.emit("request.completed", request_id=request_id, method=method,
+                         outcome=outcome, duration_ms=duration)

package/src/harness_context/mcp/server.py

@@ -0,0 +1,3 @@
+from harness_context.mcp.lifecycle import create_mcp_server
+
+__all__ = ["create_mcp_server"]

package/src/harness_context/mcp/tool_handlers/__init__.py

@@ -0,0 +1,7 @@
+from harness_context.mcp.tool_handlers.context import register_context_tools
+from harness_context.mcp.tool_handlers.ecc import register_ecc_tools
+from harness_context.mcp.tool_handlers.handoffs import register_handoff_tools
+from harness_context.mcp.tool_handlers.memory import register_memory_tools
+from harness_context.mcp.tool_handlers.workspace import register_workspace_tools
+
+__all__ = ["register_context_tools", "register_ecc_tools", "register_handoff_tools", "register_memory_tools", "register_workspace_tools"]

package/src/harness_context/mcp/tool_handlers/context.py

@@ -0,0 +1,16 @@
+def register_context_tools(mcp, container, default_workspace_id: str) -> None:
+    @mcp.tool()
+    def plan_context(workspace_id: str, query: str, available_input_tokens: int, strategy_override: str = "") -> dict:
+        return container.retrieval.plan(workspace_id, query, available_input_tokens, strategy_override)
+
+    @mcp.tool()
+    def retrieve_context(workspace_id: str, query: str, top_k: int = 12, graph_expand: bool = True, token_budget: int = 4_000) -> dict:
+        return container.retrieval.retrieve(workspace_id, query, top_k, graph_expand, token_budget)
+
+    @mcp.tool()
+    def prepare_context(workspace_id: str, query: str, available_input_tokens: int, preferred_strategy: str = "auto", include_memory: bool = True, include_handoff: bool = False, handoff_id: str = "", include_ecc: bool = False, freshness: str = "current", deadline_ms: int = 5_000) -> dict:
+        return container.context.prepare_values(workspace_id=workspace_id, query=query, available_input_tokens=available_input_tokens, preferred_strategy=preferred_strategy, include_memory=include_memory, include_handoff=include_handoff, handoff_id=handoff_id, include_ecc=include_ecc, freshness=freshness, deadline_ms=deadline_ms)
+
+    @mcp.tool()
+    def context_stats(workspace_id: str = default_workspace_id) -> dict:
+        return container.retrieval.stats(workspace_id)

package/src/harness_context/mcp/tool_handlers/ecc.py

@@ -0,0 +1,8 @@
+def register_ecc_tools(mcp, container) -> None:
+    @mcp.tool()
+    def ecc_status() -> dict:
+        return container.ecc_queries.status()
+
+    @mcp.tool()
+    def ecc_search(query: str, limit: int = 4) -> dict:
+        return container.ecc_queries.search(query, limit)

package/src/harness_context/mcp/tool_handlers/handoffs.py

@@ -0,0 +1,20 @@
+def register_handoff_tools(mcp, container) -> None:
+    @mcp.tool()
+    def handoff_conversation(workspace_id: str, messages_json: str, threshold_tokens: int = 30_000, label: str = "", retention_seconds: int = 604_800, consent: bool = False) -> dict:
+        return container.handoff.prepare(workspace_id, messages_json, threshold_tokens, label, retention_seconds, consent)
+
+    @mcp.tool()
+    def restore_conversation_handoff(workspace_id: str, handoff_id: str) -> dict:
+        return container.handoff.restore(workspace_id, handoff_id)
+
+    @mcp.tool()
+    def list_conversation_handoffs(workspace_id: str, limit: int = 30) -> list[dict]:
+        return container.handoff.list(workspace_id, limit)
+
+    @mcp.tool()
+    def delete_conversation_handoff(workspace_id: str, handoff_id: str) -> dict:
+        return container.handoff.delete(workspace_id, handoff_id)
+
+    @mcp.tool()
+    def purge_expired_handoffs() -> dict:
+        return container.handoff.purge()

package/src/harness_context/mcp/tool_handlers/memory.py

@@ -0,0 +1,16 @@
+def register_memory_tools(mcp, container) -> None:
+    @mcp.tool()
+    def memory_save(workspace_id: str, key: str, value: str, mtype: str = "semantic", tags: str = "", scope: str = "workspace", source: str = "user", confidence: float = 1.0, expires_at: float | None = None) -> dict:
+        return container.memories.save(workspace_id, key, value, mtype, tags, scope, source, confidence, expires_at)
+
+    @mcp.tool()
+    def memory_search(workspace_id: str, query: str, mtype: str = "", top_k: int = 5, min_sim: float = 0.12) -> list[dict]:
+        return container.memories.search(workspace_id, query, mtype, top_k, min_sim)
+
+    @mcp.tool()
+    def memory_delete(workspace_id: str, key: str, mtype: str = "semantic") -> dict:
+        return container.memories.delete(workspace_id, key, mtype)
+
+    @mcp.tool()
+    def memory_list(workspace_id: str, mtype: str = "", limit: int = 30) -> list[str]:
+        return container.memories.list(workspace_id, mtype, limit)

package/src/harness_context/mcp/tool_handlers/workspace.py

@@ -0,0 +1,12 @@
+def register_workspace_tools(mcp, container, default_workspace_id: str) -> None:
+    @mcp.tool()
+    def register_workspace(workspace_id: str, roots: list[str], initial_refresh: bool = False) -> dict:
+        return container.workspace.register(workspace_id, roots, initial_refresh)
+
+    @mcp.tool()
+    def refresh_workspace(workspace_id: str = default_workspace_id, paths: list[str] | None = None) -> dict:
+        return container.refresh.execute(workspace_id, paths)
+
+    @mcp.tool()
+    def invalidate_context(workspace_id: str, target: str) -> dict:
+        return container.refresh.invalidate(workspace_id, target)

package/src/harness_context/mcp/tools.py

@@ -0,0 +1,15 @@
+from harness_context.mcp.tool_handlers import (
+    register_context_tools,
+    register_ecc_tools,
+    register_handoff_tools,
+    register_memory_tools,
+    register_workspace_tools,
+)
+
+
+def register_tools(mcp, container, default_workspace_id: str) -> None:
+    register_workspace_tools(mcp, container, default_workspace_id)
+    register_context_tools(mcp, container, default_workspace_id)
+    register_memory_tools(mcp, container)
+    register_handoff_tools(mcp, container)
+    register_ecc_tools(mcp, container)

package/src/harness_context/observability/__init__.py

@@ -0,0 +1,6 @@
+from harness_context.observability.events import StructuredEventSink
+from harness_context.observability.metrics import LocalMetrics
+
+__all__ = ["LocalMetrics", "StructuredEventSink"]
+
+__all__ = ["LocalMetrics", "StructuredEventSink"]

package/src/harness_context/observability/events.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import json
+import threading
+import time
+from pathlib import Path
+from typing import ClassVar
+
+
+class StructuredEventSink:
+    _FIELDS: ClassVar = {"request_id", "method", "outcome", "duration_ms"}
+
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+        self._lock = threading.Lock()
+
+    def emit(self, event: str, **fields: object) -> dict[str, object]:
+        unknown = set(fields) - self._FIELDS
+        if unknown:
+            raise ValueError(f"unsupported event fields: {sorted(unknown)}")
+        payload = {"event": event, "timestamp": round(time.time(), 3), **fields}
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self._lock, self.path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(payload, sort_keys=True, separators=(",", ":")) + "\n")
+        return payload

package/src/harness_context/observability/metrics.py

@@ -0,0 +1,20 @@
+import threading
+from collections import Counter
+
+
+class LocalMetrics:
+    def __init__(self):
+        self._values: Counter[str] = Counter()
+        self._lock = threading.Lock()
+
+    def record_request(self, outcome: str, duration_ms: int) -> None:
+        if outcome not in {"ok", "error", "rejected"}:
+            raise ValueError("unsupported request outcome")
+        with self._lock:
+            self._values["requests_total"] += 1
+            self._values[f"requests_{outcome}"] += 1
+            self._values["request_duration_ms_total"] += max(0, int(duration_ms))
+
+    def snapshot(self) -> dict[str, int]:
+        with self._lock:
+            return dict(sorted(self._values.items()))

package/src/harness_context/paths.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from harness_context.branding import LEGACY_WORKSPACE_DIR_NAME, WORKSPACE_DIR_NAME
+
+
+def workspace_data_dir(workspace: str | Path) -> Path:
+    return Path(workspace).resolve() / WORKSPACE_DIR_NAME
+
+
+def legacy_workspace_data_dir(workspace: str | Path) -> Path:
+    return Path(workspace).resolve() / LEGACY_WORKSPACE_DIR_NAME
+
+
+def workspace_state_dir(workspace: str | Path) -> Path:
+    preferred = workspace_data_dir(workspace) / "state"
+    legacy = legacy_workspace_data_dir(workspace) / "state"
+    return preferred if preferred.exists() or not legacy.exists() else legacy
+
+
+def workspace_runtime_dir(workspace: str | Path) -> Path:
+    preferred = workspace_data_dir(workspace)
+    legacy = legacy_workspace_data_dir(workspace)
+    return preferred if (preferred / "run.pid").exists() or not (legacy / "run.pid").exists() else legacy
+
+
+def workspace_installer_dir(workspace: str | Path) -> Path:
+    preferred = workspace_data_dir(workspace) / "installer"
+    legacy = legacy_workspace_data_dir(workspace) / "installer"
+    return preferred if preferred.exists() or not legacy.exists() else legacy
+
+
+def workspace_data_dirs(workspace: str | Path) -> tuple[Path, Path]:
+    return workspace_data_dir(workspace), legacy_workspace_data_dir(workspace)