ctxora 6.2.0

package/src/harness_context/adapters/clients/__init__.py

@@ -0,0 +1,4 @@
+from harness_context.adapters.clients.formatters import get_formatter
+from harness_context.adapters.clients.profiles import PROFILES, ClientProfile, get_profile
+
+__all__ = ["PROFILES", "ClientProfile", "get_formatter", "get_profile"]

package/src/harness_context/adapters/clients/formatters.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import asdict, is_dataclass
+from typing import Any
+
+
+class ProviderFormatter:
+    def format(self, payload: Any) -> dict[str, Any]:
+        if hasattr(payload, "to_dict"):
+            payload = payload.to_dict()
+        elif is_dataclass(payload):
+            payload = asdict(payload)
+        if not isinstance(payload, dict):
+            raise TypeError("provider payload must be a mapping or dataclass")
+        return deepcopy(payload)
+
+
+class CodexFormatter(ProviderFormatter):
+    pass
+
+
+class ClaudeCodeFormatter(ProviderFormatter):
+    pass
+
+
+class CursorFormatter(ProviderFormatter):
+    pass
+
+
+class GenericMcpFormatter(ProviderFormatter):
+    pass
+
+
+FORMATTERS = {
+    "codex": CodexFormatter,
+    "claude-code": ClaudeCodeFormatter,
+    "cursor": CursorFormatter,
+    "generic-mcp": GenericMcpFormatter,
+}
+
+
+def get_formatter(name: str) -> ProviderFormatter:
+    try:
+        return FORMATTERS[name]()
+    except KeyError as exc:
+        raise ValueError(f"unknown provider formatter: {name}") from exc

package/src/harness_context/adapters/clients/profiles.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from harness_context.branding import MCP_SERVER_KEY
+
+
+@dataclass(frozen=True)
+class ClientProfile:
+    name: str
+    config_format: str
+    default_config: Path
+    server_key: str = MCP_SERVER_KEY
+
+
+PROFILES = {
+    "codex": ClientProfile("codex", "toml", Path("~/.codex/config.toml")),
+    "claude-code": ClientProfile("claude-code", "json", Path("~/.claude.json")),
+    "cursor": ClientProfile("cursor", "json", Path("~/.cursor/mcp.json")),
+    "generic-mcp": ClientProfile("generic-mcp", "json", Path("~/.config/mcp/servers.json")),
+}
+
+
+def get_profile(name: str) -> ClientProfile:
+    try:
+        return PROFILES[name]
+    except KeyError as exc:
+        raise ValueError(f"unknown client profile: {name}") from exc

package/src/harness_context/adapters/ecc/__init__.py

@@ -0,0 +1,4 @@
+from harness_context.adapters.ecc.detection import EccInstallation, detect_ecc
+from harness_context.adapters.ecc.memory_reader import EccMemoryReader
+
+__all__ = ["EccInstallation", "EccMemoryReader", "detect_ecc"]

package/src/harness_context/adapters/ecc/detection.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class EccInstallation:
+    project_memory_root: Path | None
+    user_memory_root: Path | None
+    allow_user_scope: bool
+
+    @property
+    def available(self) -> bool:
+        return self.project_memory_root is not None or self.user_memory_root is not None
+
+
+def _existing_directory(path: str | Path) -> Path | None:
+    candidate = Path(path).expanduser()
+    if candidate.is_symlink() or not candidate.is_dir():
+        return None
+    return candidate.resolve()
+
+
+def detect_ecc(
+    workspace_root: str | Path,
+    *,
+    allow_user_scope: bool = False,
+    environment: dict[str, str] | None = None,
+) -> EccInstallation:
+    """Detect existing ECC memory vaults without installing or cloning ECC."""
+    env = environment if environment is not None else os.environ
+    workspace = Path(workspace_root).expanduser().resolve(strict=True)
+    project_override = env.get("ECC_MEMORY_PROJECT_ROOT")
+    user_override = env.get("ECC_MEMORY_USER_ROOT")
+    project_root = _existing_directory(project_override or workspace / ".ecc" / "memory")
+    user_root = None
+    if allow_user_scope:
+        user_root = _existing_directory(user_override or Path.home() / ".ecc" / "memory")
+    return EccInstallation(project_root, user_root, allow_user_scope)

package/src/harness_context/adapters/ecc/mapping.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from harness_context.adapters.ecc.provenance import ecc_provenance
+
+_TYPE_MAP = {
+    "handoff": "episodic",
+    "lesson": "procedural",
+    "runbook": "procedural",
+    "context": "semantic",
+    "decision": "semantic",
+    "fact": "semantic",
+    "note": "semantic",
+    "preference": "semantic",
+}
+
+
+def map_ecc_memory(memory: dict, source_path) -> dict:
+    """Map ECC context into Harness's provider-neutral read-only memory shape."""
+    return {
+        "workspace_id": "external:ecc",
+        "type": _TYPE_MAP[memory["kind"]],
+        "key": memory["id"],
+        "value": memory["body"],
+        "title": memory["title"],
+        "tags": ",".join(memory["tags"]),
+        "scope": memory["scope"],
+        "source": f"ecc:{memory['sourceHarness']}",
+        "confidence": 0.5,
+        "status": memory["status"],
+        "links": list(memory["links"]),
+        "provenance": ecc_provenance(memory, source_path),
+    }

package/src/harness_context/adapters/ecc/memory_reader.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from harness_context.adapters.ecc.detection import EccInstallation
+from harness_context.adapters.ecc.mapping import map_ecc_memory
+from harness_context.tokenize import tokens
+
+_FIELDS = {
+    "schema": "schema", "id": "id", "title": "title", "kind": "kind",
+    "scope": "scope", "trust": "trust", "status": "status",
+    "source_harness": "sourceHarness", "target_harnesses": "targetHarnesses",
+    "tags": "tags", "links": "links", "created_at": "createdAt",
+    "updated_at": "updatedAt",
+}
+_KINDS = {"context", "decision", "fact", "handoff", "lesson", "note", "preference", "runbook"}
+_SCOPES = {"project", "team", "user"}
+_STATUSES = {"active", "rejected", "superseded"}
+_ID = re.compile(r"^mem_[a-z0-9][a-z0-9_-]{2,127}$")
+_SLUG = re.compile(r"^[a-z0-9][a-z0-9._-]{0,63}$")
+_TIMESTAMP = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$")
+_SECRETS = (
+    re.compile(r"\bsk-[A-Za-z0-9_-]{16,}\b", re.IGNORECASE),
+    re.compile(r"\b(?:sk|rk)_live_[A-Za-z0-9]{16,}\b"),
+    re.compile(r"\bnpm_[A-Za-z0-9]{20,}\b"),
+    re.compile(r"\bhf_[A-Za-z0-9]{20,}\b"),
+    re.compile(r"\bgh[pors]_[A-Za-z0-9]{16,}\b"),
+    re.compile(r"\bgithub_pat_[A-Za-z0-9_]{16,}\b"),
+    re.compile(r"\bAIza[A-Za-z0-9_-]{16,}\b"),
+    re.compile(r"\bxox[baprs]-[A-Za-z0-9-]{10,}\b"),
+    re.compile(r"\b(?:AKIA|ASIA)[A-Z0-9]{16}\b"),
+    re.compile(r"-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----"),
+)
+
+
+def _has_unsafe_characters(value: str, allow_whitespace: bool = False) -> bool:
+    for character in value:
+        code = ord(character)
+        if allow_whitespace and character in "\t\n\r":
+            continue
+        if code <= 0x1F or 0x7F <= code <= 0x9F or 0x202A <= code <= 0x202E or 0x2066 <= code <= 0x2069:
+            return True
+    return False
+
+
+class EccMemoryReader:
+    """Bounded, read-only reader for ECC's ecc.memory.v1 Markdown vault."""
+
+    def __init__(self, installation: EccInstallation, target_harness: str = "ctxora"):
+        self.installation = installation
+        self.target_harness = target_harness
+        self.target_harnesses = {target_harness, "harness-context"}
+
+    def status(self) -> dict:
+        roots = [root for root in (self.installation.project_memory_root, self.installation.user_memory_root) if root]
+        return {
+            "available": self.installation.available,
+            "read_only": True,
+            "project_memory_root": str(self.installation.project_memory_root) if self.installation.project_memory_root else None,
+            "user_memory_root": str(self.installation.user_memory_root) if self.installation.user_memory_root else None,
+            "roots": len(roots),
+        }
+
+    @staticmethod
+    def _parse(path: Path) -> dict:
+        if path.is_symlink() or path.stat().st_size > 128 * 1024:
+            raise ValueError("ECC memory file is unsafe or oversized")
+        source = path.read_text("utf-8")
+        if not source.startswith("---\n"):
+            raise ValueError("ECC memory document must start with frontmatter")
+        frontmatter, separator, body = source[4:].partition("\n---\n")
+        if not separator:
+            raise ValueError("ECC memory document has no closing frontmatter")
+        parsed = {}
+        for line in frontmatter.splitlines():
+            key, marker, value = line.partition(":")
+            if not marker or key not in _FIELDS or _FIELDS[key] in parsed:
+                raise ValueError("invalid ECC memory frontmatter")
+            parsed[_FIELDS[key]] = json.loads(value.strip())
+        required = set(_FIELDS.values())
+        if set(parsed) != required:
+            raise ValueError("incomplete ECC memory frontmatter")
+        parsed["body"] = body.strip()
+        if parsed["schema"] != "ecc.memory.v1" or not _ID.fullmatch(parsed["id"]):
+            raise ValueError("unsupported ECC memory schema or id")
+        if not isinstance(parsed["title"], str) or not parsed["title"].strip() or len(parsed["title"]) > 200:
+            raise ValueError("invalid ECC memory title")
+        if _has_unsafe_characters(parsed["title"]):
+            raise ValueError("unsafe ECC memory title")
+        if parsed["kind"] not in _KINDS or parsed["scope"] not in _SCOPES:
+            raise ValueError("unsupported ECC memory kind or scope")
+        if parsed["trust"] != "unreviewed" or parsed["status"] not in _STATUSES:
+            raise ValueError("unsupported ECC memory trust or status")
+        if not _SLUG.fullmatch(parsed["sourceHarness"]):
+            raise ValueError("invalid ECC source harness")
+        if not _TIMESTAMP.fullmatch(parsed["createdAt"]) or not _TIMESTAMP.fullmatch(parsed["updatedAt"]):
+            raise ValueError("invalid ECC timestamp")
+        if not parsed["body"] or len(parsed["body"].encode("utf-8")) > 64 * 1024:
+            raise ValueError("invalid ECC memory body")
+        if _has_unsafe_characters(parsed["body"], allow_whitespace=True):
+            raise ValueError("unsafe ECC memory body")
+        if any(pattern.search(parsed["body"]) for pattern in _SECRETS):
+            raise ValueError("ECC memory contains a secret-like value")
+        for field in ("targetHarnesses", "tags"):
+            if not isinstance(parsed[field], list) or not all(isinstance(value, str) and _SLUG.fullmatch(value) for value in parsed[field]):
+                raise ValueError(f"invalid ECC {field}")
+            if len(parsed[field]) != len(set(parsed[field])):
+                raise ValueError(f"duplicate ECC {field}")
+        if not parsed["targetHarnesses"] or len(parsed["targetHarnesses"]) > 32 or len(parsed["tags"]) > 32:
+            raise ValueError("invalid ECC target or tag count")
+        if not isinstance(parsed["links"], list) or not all(_ID.fullmatch(value) for value in parsed["links"]):
+            raise ValueError("invalid ECC links")
+        if len(parsed["links"]) > 64:
+            raise ValueError("too many ECC links")
+        if len(parsed["links"]) != len(set(parsed["links"])):
+            raise ValueError("duplicate ECC links")
+        return parsed
+
+    def read(self) -> tuple[list[dict], list[dict]]:
+        entries, diagnostics = [], []
+        roots = [root for root in (self.installation.project_memory_root, self.installation.user_memory_root) if root]
+        for root in roots:
+            for path in sorted(root.rglob("*.md"))[:1_000]:
+                try:
+                    memory = self._parse(path)
+                    is_user_root = root == self.installation.user_memory_root
+                    allowed_scopes = {"user"} if is_user_root else {"project", "team"}
+                    if memory["scope"] not in allowed_scopes:
+                        raise ValueError("ECC memory scope does not match its vault location")
+                    if memory["status"] != "active":
+                        continue
+                    if not self.target_harnesses.intersection(memory["targetHarnesses"]) and "all" not in memory["targetHarnesses"]:
+                        continue
+                    entries.append(map_ecc_memory(memory, path))
+                except (OSError, UnicodeError, ValueError) as error:
+                    diagnostics.append({"path": str(path), "error": str(error)})
+        counts = {}
+        for entry in entries:
+            counts[entry["key"]] = counts.get(entry["key"], 0) + 1
+        duplicates = {key for key, count in counts.items() if count > 1}
+        if duplicates:
+            entries = [entry for entry in entries if entry["key"] not in duplicates]
+            diagnostics.extend({"memory_id": key, "error": "duplicate ECC memory id"} for key in sorted(duplicates))
+        return entries, diagnostics[:100]
+
+    def search(self, query: str, limit: int = 4) -> dict:
+        entries, diagnostics = self.read()
+        query_tokens = set(tokens(query))
+        ranked = []
+        for entry in entries:
+            document = set(tokens(f"{entry['title']} {entry['tags']} {entry['value']}"))
+            score = len(query_tokens & document) / max(len(query_tokens), 1)
+            if not query_tokens or score > 0:
+                ranked.append((score, entry))
+        ranked.sort(key=lambda item: (-item[0], item[1]["key"]))
+        return {
+            "entries": [{**entry, "score": score} for score, entry in ranked[:max(0, limit)]],
+            "diagnostics": diagnostics,
+            "read_only": True,
+        }

package/src/harness_context/adapters/ecc/provenance.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def ecc_provenance(memory: dict, source_path: Path) -> dict:
+    return {
+        "adapter": "ecc",
+        "schema": memory["schema"],
+        "ecc_memory_id": memory["id"],
+        "source_path": str(source_path),
+        "source_harness": memory["sourceHarness"],
+        "updated_at": memory["updatedAt"],
+        "trust": memory["trust"],
+        "read_only": True,
+    }

package/src/harness_context/api/__init__.py

@@ -0,0 +1 @@
+"""Public API schemas."""

package/src/harness_context/api/v2/__init__.py

@@ -0,0 +1,12 @@
+from harness_context.api.v2.contracts import export_json_schemas, validate_response, validate_schema
+from harness_context.api.v2.diagnostics import ContextDiagnostics
+from harness_context.api.v2.enums import ContextStrategy, ErrorCode, Freshness
+from harness_context.api.v2.errors import ErrorDetail, ErrorResponse, map_exception
+from harness_context.api.v2.requests import PrepareContextRequest
+from harness_context.api.v2.responses import ContextPackageV2
+
+__all__ = [
+    "ContextDiagnostics", "ContextPackageV2", "ContextStrategy", "ErrorCode",
+    "ErrorDetail", "ErrorResponse", "Freshness", "PrepareContextRequest",
+    "export_json_schemas", "map_exception", "validate_response", "validate_schema",
+]

package/src/harness_context/api/v2/contracts.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+OBJECT = {"type": "object", "additionalProperties": True}
+ARRAY_OBJECT = {"type": "array", "items": OBJECT}
+ARRAY_STRING = {"type": "array", "items": {"type": "string"}}
+SCHEMA_VERSION = "https://json-schema.org/draft/2020-12/schema"
+
+
+def _object(properties: dict[str, Any], required: tuple[str, ...] = ()) -> dict[str, Any]:
+    schema: dict[str, Any] = {
+        "$schema": SCHEMA_VERSION,
+        "type": "object",
+        "properties": properties,
+        "additionalProperties": False,
+    }
+    if required:
+        schema["required"] = list(required)
+    return schema
+
+
+S = {"type": "string"}
+I = {"type": "integer"}
+N = {"type": "number"}
+B = {"type": "boolean"}
+NULLABLE_S = {"type": ["string", "null"]}
+NULLABLE_N = {"type": ["number", "null"]}
+
+REQUEST_SCHEMAS: dict[str, dict[str, Any]] = {
+    "register_workspace": _object({"workspace_id": S, "roots": ARRAY_STRING, "initial_refresh": B}, ("workspace_id", "roots")),
+    "refresh_workspace": _object({"workspace_id": S, "paths": {"type": ["array", "null"], "items": S}}),
+    "plan_context": _object({"workspace_id": S, "query": S, "available_input_tokens": I, "strategy_override": S}, ("workspace_id", "query", "available_input_tokens")),
+    "retrieve_context": _object({"workspace_id": S, "query": S, "top_k": I, "graph_expand": B, "token_budget": I}, ("workspace_id", "query")),
+    "prepare_context": _object({"workspace_id": S, "query": S, "available_input_tokens": I, "preferred_strategy": S, "include_memory": B, "include_handoff": B, "handoff_id": S, "include_ecc": B, "freshness": S, "deadline_ms": I}, ("workspace_id", "query", "available_input_tokens")),
+    "context_stats": _object({"workspace_id": S}),
+    "invalidate_context": _object({"workspace_id": S, "target": S}, ("workspace_id", "target")),
+    "memory_save": _object({"workspace_id": S, "key": S, "value": S, "mtype": S, "tags": S, "scope": S, "source": S, "confidence": N, "expires_at": NULLABLE_N}, ("workspace_id", "key", "value")),
+    "memory_search": _object({"workspace_id": S, "query": S, "mtype": S, "top_k": I, "min_sim": N}, ("workspace_id", "query")),
+    "memory_delete": _object({"workspace_id": S, "key": S, "mtype": S}, ("workspace_id", "key")),
+    "memory_list": _object({"workspace_id": S, "mtype": S, "limit": I}, ("workspace_id",)),
+    "handoff_conversation": _object({"workspace_id": S, "messages_json": S, "threshold_tokens": I, "label": S, "retention_seconds": I, "consent": B}, ("workspace_id", "messages_json")),
+    "restore_conversation_handoff": _object({"workspace_id": S, "handoff_id": S}, ("workspace_id", "handoff_id")),
+    "list_conversation_handoffs": _object({"workspace_id": S, "limit": I}, ("workspace_id",)),
+    "delete_conversation_handoff": _object({"workspace_id": S, "handoff_id": S}, ("workspace_id", "handoff_id")),
+    "purge_expired_handoffs": _object({}),
+    "ecc_status": _object({}),
+    "ecc_search": _object({"query": S, "limit": I}, ("query",)),
+}
+
+RESPONSE_SCHEMAS = {name: {"$schema": SCHEMA_VERSION, **OBJECT} for name in REQUEST_SCHEMAS}
+RESPONSE_SCHEMAS.update({
+    "memory_search": {"$schema": SCHEMA_VERSION, **ARRAY_OBJECT},
+    "memory_list": {"$schema": SCHEMA_VERSION, **ARRAY_STRING},
+    "list_conversation_handoffs": {"$schema": SCHEMA_VERSION, **ARRAY_OBJECT},
+    "prepare_context": _object({
+        "api_version": S, "workspace_id": S, "snapshot_id": S, "snapshot_version": I,
+        "plan": OBJECT, "stable_context": {"type": ["object", "null"]},
+        "evidence": {"type": ["object", "null"]}, "memory": ARRAY_OBJECT,
+        "handoff": {"type": ["object", "null"]}, "external_context": ARRAY_OBJECT,
+        "diagnostics": OBJECT,
+    }, ("api_version", "workspace_id", "snapshot_id", "snapshot_version", "plan", "stable_context", "evidence", "memory", "handoff", "external_context", "diagnostics")),
+})
+
+ERROR_SCHEMA = _object({
+    "api_version": S,
+    "error": _object({"code": S, "message": S, "retryable": B, "details": OBJECT}, ("code", "message", "retryable", "details")),
+}, ("api_version", "error"))
+
+
+def _matches_type(value: Any, expected: str) -> bool:
+    return {"object": isinstance(value, dict), "array": isinstance(value, list), "string": isinstance(value, str), "integer": isinstance(value, int) and not isinstance(value, bool), "number": isinstance(value, (int, float)) and not isinstance(value, bool), "boolean": isinstance(value, bool), "null": value is None}[expected]
+
+
+def validate_schema(value: Any, schema: dict[str, Any], path: str = "$") -> None:
+    expected = schema.get("type")
+    expected_types = expected if isinstance(expected, list) else [expected]
+    if expected and not any(_matches_type(value, item) for item in expected_types):
+        raise TypeError(f"{path} must be {expected}")
+    if isinstance(value, dict):
+        for key in schema.get("required", []):
+            if key not in value:
+                raise ValueError(f"{path}.{key} is required")
+        properties = schema.get("properties", {})
+        if schema.get("additionalProperties") is False:
+            unknown = set(value) - set(properties)
+            if unknown:
+                raise ValueError(f"{path} contains unknown properties: {sorted(unknown)}")
+        for key, item in value.items():
+            if key in properties:
+                validate_schema(item, properties[key], f"{path}.{key}")
+    if isinstance(value, list) and "items" in schema:
+        for index, item in enumerate(value):
+            validate_schema(item, schema["items"], f"{path}[{index}]")
+
+
+def validate_response(contract: str, value: Any) -> Any:
+    try:
+        schema = RESPONSE_SCHEMAS[contract]
+    except KeyError as error:
+        raise KeyError(f"unknown MCP v2 response contract: {contract}") from error
+    validate_schema(value, schema)
+    return value
+
+
+def export_json_schemas(directory: str | Path) -> list[Path]:
+    destination = Path(directory)
+    destination.mkdir(parents=True, exist_ok=True)
+    documents = {f"{name}.request.schema.json": schema for name, schema in REQUEST_SCHEMAS.items()}
+    documents.update({f"{name}.response.schema.json": schema for name, schema in RESPONSE_SCHEMAS.items()})
+    documents["error.response.schema.json"] = ERROR_SCHEMA
+    written = []
+    for filename, schema in sorted(documents.items()):
+        path = destination / filename
+        path.write_text(json.dumps(schema, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        written.append(path)
+    return written

package/src/harness_context/api/v2/diagnostics.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ContextDiagnostics:
+    coverage: str = "not_applicable"
+    freshness: str = "current"
+    untrusted_content: bool = True
+    latency_ms: float = 0.0
+    ecc: dict[str, Any] = field(default_factory=dict)

package/src/harness_context/api/v2/enums.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ContextStrategy(str, Enum):
+    AUTO = "auto"
+
+
+class Freshness(str, Enum):
+    CURRENT = "current"
+
+
+class ErrorCode(str, Enum):
+    INTERNAL_ERROR = "internal_error"
+    INVALID_REQUEST = "invalid_request"
+    NOT_FOUND = "not_found"

package/src/harness_context/api/v2/errors.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from harness_context.api.v2.enums import ErrorCode
+
+
+@dataclass(frozen=True)
+class ErrorDetail:
+    code: str
+    message: str
+    retryable: bool = False
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ErrorResponse:
+    error: ErrorDetail
+    api_version: str = "2.0"
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def map_exception(error: Exception) -> ErrorResponse:
+    code = getattr(error, "code", None)
+    if isinstance(code, str):
+        return ErrorResponse(ErrorDetail(code=code, message=str(error)))
+    if isinstance(error, (TypeError, ValueError)):
+        return ErrorResponse(ErrorDetail(code=ErrorCode.INVALID_REQUEST.value, message=str(error)))
+    return ErrorResponse(ErrorDetail(code=ErrorCode.INTERNAL_ERROR.value, message=str(error)))

package/src/harness_context/api/v2/models.py

@@ -0,0 +1,4 @@
+from harness_context.api.v2.requests import PrepareContextRequest
+from harness_context.api.v2.responses import ContextPackageV2
+
+__all__ = ["ContextPackageV2", "PrepareContextRequest"]

package/src/harness_context/api/v2/requests.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class PrepareContextRequest:
+    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

package/src/harness_context/api/v2/responses.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ContextPackageV2:
+    api_version: str
+    workspace_id: str
+    snapshot_id: str
+    snapshot_version: int
+    plan: dict[str, Any]
+    stable_context: dict[str, Any] | None
+    evidence: dict[str, Any] | None
+    memory: list[dict[str, Any]] = field(default_factory=list)
+    handoff: dict[str, Any] | None = None
+    external_context: list[dict[str, Any]] = field(default_factory=list)
+    diagnostics: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)

package/src/harness_context/application/__init__.py

@@ -0,0 +1,3 @@
+from harness_context.application.services import ContextService, RefreshService
+
+__all__ = ["ContextService", "RefreshService"]

package/src/harness_context/application/container.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from compact.handoff import ConversationHandoffStore
+from harness_context.adapters.ecc import EccMemoryReader
+from harness_context.application.ecc_service import EccService
+from harness_context.application.handoff_service import HandoffService
+from harness_context.application.memory_service import MemoryService
+from harness_context.application.retrieval_service import RetrievalService
+from harness_context.application.services import ContextService, RefreshService
+from harness_context.application.workspace_service import WorkspaceService
+from harness_context.engine import ContextEngine
+from harness_context.storage import SnapshotStore
+from memory.episodic import MemoryStore
+
+
+@dataclass(frozen=True)
+class ApplicationContainer:
+    engine: ContextEngine
+    snapshots: SnapshotStore
+    refresh: RefreshService
+    context: ContextService
+    memory: MemoryStore
+    handoffs: ConversationHandoffStore
+    ecc: EccMemoryReader | None
+    workspace: WorkspaceService
+    retrieval: RetrievalService
+    memories: MemoryService
+    handoff: HandoffService
+    ecc_queries: EccService