texai 0.1.0__py3-none-any.whl

texai/__init__.py

@@ -0,0 +1,5 @@
+"""texai: a tiny local PDF viewer that maps clicks back to LaTeX source."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

texai/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

texai/agent.py

@@ -0,0 +1,366 @@
+"""The background Claude Agent SDK session that edits the document.
+
+One long-lived session per project, so the agent accumulates knowledge of the
+paper across turns instead of re-reading it every time. Everything it emits is
+republished on the event bus, which is what the chat panel renders.
+
+The SDK is an optional dependency: without it the viewer, SyncTeX bridge and
+selection file all still work, and the chat panel reports why it is disabled.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from . import transcript
+from .config import AppConfig
+from .events import EventBus
+from .navigate import LocateError, locate
+from .prompt import SYSTEM_PROMPT_APPEND
+
+__all__ = ["AgentUnavailable", "TurnOutcome", "AgentSession", "sdk_status"]
+
+# Everything the agent needs to edit LaTeX. Bash is deliberately absent: the
+# harness owns compilation, so a shell would only add risk and thrash.
+ALLOWED_TOOLS = [
+    "Read",
+    "Write",
+    "Edit",
+    "Glob",
+    "Grep",
+    "NotebookEdit",
+    # In-process tool that scrolls the user's PDF view (see build_navigation_server).
+    "mcp__texai__show_in_pdf",
+]
+DISALLOWED_TOOLS = ["Bash", "WebFetch", "WebSearch", "Task", "KillShell", "BashOutput"]
+
+INSTALL_HINT = (
+    "The Claude Agent SDK is not installed. Run `uv sync --group agent` "
+    "(or `uv add claude-agent-sdk`) and restart texai."
+)
+CLI_HINT = (
+    "The `claude` CLI was not found on PATH. The Agent SDK drives it, so install "
+    "Claude Code and make sure `claude` is runnable."
+)
+
+
+class AgentUnavailable(RuntimeError):
+    """The agent cannot run (SDK missing, CLI missing, or start-up failed)."""
+
+
+@dataclass
+class TurnOutcome:
+    """What one agent turn produced."""
+
+    ok: bool
+    text: str = ""
+    tool_calls: list[dict[str, Any]] = field(default_factory=list)
+    entries: list[dict[str, Any]] = field(default_factory=list)
+    error: str | None = None
+    terminal_reason: str | None = None
+    cost_usd: float | None = None
+    duration_ms: int | None = None
+    num_turns: int | None = None
+    session_id: str | None = None
+
+
+def sdk_status() -> tuple[bool, str | None]:
+    """Whether the agent can run here, and why not if it cannot."""
+    import shutil
+
+    try:
+        import claude_agent_sdk  # noqa: F401
+    except ImportError:
+        return False, INSTALL_HINT
+    if shutil.which("claude") is None:
+        return False, CLI_HINT
+    return True, None
+
+
+def _relative(path_value: Any, root: Path) -> str:
+    """Show tool paths relative to the project root; they are long otherwise."""
+    try:
+        return str(Path(str(path_value)).resolve().relative_to(root))
+    except (ValueError, OSError, TypeError):
+        return str(path_value)
+
+
+def summarize_tool_use(name: str, tool_input: dict[str, Any], root: Path) -> str:
+    """A one-line description of a tool call for the activity log."""
+    if name in ("Read", "Write", "Edit", "NotebookEdit"):
+        target = tool_input.get("file_path") or tool_input.get("notebook_path")
+        return _relative(target, root) if target else ""
+    if name in ("Glob", "Grep"):
+        pattern = tool_input.get("pattern", "")
+        path = tool_input.get("path")
+        return f"{pattern} in {_relative(path, root)}" if path else str(pattern)
+    for key in ("command", "description", "prompt"):
+        if key in tool_input:
+            return str(tool_input[key])[:200]
+    return ""
+
+
+SHOW_IN_PDF_DESCRIPTION = """
+Scroll the user's PDF view to a source location, so they are looking at the
+thing you are talking about.
+
+Call this whenever the user asks to be shown, taken to, or pointed at something
+in the document — a table, a figure, a definition, an equation, a section — and
+whenever your answer refers to a specific place they would want to see. Find the
+file and line first (Grep is usually enough), then call this with them.
+
+It moves the view only; it changes nothing. Prefer calling it over describing
+where something is in words.
+""".strip()
+
+
+def build_navigation_server(config: AppConfig, bus: EventBus) -> Any:
+    """An in-process MCP server giving the agent one action: move the view.
+
+    Runs in this process, so the handler can publish straight onto the event
+    bus the browser is already listening to.
+    """
+    from claude_agent_sdk import create_sdk_mcp_server, tool
+
+    @tool(
+        "show_in_pdf",
+        SHOW_IN_PDF_DESCRIPTION,
+        {
+            "file": str,
+            "line": int,
+            "why": str,
+        },
+    )
+    async def show_in_pdf(args: dict[str, Any]) -> dict[str, Any]:
+        file = str(args.get("file", "")).strip()
+        line = int(args.get("line", 1) or 1)
+        why = str(args.get("why", "") or "").strip()
+
+        try:
+            found = await asyncio.to_thread(locate, config, file, line)
+        except LocateError as exc:
+            return {"content": [{"type": "text", "text": f"Could not show that: {exc}"}]}
+
+        if not found["found"]:
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": (
+                            f"SyncTeX has no record of {found['file']}:{found['line']}, so the "
+                            "view did not move. That line may produce no output (a comment, a "
+                            "definition, or something inside an untracked environment) — try a "
+                            "line that renders visible text."
+                        ),
+                    }
+                ]
+            }
+
+        bus.publish("navigate", **found, why=why)
+        return {
+            "content": [
+                {
+                    "type": "text",
+                    "text": (
+                        f"Showing {found['file']}:{found['line']} — the view moved to page "
+                        f"{found['page']}."
+                    ),
+                }
+            ]
+        }
+
+    return create_sdk_mcp_server(name="texai", version="1.0.0", tools=[show_in_pdf])
+
+
+class AgentSession:
+    """A single persistent agent conversation scoped to one project."""
+
+    def __init__(self, config: AppConfig, bus: EventBus, model: str | None = None) -> None:
+        self.config = config
+        self.bus = bus
+        self.model = model
+        self._client: Any = None
+        self._lock = asyncio.Lock()
+        self._started = False
+        self._session_id: str | None = None
+
+    @property
+    def running(self) -> bool:
+        return self._started
+
+    @property
+    def session_id(self) -> str | None:
+        """The Claude Code session id, once the first turn has reported it.
+
+        This is what makes `claude --resume <id>` attach a real terminal to the
+        very conversation the panel is driving.
+        """
+        return self._session_id
+
+    def resume_command(self) -> str | None:
+        if not self._session_id:
+            return None
+        return f"claude --resume {self._session_id}"
+
+    async def start(self) -> None:
+        """Connect the session. Raises :class:`AgentUnavailable` if it cannot."""
+        if self._started:
+            return
+
+        ok, reason = sdk_status()
+        if not ok:
+            raise AgentUnavailable(reason or "agent unavailable")
+
+        from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient
+
+        options = ClaudeAgentOptions(
+            cwd=str(self.config.root),
+            mcp_servers={"texai": build_navigation_server(self.config, self.bus)},
+            permission_mode="acceptEdits",
+            allowed_tools=list(ALLOWED_TOOLS),
+            disallowed_tools=list(DISALLOWED_TOOLS),
+            # Pick up the project's CLAUDE.md, skills and settings, like the CLI.
+            setting_sources=["user", "project"],
+            system_prompt={
+                "type": "preset",
+                "preset": "claude_code",
+                "append": SYSTEM_PROMPT_APPEND,
+            },
+            **({"model": self.model} if self.model else {}),
+        )
+
+        try:
+            self._client = ClaudeSDKClient(options=options)
+            await self._client.connect()
+        except Exception as exc:  # noqa: BLE001 - surfaced to the UI verbatim
+            self._client = None
+            raise AgentUnavailable(f"Could not start the agent session: {exc}") from exc
+
+        self._started = True
+        self.bus.publish("agent_ready", model=self.model)
+
+    async def run_turn(self, prompt: str, turn_id: str) -> TurnOutcome:
+        """Send one turn and stream everything it produces onto the bus."""
+        if not self._started or self._client is None:
+            raise AgentUnavailable("agent session is not running")
+
+        from claude_agent_sdk import (
+            AssistantMessage,
+            ResultMessage,
+            SystemMessage,
+            TextBlock,
+            ThinkingBlock,
+            ToolResultBlock,
+            ToolUseBlock,
+            UserMessage,
+        )
+
+        texts: list[str] = []
+        tool_calls: list[dict[str, Any]] = []
+        entries: list[dict[str, Any]] = []
+        tool_names: dict[str, str] = {}  # tool_use_id -> tool name, to label results
+        outcome = TurnOutcome(ok=False)
+
+        def emit(entry: dict[str, Any]) -> None:
+            entries.append(entry)
+            self.bus.publish("agent_entry", turnId=turn_id, entry=entry)
+
+        async with self._lock:
+            try:
+                await self._client.query(prompt)
+                async for message in self._client.receive_response():
+                    if isinstance(message, AssistantMessage):
+                        for block in message.content:
+                            if isinstance(block, TextBlock):
+                                texts.append(block.text)
+                                emit(transcript.text_entry(block.text))
+                            elif isinstance(block, ToolUseBlock):
+                                tool_names[block.id] = block.name
+                                summary = summarize_tool_use(
+                                    block.name, block.input or {}, self.config.root
+                                )
+                                tool_calls.append({"name": block.name, "summary": summary})
+                                emit(
+                                    transcript.tool_use_entry(
+                                        block.name, summary, block.input or {}
+                                    )
+                                )
+                            elif isinstance(block, ThinkingBlock):
+                                emit(transcript.thinking_entry())
+                    elif isinstance(message, UserMessage):
+                        # Tool results come back as user turns, as in Claude Code.
+                        for block in message.content:
+                            if isinstance(block, ToolResultBlock):
+                                emit(
+                                    transcript.tool_result_entry(
+                                        tool_names.get(block.tool_use_id, "tool"),
+                                        block.content,
+                                        bool(block.is_error),
+                                    )
+                                )
+                    elif isinstance(message, SystemMessage):
+                        entry = transcript.system_entry(message.subtype, message.data)
+                        if entry is not None:  # routine bookkeeping is dropped
+                            emit(entry)
+                    elif isinstance(message, ResultMessage):
+                        subtype = getattr(message, "subtype", None)
+                        new_session = getattr(message, "session_id", None)
+                        if new_session and new_session != self._session_id:
+                            self._session_id = new_session
+                            # Lets the UI offer `claude --resume <id>` right away.
+                            self.bus.publish(
+                                "agent_session",
+                                sessionId=new_session,
+                                resumeCommand=self.resume_command(),
+                            )
+                        outcome = TurnOutcome(
+                            ok=subtype != "error",
+                            text="".join(texts),
+                            tool_calls=tool_calls,
+                            entries=entries,
+                            terminal_reason=getattr(message, "terminal_reason", None),
+                            cost_usd=getattr(message, "total_cost_usd", None),
+                            duration_ms=getattr(message, "duration_ms", None),
+                            num_turns=getattr(message, "num_turns", None),
+                            session_id=self._session_id,
+                        )
+                        emit(
+                            transcript.result_entry(
+                                status=subtype or "done",
+                                cost_usd=outcome.cost_usd,
+                                duration_ms=outcome.duration_ms,
+                                num_turns=outcome.num_turns,
+                            )
+                        )
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:  # noqa: BLE001 - surfaced to the UI verbatim
+                outcome = TurnOutcome(
+                    ok=False,
+                    text="".join(texts),
+                    tool_calls=tool_calls,
+                    entries=entries,
+                    error=str(exc),
+                )
+
+        if outcome.error:
+            emit(transcript.notice_entry(outcome.error, is_error=True))
+            self.bus.publish("agent_error", turnId=turn_id, message=outcome.error)
+        return outcome
+
+    async def interrupt(self) -> None:
+        if self._started and self._client is not None:
+            await self._client.interrupt()
+            self.bus.publish("agent_interrupted")
+
+    async def stop(self) -> None:
+        if self._client is not None:
+            try:
+                await self._client.disconnect()
+            except Exception:  # noqa: BLE001 - shutdown is best effort
+                pass
+        self._client = None
+        self._started = False

texai/build.py

@@ -0,0 +1,177 @@
+"""Compiling the document.
+
+The harness owns the build rather than the agent. That is what makes the rest
+of the loop deterministic: we know exactly when a build started, we can diff
+against the snapshot taken just before it, and we can hand compilation errors
+back to the agent as a follow-up turn instead of watching it guess.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import shlex
+from dataclasses import dataclass, field
+from pathlib import Path
+
+__all__ = [
+    "BuildResult",
+    "BuildError",
+    "default_build_command",
+    "find_root_tex",
+    "parse_log_errors",
+    "run_build",
+]
+
+BUILD_TIMEOUT_SECONDS = 300.0
+MAX_LOG_ERRORS = 12
+MAX_OUTPUT_CHARS = 20_000
+
+
+class BuildError(RuntimeError):
+    """The build could not be started at all (bad command, missing binary)."""
+
+
+@dataclass(frozen=True)
+class BuildResult:
+    ok: bool
+    command: list[str]
+    returncode: int | None
+    output: str
+    errors: list[str] = field(default_factory=list)
+    timed_out: bool = False
+
+    def summary(self) -> str:
+        if self.ok:
+            return "Build succeeded."
+        if self.timed_out:
+            return f"Build timed out after {BUILD_TIMEOUT_SECONDS:g}s."
+        head = "\n".join(self.errors[:MAX_LOG_ERRORS]) or self.output[-2000:]
+        return f"Build failed (exit {self.returncode}).\n{head}"
+
+
+def find_root_tex(pdf_path: Path, root: Path) -> Path | None:
+    """Guess the root LaTeX file for a PDF.
+
+    A sibling ``<stem>.tex`` wins; otherwise the first file under the project
+    root that declares ``\\begin{document}``.
+    """
+    sibling = pdf_path.with_suffix(".tex")
+    if sibling.is_file():
+        return sibling
+
+    candidates = sorted(root.rglob("*.tex"))
+    for candidate in candidates:
+        if candidate.name == f"{pdf_path.stem}.tex":
+            return candidate
+    for candidate in candidates:
+        try:
+            if "\\begin{document}" in candidate.read_text(encoding="utf-8", errors="replace"):
+                return candidate
+        except OSError:
+            continue
+    return None
+
+
+def default_build_command(root_tex: Path) -> list[str]:
+    return [
+        "latexmk",
+        "-pdf",
+        "-synctex=1",
+        "-interaction=nonstopmode",
+        root_tex.name,
+    ]
+
+
+def parse_log_errors(log_text: str) -> list[str]:
+    """Pull the useful error lines out of a LaTeX log.
+
+    TeX errors start with ``!`` and the offending source line follows a few
+    lines later as ``l.<number>``; we stitch those together so the agent gets
+    "what went wrong" and "where" in one string.
+    """
+    errors: list[str] = []
+    lines = log_text.splitlines()
+
+    for index, line in enumerate(lines):
+        if not line.startswith("!"):
+            continue
+        message = line.strip()
+        location = ""
+        for following in lines[index + 1 : index + 12]:
+            match = re.match(r"^l\.(\d+)(.*)", following)
+            if match:
+                location = f" (line {match.group(1)}){match.group(2).rstrip()}"
+                break
+        errors.append(f"{message}{location}")
+        if len(errors) >= MAX_LOG_ERRORS:
+            break
+
+    if not errors:
+        for line in lines:
+            if "LaTeX Error" in line or "Emergency stop" in line:
+                errors.append(line.strip())
+                if len(errors) >= MAX_LOG_ERRORS:
+                    break
+    return errors
+
+
+def resolve_command(command: str | None, root_tex: Path | None) -> list[str]:
+    """Turn a configured build command into an argv list.
+
+    Parsed with ``shlex`` and run without a shell, so pipes and ``&&`` are not
+    supported by design — point ``--build-cmd`` at a script if you need them.
+    """
+    if command:
+        argv = shlex.split(command)
+        if not argv:
+            raise BuildError("--build-cmd is empty")
+        return argv
+    if root_tex is None:
+        raise BuildError(
+            "No build command configured and no root .tex file found. "
+            "Pass --build-cmd, e.g. "
+            "--build-cmd 'latexmk -pdf -synctex=1 -interaction=nonstopmode main.tex'."
+        )
+    return default_build_command(root_tex)
+
+
+async def run_build(argv: list[str], cwd: Path, log_path: Path | None = None) -> BuildResult:
+    """Run the build, returning its output plus any parsed LaTeX errors."""
+    try:
+        process = await asyncio.create_subprocess_exec(
+            *argv,
+            cwd=str(cwd),
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.STDOUT,
+        )
+    except FileNotFoundError as exc:
+        raise BuildError(f"Build command not found: {argv[0]}") from exc
+    except PermissionError as exc:
+        raise BuildError(f"Build command is not executable: {argv[0]}") from exc
+
+    timed_out = False
+    try:
+        stdout, _ = await asyncio.wait_for(process.communicate(), timeout=BUILD_TIMEOUT_SECONDS)
+    except asyncio.TimeoutError:
+        timed_out = True
+        process.kill()
+        stdout, _ = await process.communicate()
+
+    output = (stdout or b"").decode("utf-8", errors="replace")[-MAX_OUTPUT_CHARS:]
+    ok = not timed_out and process.returncode == 0
+
+    errors: list[str] = []
+    if not ok:
+        errors = parse_log_errors(output)
+        if not errors and log_path is not None and log_path.is_file():
+            errors = parse_log_errors(log_path.read_text(encoding="utf-8", errors="replace"))
+
+    return BuildResult(
+        ok=ok,
+        command=argv,
+        returncode=process.returncode,
+        output=output,
+        errors=errors,
+        timed_out=timed_out,
+    )