attocode-code-intel 0.1.0__py3-none-any.whl

attocode_intel/onboarding.py

@@ -0,0 +1,258 @@
+"""Reversible client configuration and end-to-end installation diagnostics."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+import tomlkit
+
+from attocode_intel.catalog import INSTRUCTIONS
+from attocode_intel.project_dir import cache_folder
+
+NAME = "attocode-code-intel"
+REMOTE_NAME = NAME + "-remote"
+START = "<!-- attocode-code-intel:start -->"
+END = "<!-- attocode-code-intel:end -->"
+
+
+def client_paths(client: str, project: Path, global_scope: bool):
+    home = Path.home()
+    if client == "codex":
+        base = home / ".codex" if global_scope else project / ".codex"
+        return (
+            base / "config.toml",
+            (base / "AGENTS.md" if global_scope else project / "AGENTS.md"),
+            "mcp_servers",
+        )
+    if client == "claude":
+        return (
+            (home / ".claude.json" if global_scope else project / ".mcp.json"),
+            (home / ".claude/CLAUDE.md" if global_scope else project / "CLAUDE.md"),
+            "mcpServers",
+        )
+    if client == "cursor":
+        return (
+            (home if global_scope else project) / ".cursor/mcp.json",
+            project / ".cursor/rules/attocode-code-intel.mdc",
+            "mcpServers",
+        )
+    raise ValueError(f"Unsupported client: {client}")
+
+
+def atomic_write(path: Path, text: str):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    mode = path.stat().st_mode & 0o777 if path.exists() else 0o600
+    fd, temporary = tempfile.mkstemp(prefix=".intel-", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as stream:
+            stream.write(text)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.chmod(temporary, mode)
+        os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+def _instruction_text(path: Path, client: str, remove=False):
+    text = path.read_text() if path.exists() else ""
+    if (START in text) != (END in text):
+        raise ValueError(f"Incomplete managed instruction block in {path}")
+    block = f"{START}\n{INSTRUCTIONS}\n{END}"
+    if START in text:
+        first = text.index(START)
+        last = text.index(END, first) + len(END)
+        text = text[:first] + ("" if remove else block) + text[last:]
+    elif not remove:
+        if not text and client == "cursor":
+            text = "---\nalwaysApply: true\n---\n"
+        text = text.rstrip() + "\n\n" + block + "\n"
+    return text
+
+
+def configure_client(
+    client,
+    project=".",
+    *,
+    global_scope=False,
+    profile="daily",
+    dry_run=False,
+    remove=False,
+    server="",
+    token_env="ATTOCODE_API_KEY",
+    repo="",
+):
+    if repo and not server and not remove:
+        raise ValueError("Remote installation requires --server; use --remote only with doctor or --remove")
+    root = Path(project).resolve()
+    config, guidance, key = client_paths(client, root, global_scope)
+    entry_name = REMOTE_NAME if server or repo else NAME
+    state_path = config.parent / ".attocode-intelligence-install.json"
+    # The Claude project config sits in the project root, where the record would show in git status.
+    old_state = None
+    if config.parent == root:
+        old_state, state_path = state_path, root / ".attocode" / "claude-install.json"
+    source = state_path if state_path.exists() or not (old_state and old_state.exists()) else old_state
+    state = json.loads(source.read_text()) if source.exists() else {}
+    is_toml = config.suffix == ".toml"
+    if config.exists():
+        raw = config.read_text()
+        document = tomlkit.parse(raw) if is_toml else json.loads(raw)
+        if not isinstance(document, dict) and not is_toml:
+            raise ValueError(f"Expected an object in {config}")
+    else:
+        document = tomlkit.document() if is_toml else {}
+    servers = document.setdefault(key, {})
+    if remove:
+        saved = state.get(entry_name)
+        if saved and servers.get(entry_name) != saved["installed"]:
+            raise ValueError(
+                f"{entry_name} was edited after installation; preserve those edits before removing it"
+            )
+        if saved and saved["previous"] is not None:
+            servers[entry_name] = saved["previous"]
+        else:
+            servers.pop(entry_name, None)
+        state.pop(entry_name, None)
+    elif server:
+        from urllib.parse import urlsplit
+
+        url = urlsplit(server)
+        if url.scheme not in ("http", "https") or not url.netloc or url.username or url.password:
+            raise ValueError("Server must be an HTTP(S) URL without embedded credentials")
+        endpoint = server.rstrip("/")
+        entry = {"url": endpoint + ("/" if endpoint.endswith("/mcp") else "/mcp/")}
+        if client == "claude":
+            entry["type"] = "http"
+        if client == "codex":
+            entry["bearer_token_env_var"] = token_env
+        else:
+            env_ref = "${" + token_env + "}" if client == "claude" else "${env:" + token_env + "}"
+            entry["headers"] = {"Authorization": "Bearer " + env_ref}
+        if repo:
+            entry.setdefault("http_headers" if client == "codex" else "headers", {})[
+                "X-Attocode-Workspace"
+            ] = repo
+        entry.setdefault("http_headers" if client == "codex" else "headers", {})[
+            "X-Attocode-Profile"
+        ] = profile
+        previous = state.get(entry_name, {}).get("previous", servers.get(entry_name))
+        state[entry_name] = {"previous": previous, "installed": entry}
+        servers[entry_name] = entry
+    else:
+        executable = Path(sys.executable).parent / NAME
+        command = str(executable) if executable.is_file() else None
+        entry = {
+            "command": command or sys.executable,
+            "args": ([] if command else ["-m", "attocode_intel.entrypoint"])
+            + ["--profile", profile],
+        }
+        if not global_scope:
+            entry["args"] += ["--project", str(root)]
+        if client == "cursor":
+            entry["type"] = "stdio"
+        previous = state.get(entry_name, {}).get("previous", servers.get(entry_name))
+        state[entry_name] = {"previous": previous, "installed": entry}
+        servers[entry_name] = entry
+    output = tomlkit.dumps(document) if is_toml else json.dumps(document, indent=2) + "\n"
+    # Claude Code shows the server instructions to the model, so a CLAUDE.md copy is a duplicate
+    # in every request. Claude gets no managed block, and an old block is removed.
+    drop = client == "claude" or (remove and not any(name in servers for name in (NAME, REMOTE_NAME)))
+    instruction = _instruction_text(guidance, client, remove=drop)
+    # Prepare everything before writing either file; previews contain no credential values.
+    if dry_run:
+        return {
+            "config": str(config),
+            "entry": entry_name,
+            "configuration": servers.get(entry_name),
+            "guidance": str(guidance),
+            "instructions": instruction,
+        }
+    atomic_write(config, output)
+    if guidance.exists() or not (remove or drop):
+        atomic_write(guidance, instruction)
+    if old_state:
+        cache_folder(root)
+    atomic_write(state_path, json.dumps(state, indent=2) + "\n")
+    if old_state and old_state.exists():
+        old_state.unlink()
+    return {"client": client, "config": str(config), "guidance": str(guidance), "removed": remove}
+
+
+async def diagnose(client, project=".", *, global_scope=False, remote=False):
+    import httpx
+    from mcp import ClientSession, StdioServerParameters
+    from mcp.client.stdio import stdio_client
+    from mcp.client.streamable_http import streamable_http_client
+
+    root = Path(project).resolve()
+    config, _, key = client_paths(client, root, global_scope)
+    name = REMOTE_NAME if remote else NAME
+    text = config.read_text() if config.exists() else ""
+    doc = (tomlkit.parse(text) if config.suffix == ".toml" else json.loads(text)) if text else {}
+    entry = doc.get(key, {}).get(name)
+    if not entry:
+        return {"client": client, "status": "not configured", "config": str(config),
+                "hint": f"Run: attocode-code-intel init --client {client}"}
+
+    async def probe(streams):
+        async with ClientSession(streams[0], streams[1]) as session:
+            await session.initialize()
+            catalog = await session.list_tools()
+            result = await session.call_tool(
+                "capabilities", {"max_tokens": 16000, **({"workspace": str(root)} if "url" not in entry else {})}
+            )
+            if result.isError:
+                raise RuntimeError(result.content)
+            payload = result.structuredContent
+            if payload is None:
+                payload = json.loads(next(item.text for item in result.content if item.type == "text"))
+            metadata = payload.get("metadata", {})
+            if "url" not in entry and metadata.get("workspace") != str(root):
+                raise RuntimeError("Server selected a different workspace")
+            query = await session.call_tool(
+                "project_summary", {"workspace": metadata["workspace"], "max_tokens": 512}
+            )
+            if query.isError:
+                raise RuntimeError("Bounded project query failed")
+            return {
+                "client": client,
+                "tools": len(catalog.tools),
+                "metadata": metadata,
+                "status": "ok",
+                "languages": payload.get("capabilities", payload.get("data", {})).get("languages", {}),
+                "precision_hint": "Optional installed language servers improve reference lookup. Restart the agent after setup; ATTOCODE_INTEL_PRECISION=off disables enrichment.",
+            }
+
+    async with asyncio.timeout(30):
+        if "url" in entry:
+            headers = dict(entry.get("http_headers", entry.get("headers", {})))
+            for name, value in headers.items():
+                for env_name, env_value in os.environ.items():
+                    value = value.replace("${env:" + env_name + "}", env_value).replace(
+                        "${" + env_name + "}", env_value
+                    )
+                headers[name] = value
+            if entry.get("bearer_token_env_var"):
+                token = os.environ.get(entry["bearer_token_env_var"], "")
+                headers["Authorization"] = "Bearer " + token
+            async with (
+                httpx.AsyncClient(headers=headers) as http,
+                streamable_http_client(entry["url"], http_client=http) as streams,
+            ):
+                return await probe(streams)
+        else:
+            params = StdioServerParameters(
+                command=entry["command"],
+                args=list(entry.get("args", [])),
+                env={**os.environ, **dict(entry.get("env", {}))},
+                cwd=str(root),
+            )
+            async with stdio_client(params) as streams:
+                return await probe(streams)

attocode_intel/output.py

@@ -0,0 +1,178 @@
+"""A single output budget, including all composed sections."""
+
+from __future__ import annotations
+
+import json
+from copy import deepcopy
+
+from mcp import types
+
+from attocode_intel._internal.integrations.utilities.token_estimate import count_tokens
+
+
+def bounded_text(text: str, max_tokens: int) -> tuple[str, bool]:
+    if max_tokens < 1:
+        raise ValueError("max_tokens must be positive")
+    if count_tokens(text) <= max_tokens:
+        return text, False
+    suffix = "\n[Truncated; narrow the query or increase max_tokens.]"
+    if count_tokens(suffix) >= max_tokens:
+        suffix = ""
+    lo, hi = 0, len(text)
+    while lo < hi:
+        mid = (lo + hi + 1) // 2
+        if count_tokens(text[:mid] + suffix) <= max_tokens:
+            lo = mid
+        else:
+            hi = mid - 1
+    return text[:lo] + suffix, True
+
+
+def compact_metadata(metadata: dict) -> dict:
+    """Provenance is mandatory; detailed diagnostics live in capabilities."""
+    result = {key: metadata[key] for key in
+              ("workspace", "workspaces", "warming_workspaces", "source", "revision",
+               "freshness", "truncated", "ranking")
+              if key in metadata}
+    coverage = metadata.get("coverage", {})
+    analysis = metadata.get("analysis", {})
+    if coverage:
+        result["index"] = {key: coverage[key] for key in
+                           ("phase", "parsed_files", "total_files", "discovery_truncated") if key in coverage}
+        if coverage.get("excluded_checkout_roots"):
+            result["index"]["excluded_checkout_roots_found"] = len(coverage["excluded_checkout_roots"])
+        if coverage.get("excluded_checkout_roots_truncated"):
+            result["index"]["excluded_checkout_roots_truncated"] = True
+    if analysis:
+        result["analysis"] = analysis.get("status", "partial")
+        result["absence_proven"] = False
+        result["precision"] = analysis.get("precision", {}).get("status", "not_requested")
+    return result
+
+
+def compact_result(metadata: dict, data) -> types.CallToolResult:
+    # Text-only MCP works in clients that ignore structuredContent and avoids duplication
+    # in clients that include both representations in the model's context.
+    text = json.dumps({"metadata": metadata, "data": data}, ensure_ascii=False, separators=(",", ":"))
+    return types.CallToolResult(content=[types.TextContent(type="text", text=text)])
+
+
+def response_tokens(result: types.CallToolResult) -> int:
+    return count_tokens(result.model_dump_json(exclude_none=True))
+
+
+def bounded_bootstrap(metadata: dict, body: str, max_tokens: int) -> types.CallToolResult:
+    """Fit whole bootstrap sections into the serialized MCP budget."""
+    if not body.startswith("## "):
+        return bounded_compact(metadata, {"result": body}, max_tokens)
+    sections = ["## " + section for section in body.removeprefix("## ").split("\n\n## ")]
+    compact = compact_metadata(metadata)
+    probe_metadata = {**compact, "truncated": True}
+    selected: list[str] = []
+    omitted_search = False
+    for section in sections:
+        candidate = "\n\n".join([*selected, section])
+        if response_tokens(compact_result(probe_metadata, {"result": candidate})) <= max_tokens:
+            selected.append(section)
+        elif section.startswith("## Relevant Code"):
+            # Search hits are indivisible evidence. Never let the generic string
+            # shortener turn a ranked result into a plausible-looking fragment.
+            omission = "## Relevant Code\nTop match omitted; increase max_tokens."
+            candidate = "\n\n".join([*selected, omission])
+            if response_tokens(compact_result(probe_metadata, {"result": candidate})) <= max_tokens:
+                selected.append(omission)
+                omitted_search = True
+            else:
+                raise ValueError("max_tokens is too small to report omitted search evidence; increase it")
+    if not selected:
+        return bounded_compact(metadata, {"result": body}, max_tokens)
+    compact["truncated"] = compact.get("truncated", False) or omitted_search or len(selected) != len(sections)
+    return compact_result(compact, {"result": "\n\n".join(selected)})
+
+
+def bounded_compact(metadata: dict, data, max_tokens: int) -> types.CallToolResult:
+    """Bound the serialized result while retaining valid data and its provenance.
+
+    The estimate uses the shared tokenizer, not a promise about every client's tokenizer.
+    Only evidence collections and prose are shortened; paths, identifiers and flags survive.
+    """
+    metadata = compact_metadata(metadata)
+    data = deepcopy(data)
+    omitted = {}
+    match data:
+        case {"results": list() as result_rows,
+              "ranking": {"candidate_pool_count": _, **ranking}}:
+            search_result_count = len(result_rows)
+            initial_search_omissions = ranking.get("omitted_results_due_to_budget", 0)
+        case _:
+            search_result_count = None
+            initial_search_omissions = 0
+    while True:
+        if search_result_count is not None:
+            delivered = len(data["results"])
+            if delivered < search_result_count:
+                data["ranking"]["delivered_count"] = delivered
+                data["ranking"]["omitted_results_due_to_budget"] = (
+                    initial_search_omissions + search_result_count - delivered
+                )
+                metadata["ranking"] = deepcopy(data["ranking"])
+                metadata["truncated"] = True
+        # Budget trimming can shorten a source page after inspection constructed its
+        # continuation. Compute the next offset from the excerpt actually delivered.
+        if (isinstance(data, dict) and isinstance(data.get("follow_up"), dict) and "next_source" in data["follow_up"]
+                and "source" in data and "definition" in data):
+            source, definition = data["source"], data["definition"]
+            if source["end_line"] < source["start_line"]:
+                raise ValueError("max_tokens is too small to include a complete source line; increase it")
+            data["follow_up"]["next_source"] = ({
+                "tool": "inspect_symbol", "symbol_name": definition["qualified_name"],
+                "file_path": definition["file_path"], "line": definition["start_line"],
+                "source_start_line": source["end_line"] + 1,
+            } if source["end_line"] < definition["end_line"] else None)
+        result = compact_result(metadata, data)
+        if response_tokens(result) <= max_tokens:
+            return result
+        choices = []
+
+        def visit(value, parent=None, key=None, path="data", choices=choices):
+            if isinstance(value, list) and value:
+                # A partial match explanation would falsely imply that omitted
+                # query terms did not match. Drop whole hits before splitting it.
+                if key not in {"matched_terms", "match_fields"}:
+                    choices.append((len(json.dumps(value)), parent, key, value, path))
+            elif isinstance(value, str) and (key in {"text", "snippet", "result", "details", "description"}):
+                if len(value) > 32:
+                    choices.append((len(value), parent, key, value, path))
+            elif isinstance(value, dict):
+                if key == "languages" and value:
+                    choices.append((len(json.dumps(value)), parent, key, value, path))
+                else:
+                    for child, item in value.items():
+                        if child not in {"omitted", "follow_up", "definition"}:
+                            visit(item, value, child, path + "." + child)
+
+        wrapper = {"data": data}
+        visit(data, wrapper, "data")
+        if not choices:
+            raise ValueError("max_tokens is too small to preserve provenance and evidence identifiers; increase it")
+        _, parent, key, value, path = max(choices, key=lambda item: item[0])
+        if isinstance(value, list):
+            keep = len(value) // 2
+            parent[key] = value[:keep]
+            omitted[path] = omitted.get(path, 0) + len(value) - keep
+        elif isinstance(value, dict):
+            keep = len(value) // 2
+            parent[key] = dict(list(value.items())[:keep])
+            omitted[path] = omitted.get(path, 0) + len(value) - keep
+        else:
+            shortened = value[:len(value) // 2]
+            # Source excerpts must end on a complete line with accurate coordinates.
+            if key == "text" and "start_line" in parent:
+                shortened = shortened.rsplit("\n", 1)[0] if "\n" in shortened else ""
+                parent["end_line"] = parent["start_line"] + len(shortened.splitlines()) - 1
+                parent["truncated"] = True
+            parent[key] = shortened
+            omitted[path] = "shortened"
+        data = wrapper["data"]
+        metadata["truncated"] = True
+        metadata["omitted"] = omitted

attocode_intel/precision.py

@@ -0,0 +1,133 @@
+"""Optional workspace-scoped language-server enrichment for daily navigation."""
+from __future__ import annotations
+
+import asyncio
+import os
+import shutil
+from pathlib import Path
+
+from ._internal.integrations.context.codebase_ast import detect_language
+from ._internal.integrations.context.syntax_evidence import symbol_position
+
+
+class PrecisionSession:
+    def __init__(self, service):
+        self.service = service
+        self.documents = {}
+        self.pending = set()
+        self.completed = {}
+        self.failures = {}
+        self.verified_languages = set()
+
+    def invalidate(self, paths):
+        self.pending.update(paths)
+        self.completed.clear()
+        self.failures.clear()
+
+    async def enrich(self, name, file_path=None, line=None):
+        if os.environ.get("ATTOCODE_INTEL_PRECISION", "auto") == "off":
+            return {"status": "disabled"}
+        from .symbol_inspection import select_definitions
+        ast = self.service._get_ast_service()
+        definitions = select_definitions(self.service, name, file_path, line)
+        if not definitions:
+            return {"status": "no_definition"}
+        if len(definitions) != 1:
+            return {"status": "ambiguous", "definitions": len(definitions)}
+        key = tuple((d.file_path, d.start_line, d.qualified_name) for d in definitions)
+        if key in self.completed:
+            return self.completed[key]
+        from ._internal.integrations.lsp.client import BUILTIN_SERVERS
+        outcomes = []
+        deadline = asyncio.get_running_loop().time() + 2.0
+        for definition in definitions[:8]:
+            language = detect_language(definition.file_path)
+            server_id = "typescript" if language == "javascript" else language
+            config = BUILTIN_SERVERS.get(server_id)
+            if not config or not shutil.which(config.command):
+                outcomes.append({"language": language, "status": "unavailable"})
+                continue
+            if server_id in self.failures:
+                outcomes.append({"language": language, "status": self.failures[server_id]})
+                continue
+            manager = self.service._get_lsp_manager()
+            try:
+                async with asyncio.timeout_at(deadline):
+                    if server_id not in manager.get_active_servers():
+                        manager._timeout = 2
+                        await manager.start_server(server_id, Path(self.service.project_dir).as_uri())
+                    # Send edits/deletions for all previously opened documents.
+                    for rel in list(self.pending):
+                        path = str(Path(self.service.project_dir) / rel)
+                        if path in self.documents:
+                            if Path(path).is_file():
+                                self.documents[path] += 1
+                                manager.notify_file_changed(path, Path(path).read_text(), self.documents[path])
+                            else:
+                                manager.notify_file_closed(path)
+                                self.documents.pop(path)
+                        elif Path(path).is_file() and manager._get_client_for_file(path):
+                            manager.notify_file_opened(path, Path(path).read_text())
+                            self.documents[path] = 1
+                        self.pending.discard(rel)
+                    path = str(Path(self.service.project_dir) / definition.file_path)
+                    if path not in self.documents:
+                        manager.notify_file_opened(path, Path(path).read_text())
+                        self.documents[path] = 1
+                    position = symbol_position(path, definition.name, definition.start_line,
+                                               definition.end_line, language)
+                    if position is None:
+                        outcomes.append({"language": language, "status": "identifier_unavailable"})
+                        continue
+                    # Supply the explicit queried symbol; body ranges alone are ambiguous.
+                    callback = manager.on_result_callback
+                    manager.on_result_callback = None
+                    try:
+                        resolved = await manager.get_definition(path, *position)
+                        if resolved is None:
+                            outcomes.append({"language": language, "status": "not_resolved"})
+                            continue
+                        references = await manager.get_references(path, *position, include_declaration=False)
+                        # Some servers initially know only the opened definition. Prime a
+                        # bounded set of indexed candidates, then retry once within the same
+                        # deadline. No sleeps, background warmup, or unbounded file reads.
+                        candidates = ast.get_callers(definition.qualified_name)
+                        if not references and candidates:
+                            root = Path(self.service.project_dir).resolve()
+                            remaining_bytes = 256_000
+                            for rel in sorted({ref.file_path for ref in candidates})[:8]:
+                                if asyncio.get_running_loop().time() >= deadline:
+                                    break
+                                candidate = (root / rel).resolve()
+                                if (not candidate.is_relative_to(root) or not candidate.is_file()
+                                        or str(candidate) in self.documents
+                                        or not manager._get_client_for_file(str(candidate))):
+                                    continue
+                                size = candidate.stat().st_size
+                                if size > min(64_000, remaining_bytes):
+                                    continue
+                                with candidate.open("rb") as stream:
+                                    content = stream.read(min(64_000, remaining_bytes) + 1)
+                                if len(content) > min(64_000, remaining_bytes):
+                                    continue
+                                manager.notify_file_opened(str(candidate), content.decode("utf-8", errors="replace"))
+                                self.documents[str(candidate)] = 1
+                                remaining_bytes -= len(content)
+                            references = await manager.get_references(path, *position, include_declaration=False)
+                    finally:
+                        manager.on_result_callback = callback
+                    ast.ingest_lsp_results("references", path, references,
+                                           {"line": position[0], "col": position[1],
+                                            "symbol_name": definition.qualified_name})
+                    self.verified_languages.add(language)
+                    outcomes.append({"language": language, "status": "verified" if references or not candidates else "no_references",
+                                     "symbol": definition.qualified_name, "references": len(references)})
+            except Exception as exc:
+                status = "timeout" if isinstance(exc, TimeoutError) or isinstance(exc.__cause__, TimeoutError) else "failed"
+                self.failures[server_id] = status
+                outcomes.append({"language": language, "status": status})
+        status = "verified" if outcomes and all(o["status"] == "verified" for o in outcomes) else "partial"
+        result = {"status": status, "queries": outcomes,
+                  "definitions_truncated": len(definitions) > 8}
+        self.completed[key] = result
+        return result