citrus-code 0.1.0__py3-none-any.whl

citrus_code/coding/tools/read.py

@@ -0,0 +1,133 @@
+import asyncio
+import base64
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field, JsonValue
+
+from ...agent.types import ToolExecutionResult
+from ...ai.types import ImageContent, TextContent, ToolDefinition
+from .paths import resolve_to_cwd
+from .truncate import DEFAULT_MAX_BYTES, truncate_text
+
+class ReadArguments(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        strict=True
+    )
+    path: str = Field(
+        min_length=1,
+        description="The file path, absolute or relative to the working directory.",
+    )
+
+    offset: int = Field(
+        default=1,
+        ge=1,
+        description="The first line to read, starting from 1.",
+    )
+
+    limit: int | None = Field(
+        default=None,
+        ge=1,
+        description="The maximum number of lines to read.",
+    )
+
+
+class ReadTool:
+    name: str = "read"
+    description: str = (
+        "Read a UTF-8 text file or an image (PNG, JPEG, GIF, WebP, BMP). "
+        "Images are returned as attachments. Text is limited to 2000 lines or 50KB, "
+        "whichever is hit first. Use offset (1-based) and limit for large files; "
+        "continue with the suggested offset to read more."
+    )
+
+    def __init__(self, cwd: Path) -> None:
+        self._cwd = cwd.resolve()
+
+    def get_definition(self) -> ToolDefinition:
+        return ToolDefinition(
+            name=self.name,
+            description=self.description,
+            parameters=ReadArguments.model_json_schema(),
+        )
+
+    async def execute(
+        self,
+        tool_call_id: str,
+        arguments: dict[str, JsonValue],
+    ) -> ToolExecutionResult:
+        args = ReadArguments.model_validate(arguments)
+
+        path = resolve_to_cwd(args.path, self._cwd)
+
+        return await asyncio.to_thread(
+            self._read,
+            path,
+            args,
+        )
+
+    def _read(
+        self,
+        path: Path,
+        args: ReadArguments,
+    ) -> ToolExecutionResult:
+        buffer = path.read_bytes()
+        mime_type: str | None = None
+        if buffer.startswith(b"\x89PNG\r\n\x1a\n"):
+            mime_type = "image/png"
+        elif buffer.startswith(b"\xff\xd8\xff"):
+            mime_type = "image/jpeg"
+        elif buffer.startswith((b"GIF87a", b"GIF89a")):
+            mime_type = "image/gif"
+        elif buffer.startswith(b"RIFF") and buffer[8:12] == b"WEBP":
+            mime_type = "image/webp"
+        elif buffer.startswith(b"BM"):
+            mime_type = "image/bmp"
+        if mime_type is not None:
+            return ToolExecutionResult(
+                content=[
+                    TextContent(text=f"Read image file [{mime_type}]: {args.path}"),
+                    ImageContent(data=base64.b64encode(buffer).decode("ascii"), mime_type=mime_type),
+                ],
+                details={"path": str(path), "mimeType": mime_type, "bytes": len(buffer)},
+            )
+        text = buffer.decode("utf-8").replace("\r\n", "\n").replace("\r", "\n")
+        # Split only LF: Unicode separators inside source literals are not lines.
+        parts = text.split("\n")
+        lines = [line + "\n" for line in parts[:-1]]
+        if parts[-1]:
+            lines.append(parts[-1])
+        start = args.offset - 1
+        if start >= len(lines) and (lines or start != 0):
+            raise ValueError(
+                f"Offset {args.offset} is beyond end of file ({len(lines)} lines total)"
+            )
+        stop = len(lines) if args.limit is None else start + args.limit
+        truncation = truncate_text("".join(lines[start:stop]))
+        text = truncation.content
+        has_more = start + truncation.output_lines < len(lines)
+        if truncation.first_line_exceeds_limit:
+            text = (
+                f"[Line {args.offset} exceeds {DEFAULT_MAX_BYTES} bytes. "
+                "Use bash or powershell to inspect a smaller portion of this line.]"
+            )
+        elif has_more:
+            next_offset = args.offset + truncation.output_lines
+            text += (
+                f"\n\n[Showing {truncation.output_lines} lines starting at {args.offset}. "
+                f"Use offset={next_offset} to continue.]"
+            )
+
+        details: dict[str, JsonValue] = {
+            "path": str(path),
+            "offset": args.offset,
+            "lines_read": truncation.output_lines,
+            "has_more": has_more,
+        }
+        if truncation.truncated:
+            details["truncation"] = truncation.model_dump(mode="json", exclude={"content"})
+
+        return ToolExecutionResult(
+            content=[TextContent(text=text)],
+            details=details,
+        )

citrus_code/coding/tools/shell.py

@@ -0,0 +1,218 @@
+import asyncio
+import base64
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field, JsonValue
+
+from ...agent.types import ToolExecutionResult
+from ...ai.types import TextContent, ToolDefinition
+from .processes import find_executable, spawn_process, stop_process
+from .truncate import DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, truncate_text
+
+
+class ShellArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    command: str = Field(min_length=1, description="Shell command to execute.")
+    timeout: float | None = Field(
+        default=None,
+        gt=0,
+        allow_inf_nan=False,
+        description="Timeout in seconds. Omit for no timeout.",
+    )
+
+
+class ShellTool:
+    name: str = "bash"
+    description: str
+
+    def __init__(self, cwd: Path, shell_path: str | None = None) -> None:
+        self._cwd = cwd.resolve()
+        self._shell_path = shell_path
+        language = "PowerShell" if self.name == "powershell" else "Bash"
+        self.description = (
+            f"Execute a {language} command in the working directory. Returns stdout "
+            "and stderr. Keeps the last 2000 lines or 50KB; full truncated output "
+            "is saved to a temporary file. Optional timeout is in seconds."
+        )
+        if self.name == "powershell":
+            self.description += (
+                " Commands run in a fresh session; variables and cd do not persist. "
+                "Use Windows PowerShell 5.1-compatible syntax: no Bash heredocs, && or ||. "
+                "Backslash does not escape quotes in PowerShell; use single-quoted literals "
+                "or a PowerShell here-string. For complex Python/JavaScript, write a script "
+                "file first, then execute it instead of nesting code inside -c/-e."
+            )
+
+    def get_definition(self) -> ToolDefinition:
+        return ToolDefinition(
+            name=self.name,
+            description=self.description,
+            parameters=ShellArguments.model_json_schema(),
+        )
+
+    def _command(self, command: str, script_path: Path | None) -> list[str]:
+        if self.name == "powershell":
+            executable = self._shell_path or shutil.which("pwsh") or find_executable("powershell")
+            if script_path is None:
+                raise ValueError("PowerShell requires a script file")
+            encoded_path = base64.b64encode(str(script_path).encode("utf-8")).decode("ascii")
+            # Only the short launcher crosses Windows argv parsing. Read and
+            # parse the original command after UTF-8 and error handling are set,
+            # so nested quotes, long commands and parser diagnostics survive.
+            launcher = (
+                "$OutputEncoding = [Console]::OutputEncoding = "
+                "[System.Text.UTF8Encoding]::new($false); "
+                "$ErrorActionPreference = 'Stop'; "
+                "$PSNativeCommandUseErrorActionPreference = $false; "
+                "try { "
+                "$citrusCodeScriptPath = [System.Text.Encoding]::UTF8.GetString("
+                f"[System.Convert]::FromBase64String('{encoded_path}')); "
+                "& ([scriptblock]::Create([System.IO.File]::ReadAllText("
+                "$citrusCodeScriptPath, [System.Text.Encoding]::UTF8))); "
+                "if (-not $?) { "
+                "if ($LASTEXITCODE -is [int] -and $LASTEXITCODE -ne 0) { exit $LASTEXITCODE }; "
+                "exit 1 }; exit 0 "
+                "} catch { [Console]::Error.WriteLine(($_ | Out-String)); exit 1 }"
+            )
+            return [executable, "-NoLogo", "-NoProfile", "-NonInteractive", "-Command", launcher]
+
+        executable = self._shell_path
+        if executable is None and os.name == "nt":
+            # Prefer Git Bash to Windows' WSL launcher: the tool must execute
+            # Bash commands against the same Windows working directory.
+            candidates: list[Path] = []
+            git = shutil.which("git")
+            if git:
+                candidates.append(Path(git).resolve().parent.parent / "bin" / "bash.exe")
+            for variable in ("ProgramFiles", "ProgramFiles(x86)", "LOCALAPPDATA"):
+                base = os.environ.get(variable)
+                if base:
+                    candidates.append(Path(base) / "Git" / "bin" / "bash.exe")
+            executable = next((str(path) for path in candidates if path.is_file()), None)
+            if executable is None:
+                raise FileNotFoundError("Git Bash is required on Windows. Install Git Bash or set shell_path.")
+        return [executable or find_executable("bash"), "-c", command]
+
+    async def execute(
+        self,
+        tool_call_id: str,
+        arguments: dict[str, JsonValue],
+    ) -> ToolExecutionResult:
+        args = ShellArguments.model_validate(arguments)
+        script_path: Path | None = None
+        output_path: Path | None = None
+        keep_output = False
+        try:
+            if self.name == "powershell":
+                with tempfile.NamedTemporaryFile(
+                    prefix="citrus-code-powershell-", suffix=".ps1",
+                    mode="w", encoding="utf-8", newline="\n", delete=False,
+                ) as script:
+                    script_path = Path(script.name)
+                    script.write(args.command)
+                    # Capture status inside the same script block as the final
+                    # user command; invoking a block can reset $? in PowerShell.
+                    script.write(
+                        "\nif (-not $?) { "
+                        "if ($LASTEXITCODE -is [int] -and $LASTEXITCODE -ne 0) { exit $LASTEXITCODE }; "
+                        "exit 1 }; exit 0\n"
+                    )
+            command = self._command(args.command, script_path)
+            # A file sink bounds memory and avoids inherited pipe handles keeping
+            # a completed foreground shell blocked on stdout/stderr drainage.
+            with tempfile.NamedTemporaryFile(
+                prefix=f"citrus-code-{self.name}-", suffix=".log", delete=False
+            ) as output:
+                output_path = Path(output.name)
+                process = await spawn_process(
+                    command, self._cwd, merge_stderr=True, output=output.file
+                )
+                timed_out = False
+                try:
+                    if args.timeout is None:
+                        code = await process.wait()
+                    else:
+                        code = await asyncio.wait_for(process.wait(), args.timeout)
+                except TimeoutError:
+                    timed_out = True
+                    await stop_process(process)
+                    code = await process.wait()
+                except BaseException:
+                    await stop_process(process)
+                    await process.wait()
+                    raise
+
+            format_task = asyncio.create_task(asyncio.to_thread(self._format_output, output_path))
+            try:
+                text, details = await asyncio.shield(format_task)
+            except asyncio.CancelledError:
+                # Do not remove an output file still being read by the worker.
+                await format_task
+                raise
+            keep_output = "fullOutputPath" in details
+            if timed_out:
+                raise RuntimeError(
+                    f"{text}\n\nCommand timed out after {args.timeout} seconds"
+                    f"\nShell: {command[0]}"
+                )
+            if code != 0:
+                raise RuntimeError(f"{text}\n\nCommand exited with code {code}\nShell: {command[0]}")
+            details["exit_code"] = code
+            details["shell"] = command[0]
+            return ToolExecutionResult(content=[TextContent(text=text)], details=details)
+        finally:
+            if script_path is not None:
+                script_path.unlink(missing_ok=True)
+            if output_path is not None and not keep_output:
+                output_path.unlink(missing_ok=True)
+
+    def _format_output(self, path: Path) -> tuple[str, dict[str, JsonValue]]:
+        total_bytes = 0
+        newline_count = 0
+        last_byte = b""
+        suffix = bytearray()
+        with path.open("rb") as file:
+            while chunk := file.read(64 * 1024):
+                total_bytes += len(chunk)
+                newline_count += chunk.count(b"\n")
+                last_byte = chunk[-1:]
+                suffix.extend(chunk)
+                if len(suffix) > DEFAULT_MAX_BYTES:
+                    del suffix[:-DEFAULT_MAX_BYTES]
+
+        byte_clipped = total_bytes > len(suffix)
+        partial_line = False
+        if byte_clipped:
+            first_break = suffix.find(b"\n")
+            if 0 <= first_break < len(suffix) - 1:
+                del suffix[:first_break + 1]
+            else:
+                partial_line = True
+        # Ignore only an incomplete leading UTF-8 code point introduced by clipping.
+        while suffix and byte_clipped and suffix[0] & 0xC0 == 0x80:
+            del suffix[0]
+        tail = bytes(suffix).decode("utf-8", errors="replace")
+        truncation = truncate_text(tail, tail=True)
+        truncation.total_bytes = total_bytes
+        truncation.total_lines = newline_count + int(total_bytes > 0 and last_byte != b"\n")
+        if byte_clipped:
+            truncation.truncated = True
+            if truncation.truncated_by is None:
+                truncation.truncated_by = "bytes"
+            truncation.last_line_partial = partial_line
+
+        text = truncation.content or "(no output)"
+        details: dict[str, JsonValue] = {}
+        if truncation.truncated:
+            details["truncation"] = truncation.model_dump(mode="json", exclude={"content"})
+            details["fullOutputPath"] = str(path)
+            text += (
+                f"\n\n[Showing the last {truncation.output_lines} lines "
+                f"({truncation.output_bytes} bytes); limits: {DEFAULT_MAX_LINES} lines / "
+                f"{DEFAULT_MAX_BYTES} bytes. Full output: {path}]"
+            )
+        return text, details

citrus_code/coding/tools/truncate.py

@@ -0,0 +1,87 @@
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict
+
+
+DEFAULT_MAX_LINES = 2000
+DEFAULT_MAX_BYTES = 50 * 1024
+GREP_MAX_LINE_LENGTH = 500
+
+
+class TruncationResult(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    content: str
+    truncated: bool
+    truncated_by: Literal["lines", "bytes"] | None
+    total_lines: int
+    total_bytes: int
+    output_lines: int
+    output_bytes: int
+    first_line_exceeds_limit: bool = False
+    last_line_partial: bool = False
+
+
+def truncate_text(
+    content: str,
+    *,
+    tail: bool = False,
+    max_lines: int = DEFAULT_MAX_LINES,
+    max_bytes: int = DEFAULT_MAX_BYTES,
+) -> TruncationResult:
+    """Keep complete lines, with a UTF-8-safe partial last line for shell tails."""
+    if max_lines < 1 or max_bytes < 1:
+        raise ValueError("Output limits must be positive")
+
+    lines = content.split("\n") if content else []
+    if content.endswith("\n"):
+        lines.pop()
+    total_bytes = len(content.encode("utf-8"))
+    if len(lines) <= max_lines and total_bytes <= max_bytes:
+        return TruncationResult(
+            content=content,
+            truncated=False,
+            truncated_by=None,
+            total_lines=len(lines),
+            total_bytes=total_bytes,
+            output_lines=len(lines),
+            output_bytes=total_bytes,
+        )
+
+    selected: list[str] = []
+    size = 0
+    reason: Literal["lines", "bytes"] = "lines"
+    partial = False
+    first_too_large = False
+    candidates = reversed(lines) if tail else iter(lines)
+    for line in candidates:
+        if len(selected) >= max_lines:
+            break
+        line_bytes = line.encode("utf-8")
+        cost = len(line_bytes) + (1 if selected else 0)
+        if size + cost > max_bytes:
+            reason = "bytes"
+            if not selected:
+                if tail:
+                    selected.append(line_bytes[-max_bytes:].decode("utf-8", errors="ignore"))
+                    partial = True
+                else:
+                    first_too_large = True
+            break
+        selected.append(line)
+        size += cost
+
+    if tail:
+        selected.reverse()
+    output = "\n".join(selected)
+    return TruncationResult(
+        content=output,
+        truncated=True,
+        truncated_by=reason,
+        total_lines=len(lines),
+        total_bytes=total_bytes,
+        output_lines=len(selected),
+        output_bytes=len(output.encode("utf-8")),
+        first_line_exceeds_limit=first_too_large,
+        last_line_partial=partial,
+    )

citrus_code/coding/tools/write.py

@@ -0,0 +1,94 @@
+import asyncio
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field, JsonValue
+
+from ...agent.types import ToolExecutionResult
+from ...ai.types import TextContent, ToolDefinition
+from .mutation import file_mutation
+from .paths import resolve_to_cwd
+
+
+class WriteArguments(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        strict=True,
+    )
+
+    path: str = Field(
+        min_length=1,
+        description=(
+            "The file path, absolute or relative "
+            "to the working directory."
+        ),
+    )
+
+    content: str = Field(
+        description="The complete text content to write.",
+    )
+
+
+class WriteTool:
+    name: str = "write"
+
+    description: str = (
+        "Write UTF-8 text to a file. "
+        "Creates the file if it does not exist, "
+        "overwrites it if it does, "
+        "and automatically creates parent directories. "
+        "Use this tool for new files or complete rewrites."
+    )
+
+    def __init__(self, cwd: Path) -> None:
+        self._cwd = cwd.resolve()
+
+    def get_definition(self) -> ToolDefinition:
+        return ToolDefinition(
+            name=self.name,
+            description=self.description,
+            parameters=WriteArguments.model_json_schema(),
+        )
+
+    async def execute(
+        self,
+        tool_call_id: str,
+        arguments: dict[str, JsonValue],
+    ) -> ToolExecutionResult:
+        args = WriteArguments.model_validate(arguments)
+
+        path = resolve_to_cwd(args.path, self._cwd)
+
+        return await asyncio.to_thread(
+            self._write,
+            path,
+            args,
+        )
+
+    def _write(
+        self,
+        path: Path,
+        args: WriteArguments,
+    ) -> ToolExecutionResult:
+        with file_mutation(path):
+            path.parent.mkdir(parents=True, exist_ok=True)
+            characters_written = path.write_text(
+                args.content,
+                encoding="utf-8",
+                newline="",
+            )
+
+        return ToolExecutionResult(
+            content=[
+                TextContent(
+                    text=(
+                        f"Successfully wrote "
+                        f"{characters_written} characters "
+                        f"to {args.path}."
+                    )
+                )
+            ],
+            details={
+                "path": str(path),
+                "characters_written": characters_written,
+            },
+        )

citrus_code/config.py

@@ -0,0 +1,34 @@
+import os
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr
+
+
+class ModelConnectionConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    provider_id: str = Field(min_length=1)
+    model_id: str = Field(min_length=1)
+    base_url: str = Field(min_length=1)
+    api_key: SecretStr
+
+
+def load_connection_config() -> ModelConnectionConfig:
+    api_key = os.getenv("DEEPSEEK_API_KEY")
+
+    if api_key is None or not api_key.strip():
+        raise ValueError(
+            "Please set the DEEPSEEK_API_KEY environment variable"
+        )
+
+    return ModelConnectionConfig(
+        provider_id="deepseek",
+        model_id=os.getenv(
+            "CITRUS_CODE_MODEL",
+            "deepseek-flash",
+        ),
+        base_url=os.getenv(
+            "CITRUS_CODE_BASE_URL",
+            "https://api.deepseek.com",
+        ),
+        api_key=SecretStr(api_key),
+    )