pythinker-code 2.0.0__py3-none-any.whl

pythinker_code/tools/background/__init__.py

@@ -0,0 +1,318 @@
+import time
+from pathlib import Path
+from typing import override
+
+from pydantic import BaseModel, Field
+from pythinker_core.tooling import CallableTool2, ToolError, ToolReturnValue
+
+from pythinker_code.background import TaskView, format_task, format_task_list, list_task_views
+from pythinker_code.soul.agent import Runtime
+from pythinker_code.soul.approval import Approval
+from pythinker_code.tools.display import BackgroundTaskDisplayBlock
+from pythinker_code.tools.utils import load_desc
+
+TASK_OUTPUT_PREVIEW_BYTES = 32 << 10
+TASK_OUTPUT_READ_HINT_LINES = 300
+
+
+def _ensure_root(runtime: Runtime) -> ToolError | None:
+    if runtime.role != "root":
+        return ToolError(
+            message="Background tasks can only be managed by the root agent.",
+            brief="Background task unavailable",
+        )
+    return None
+
+
+def _task_display(runtime: Runtime, task_id: str) -> BackgroundTaskDisplayBlock:
+    view = runtime.background_tasks.store.merged_view(task_id)
+    return BackgroundTaskDisplayBlock(
+        task_id=view.spec.id,
+        kind=view.spec.kind,
+        status=view.runtime.status,
+        description=view.spec.description,
+    )
+
+
+def _format_task_output(
+    view: TaskView,
+    *,
+    retrieval_status: str,
+    output: str,
+    output_path: Path,
+    full_output_available: bool,
+    output_size_bytes: int,
+    output_preview_bytes: int,
+    output_truncated: bool,
+) -> str:
+    terminal_reason = "timed_out" if view.runtime.timed_out else view.runtime.status
+    output_path_str = str(output_path.resolve())
+    lines = [
+        f"retrieval_status: {retrieval_status}",
+        f"task_id: {view.spec.id}",
+        f"kind: {view.spec.kind}",
+        f"status: {view.runtime.status}",
+        f"description: {view.spec.description}",
+    ]
+    if view.spec.kind == "agent" and view.spec.kind_payload:
+        if agent_id := view.spec.kind_payload.get("agent_id"):
+            lines.append(f"agent_id: {agent_id}")
+        if subagent_type := view.spec.kind_payload.get("subagent_type"):
+            lines.append(f"subagent_type: {subagent_type}")
+    if view.spec.command:
+        lines.append(f"command: {view.spec.command}")
+    lines.extend(
+        [
+            f"interrupted: {str(view.runtime.interrupted).lower()}",
+            f"timed_out: {str(view.runtime.timed_out).lower()}",
+            f"terminal_reason: {terminal_reason}",
+        ]
+    )
+    if view.runtime.exit_code is not None:
+        lines.append(f"exit_code: {view.runtime.exit_code}")
+    if view.runtime.failure_reason:
+        lines.append(f"reason: {view.runtime.failure_reason}")
+    full_output_hint = (
+        (
+            "full_output_hint: "
+            f'Use ReadFile(path="{output_path_str}", line_offset=1, '
+            f"n_lines={TASK_OUTPUT_READ_HINT_LINES}) to inspect the full log. "
+            "Increase line_offset to continue paging through the file."
+        )
+        if full_output_available
+        else "full_output_hint: No output file is currently available for this task."
+    )
+    lines.extend(
+        [
+            "",
+            f"output_path: {output_path_str}",
+            f"output_size_bytes: {output_size_bytes}",
+            f"output_preview_bytes: {output_preview_bytes}",
+            f"output_truncated: {str(output_truncated).lower()}",
+            "",
+            f"full_output_available: {str(full_output_available).lower()}",
+            "full_output_tool: ReadFile",
+            full_output_hint,
+        ]
+    )
+    rendered_output = output or "[no output available]"
+    if output_truncated:
+        rendered_output = f"[Truncated. Full output: {output_path_str}]\n\n{rendered_output}"
+    return "\n".join(
+        lines
+        + [
+            "",
+            "[output]",
+            rendered_output,
+        ]
+    )
+
+
+class TaskOutputParams(BaseModel):
+    task_id: str = Field(description="The background task ID to inspect.")
+    block: bool = Field(
+        default=False,
+        description="Whether to wait for the task to finish before returning.",
+    )
+    timeout: int = Field(
+        default=30,
+        ge=0,
+        le=3600,
+        description="Maximum number of seconds to wait when block=true.",
+    )
+
+
+class TaskStopParams(BaseModel):
+    task_id: str = Field(description="The background task ID to stop.")
+    reason: str = Field(
+        default="Stopped by TaskStop",
+        description="Short reason recorded when the task is stopped.",
+    )
+
+
+class TaskListParams(BaseModel):
+    active_only: bool = Field(
+        default=True,
+        description="Whether to list only non-terminal background tasks.",
+    )
+    limit: int = Field(
+        default=20,
+        ge=1,
+        le=100,
+        description="Maximum number of tasks to return.",
+    )
+
+
+class TaskList(CallableTool2[TaskListParams]):
+    name: str = "TaskList"
+    description: str = load_desc(Path(__file__).parent / "list.md")
+    params: type[TaskListParams] = TaskListParams
+
+    def __init__(self, runtime: Runtime):
+        super().__init__()
+        self._runtime = runtime
+
+    @override
+    async def __call__(self, params: TaskListParams) -> ToolReturnValue:
+        if err := _ensure_root(self._runtime):
+            return err
+
+        views = list_task_views(
+            self._runtime.background_tasks,
+            active_only=params.active_only,
+            limit=params.limit,
+        )
+        display = [
+            BackgroundTaskDisplayBlock(
+                task_id=view.spec.id,
+                kind=view.spec.kind,
+                status=view.runtime.status,
+                description=view.spec.description,
+            )
+            for view in views
+        ]
+        return ToolReturnValue(
+            is_error=False,
+            output=format_task_list(views, active_only=params.active_only),
+            message="Task list retrieved.",
+            display=list(display),
+        )
+
+
+class TaskOutput(CallableTool2[TaskOutputParams]):
+    name: str = "TaskOutput"
+    description: str = load_desc(Path(__file__).parent / "output.md")
+    params: type[TaskOutputParams] = TaskOutputParams
+
+    def __init__(self, runtime: Runtime):
+        super().__init__()
+        self._runtime = runtime
+
+    def _render_output_preview(self, task_id: str) -> tuple[str, bool, int, int, bool, Path]:
+        manager = self._runtime.background_tasks
+        output_path = manager.resolve_output_path(task_id)
+        try:
+            output_size = output_path.stat().st_size if output_path.exists() else 0
+        except OSError:
+            output_size = 0
+        preview_offset = max(0, output_size - TASK_OUTPUT_PREVIEW_BYTES)
+        chunk = manager.read_output(
+            task_id,
+            offset=preview_offset,
+            max_bytes=TASK_OUTPUT_PREVIEW_BYTES,
+        )
+        return (
+            chunk.text.rstrip("\n"),
+            output_size > 0,
+            output_size,
+            chunk.next_offset - chunk.offset,
+            preview_offset > 0,
+            output_path,
+        )
+
+    @override
+    async def __call__(self, params: TaskOutputParams) -> ToolReturnValue:
+        if err := _ensure_root(self._runtime):
+            return err
+
+        view = self._runtime.background_tasks.get_task(params.task_id)
+        if view is None:
+            return ToolError(message=f"Task not found: {params.task_id}", brief="Task not found")
+
+        if params.block:
+            view = await self._runtime.background_tasks.wait(
+                params.task_id,
+                timeout_s=params.timeout,
+            )
+            retrieval_status = (
+                "success"
+                if view.runtime.status in {"completed", "failed", "killed", "lost"}
+                else "timeout"
+            )
+        else:
+            retrieval_status = (
+                "success"
+                if view.runtime.status in {"completed", "failed", "killed", "lost"}
+                else "not_ready"
+            )
+
+        (
+            output,
+            full_output_available,
+            output_size,
+            output_preview_bytes,
+            output_truncated,
+            output_path,
+        ) = self._render_output_preview(params.task_id)
+        consumer = view.consumer.model_copy(
+            update={
+                "last_seen_output_size": output_size,
+                "last_viewed_at": time.time(),
+            }
+        )
+        self._runtime.background_tasks.store.write_consumer(params.task_id, consumer)
+
+        return ToolReturnValue(
+            is_error=False,
+            output=_format_task_output(
+                view,
+                retrieval_status=retrieval_status,
+                output=output,
+                output_path=output_path,
+                full_output_available=full_output_available,
+                output_size_bytes=output_size,
+                output_preview_bytes=output_preview_bytes,
+                output_truncated=output_truncated,
+            ),
+            message=(
+                "Task snapshot retrieved."
+                if not params.block and retrieval_status == "not_ready"
+                else "Task output retrieved."
+            ),
+            display=[_task_display(self._runtime, params.task_id)],
+        )
+
+
+class TaskStop(CallableTool2[TaskStopParams]):
+    name: str = "TaskStop"
+    description: str = load_desc(Path(__file__).parent / "stop.md")
+    params: type[TaskStopParams] = TaskStopParams
+
+    def __init__(self, runtime: Runtime, approval: Approval):
+        super().__init__()
+        self._runtime = runtime
+        self._approval = approval
+
+    @override
+    async def __call__(self, params: TaskStopParams) -> ToolReturnValue:
+        if err := _ensure_root(self._runtime):
+            return err
+        if self._runtime.session.state.plan_mode:
+            return ToolError(
+                message="TaskStop is not available in plan mode.",
+                brief="Blocked in plan mode",
+            )
+
+        view = self._runtime.background_tasks.get_task(params.task_id)
+        if view is None:
+            return ToolError(message=f"Task not found: {params.task_id}", brief="Task not found")
+
+        result = await self._approval.request(
+            self.name,
+            "stop background task",
+            f"Stop background task `{params.task_id}`",
+            display=[_task_display(self._runtime, params.task_id)],
+        )
+        if not result:
+            return result.rejection_error()
+
+        view = self._runtime.background_tasks.kill(
+            params.task_id,
+            reason=params.reason.strip() or "Stopped by TaskStop",
+        )
+        return ToolReturnValue(
+            is_error=False,
+            output=format_task(view, include_command=True),
+            message="Task stop requested.",
+            display=[_task_display(self._runtime, params.task_id)],
+        )

pythinker_code/tools/background/list.md

@@ -0,0 +1,10 @@
+List background tasks from the current session.
+
+Use this when you need to re-enumerate which background tasks still exist, especially after context compaction or when you are no longer confident which task IDs are still active.
+
+Guidelines:
+
+- Prefer the default `active_only=true` unless you specifically need completed or failed tasks.
+- Use `TaskOutput` to inspect one task in detail after you have identified the correct task ID.
+- Do not guess which tasks are still running when you can call this tool directly.
+- This tool is read-only and safe to use in plan mode.

pythinker_code/tools/background/output.md

@@ -0,0 +1,11 @@
+Retrieve output from a running or completed background task.
+
+Use this after `Shell(run_in_background=true)` when you need to inspect progress or explicitly wait for completion.
+
+Guidelines:
+- Prefer relying on automatic completion notifications. Use this tool only when you need task output before the automatic notification arrives.
+- By default this tool is non-blocking and returns a current status/output snapshot.
+- Use `block=true` only when you intentionally want to wait for completion or timeout.
+- This tool returns structured task metadata, a fixed-size output preview, and an `output_path` for the full log.
+- When the preview is truncated, use `ReadFile` with the returned `output_path` to inspect the full log in pages.
+- This tool works with the generic background task system and should remain the primary read path for future task types, not just bash.

pythinker_code/tools/background/stop.md

@@ -0,0 +1,8 @@
+Stop a running background task.
+
+Use this only when a background task must be cancelled. For normal task completion, prefer waiting for the automatic notification or using `TaskOutput`.
+
+Guidelines:
+- This is a generic task stop capability, not a bash-specific kill tool.
+- Use it sparingly because stopping a task is destructive and may leave partial side effects.
+- If the task is already complete, this tool will simply return its current state.

pythinker_code/tools/display.py

@@ -0,0 +1,46 @@
+from typing import Literal
+
+from pydantic import BaseModel
+from pythinker_core.tooling import DisplayBlock
+
+
+class DiffDisplayBlock(DisplayBlock):
+    """Display block describing a file diff."""
+
+    type: str = "diff"
+    path: str
+    old_text: str
+    new_text: str
+    old_start: int = 1
+    new_start: int = 1
+    is_summary: bool = False
+
+
+class TodoDisplayItem(BaseModel):
+    title: str
+    status: Literal["pending", "in_progress", "done"]
+
+
+class TodoDisplayBlock(DisplayBlock):
+    """Display block describing a todo list update."""
+
+    type: str = "todo"
+    items: list[TodoDisplayItem]
+
+
+class ShellDisplayBlock(DisplayBlock):
+    """Display block describing a shell command."""
+
+    type: str = "shell"
+    language: str
+    command: str
+
+
+class BackgroundTaskDisplayBlock(DisplayBlock):
+    """Display block describing a background task."""
+
+    type: str = "background_task"
+    task_id: str
+    kind: str
+    status: str
+    description: str

pythinker_code/tools/dmail/__init__.py

@@ -0,0 +1,38 @@
+from pathlib import Path
+from typing import override
+
+from pythinker_core.tooling import CallableTool2, ToolError, ToolOk, ToolReturnValue
+
+from pythinker_code.soul.denwarenji import DenwaRenji, DenwaRenjiError, DMail
+from pythinker_code.tools.utils import load_desc
+
+NAME = "SendDMail"
+
+
+class SendDMail(CallableTool2[DMail]):
+    name: str = NAME
+    description: str = load_desc(Path(__file__).parent / "dmail.md")
+    params: type[DMail] = DMail
+
+    def __init__(self, denwa_renji: DenwaRenji) -> None:
+        super().__init__()
+        self._denwa_renji = denwa_renji
+
+    @override
+    async def __call__(self, params: DMail) -> ToolReturnValue:
+        try:
+            self._denwa_renji.send_dmail(params)
+        except DenwaRenjiError as e:
+            return ToolError(
+                output="",
+                message=f"Failed to send D-Mail. Error: {str(e)}",
+                brief="Failed to send D-Mail",
+            )
+        return ToolOk(
+            output="",
+            message=(
+                "If you see this message, the D-Mail was NOT sent successfully. "
+                "This may be because some other tool that needs approval was rejected."
+            ),
+            brief="El Psy Kongroo",
+        )

pythinker_code/tools/dmail/dmail.md

@@ -0,0 +1,17 @@
+Send a message to the past, just like sending a D-Mail in Steins;Gate.
+
+This tool is provided to enable you to proactively manage the context. You can see some `user` messages with text `CHECKPOINT {checkpoint_id}` wrapped in `<system>` tags in the context. When you feel there is too much irrelevant information in the current context, you can send a D-Mail to revert the context to a previous checkpoint with a message containing only the useful information. When you send a D-Mail, you must specify an existing checkpoint ID from the before-mentioned messages.
+
+Typical scenarios you may want to send a D-Mail:
+
+- You read a file, found it very large and most of the content is not relevant to the current task. In this case you can send a D-Mail immediately to the checkpoint before you read the file and give your past self only the useful part.
+- You searched the web, the result is large.
+  - If you got what you need, you may send a D-Mail to the checkpoint before you searched the web and put only the useful result in the mail message.
+  - If you did not get what you need, you may send a D-Mail to tell your past self to try another query.
+- You wrote some code and it did not work as expected. You spent many struggling steps to fix it but the process is not relevant to the ultimate goal. In this case you can send a D-Mail to the checkpoint before you wrote the code and give your past self the fixed version of the code and tell yourself no need to write it again because you already wrote to the filesystem.
+
+After a D-Mail is sent, the system will revert the current context to the specified checkpoint, after which, you will no longer see any messages which you can now see after that checkpoint. The message in the D-Mail will be appended to the end of the context. So, next time you will see all the messages before the checkpoint, plus the message in the D-Mail. You must make it very clear in the message, tell your past self what you have done/changed, what you have learned and any other information that may be useful, so that your past self can continue the task without confusion and will not repeat the steps you have already done.
+
+You must understand that, unlike D-Mail in Steins;Gate, the D-Mail you send here will not revert the filesystem or any external state. That means, you are basically folding the recent messages in your context into a single message, which can significantly reduce the waste of context window.
+
+When sending a D-Mail, DO NOT explain to the user. The user do not care about this. Just explain to your past self.

pythinker_code/tools/file/__init__.py

@@ -0,0 +1,30 @@
+from enum import StrEnum
+
+
+class FileOpsWindow:
+    """Maintains a window of file operations."""
+
+    pass
+
+
+class FileActions(StrEnum):
+    READ = "read file"
+    EDIT = "edit file"
+    EDIT_OUTSIDE = "edit file outside of working directory"
+
+
+from .glob import Glob  # noqa: E402
+from .grep_local import Grep  # noqa: E402
+from .read import ReadFile  # noqa: E402
+from .read_media import ReadMediaFile  # noqa: E402
+from .replace import StrReplaceFile  # noqa: E402
+from .write import WriteFile  # noqa: E402
+
+__all__ = (
+    "ReadFile",
+    "ReadMediaFile",
+    "Glob",
+    "Grep",
+    "WriteFile",
+    "StrReplaceFile",
+)

pythinker_code/tools/file/glob.md

@@ -0,0 +1,17 @@
+Find files and directories using glob patterns. This tool supports standard glob syntax like `*`, `?`, and `**` for recursive searches.
+
+**When to use:**
+- Find files matching specific patterns (e.g., all Python files: `*.py`)
+- Search for files recursively in subdirectories (e.g., `src/**/*.js`)
+- Locate configuration files (e.g., `*.config.*`, `*.json`)
+- Find test files (e.g., `test_*.py`, `*_test.go`)
+
+**Example patterns:**
+- `*.py` - All Python files in current directory
+- `src/**/*.js` - All JavaScript files in src directory recursively
+- `test_*.py` - Python test files starting with "test_"
+- `*.config.{js,ts}` - Config files with .js or .ts extension
+
+**Bad example patterns:**
+- `**`, `**/*.py` - Any pattern starting with '**' will be rejected. Because it would recursively search all directories and subdirectories, which is very likely to yield large result that exceeds your context size. Always use more specific patterns like `src/**/*.py` instead.
+- `node_modules/**/*.js` - Although this does not start with '**', it would still highly possible to yield large result because `node_modules` is well-known to contain too many directories and files. Avoid recursively searching in such directories, other examples include `venv`, `.venv`, `__pycache__`, `target`. If you really need to search in a dependency, use more specific patterns like `node_modules/react/src/*` instead.

pythinker_code/tools/file/glob.py

@@ -0,0 +1,160 @@
+"""Glob tool implementation."""
+
+from pathlib import Path
+from typing import override
+
+from pydantic import BaseModel, Field
+from pythinker_core.tooling import CallableTool2, ToolError, ToolOk, ToolReturnValue
+from pythinker_host.path import HostPath
+
+from pythinker_code.soul.agent import Runtime
+from pythinker_code.tools.utils import load_desc
+from pythinker_code.utils.logging import logger
+from pythinker_code.utils.path import is_within_directory, is_within_workspace, list_directory
+
+MAX_MATCHES = 1000
+
+
+class Params(BaseModel):
+    pattern: str = Field(description=("Glob pattern to match files/directories."))
+    directory: str | None = Field(
+        description=(
+            "Absolute path to the directory to search in (defaults to working directory)."
+        ),
+        default=None,
+    )
+    include_dirs: bool = Field(
+        description="Whether to include directories in results.",
+        default=True,
+    )
+
+
+class Glob(CallableTool2[Params]):
+    name: str = "Glob"
+    description: str = load_desc(
+        Path(__file__).parent / "glob.md",
+        {
+            "MAX_MATCHES": str(MAX_MATCHES),
+        },
+    )
+    params: type[Params] = Params
+
+    def __init__(self, runtime: Runtime) -> None:
+        super().__init__()
+        self._work_dir = runtime.builtin_args.PYTHINKER_WORK_DIR
+        self._additional_dirs = runtime.additional_dirs
+        self._skills_dirs = runtime.skills_dirs
+
+    async def _validate_pattern(self, pattern: str) -> ToolError | None:
+        """Validate that the pattern is safe to use."""
+        if pattern.startswith("**"):
+            ls_result = await list_directory(self._work_dir)
+            return ToolError(
+                output=ls_result,
+                message=(
+                    f"Pattern `{pattern}` starts with '**' which is not allowed. "
+                    "This would recursively search all directories and may include large "
+                    "directories like `node_modules`. Use more specific patterns instead. "
+                    "For your convenience, a list of all files and directories in the "
+                    "top level of the working directory is provided below."
+                ),
+                brief="Unsafe pattern",
+            )
+        return None
+
+    async def _validate_directory(self, directory: HostPath) -> ToolError | None:
+        """Validate that the directory is safe to search."""
+        resolved_dir = directory.canonical()
+
+        # Allow directories within the workspace (work_dir or additional dirs)
+        if is_within_workspace(resolved_dir, self._work_dir, self._additional_dirs):
+            return None
+
+        # Allow directories within any discovered skills root
+        if any(is_within_directory(resolved_dir, d) for d in self._skills_dirs):
+            return None
+
+        return ToolError(
+            message=(
+                f"`{directory}` is outside the workspace. "
+                "You can only search within the working directory, "
+                "additional directories, and skills directories."
+            ),
+            brief="Directory outside workspace",
+        )
+
+    @override
+    async def __call__(self, params: Params) -> ToolReturnValue:
+        try:
+            # Validate pattern safety
+            pattern_error = await self._validate_pattern(params.pattern)
+            if pattern_error:
+                return pattern_error
+
+            dir_path = (
+                HostPath(params.directory).expanduser() if params.directory else self._work_dir
+            )
+
+            if not dir_path.is_absolute():
+                return ToolError(
+                    message=(
+                        f"`{params.directory}` is not an absolute path. "
+                        "You must provide an absolute path to search."
+                    ),
+                    brief="Invalid directory",
+                )
+
+            # Validate directory safety
+            dir_error = await self._validate_directory(dir_path)
+            if dir_error:
+                return dir_error
+
+            if not await dir_path.exists():
+                return ToolError(
+                    message=f"`{params.directory}` does not exist.",
+                    brief="Directory not found",
+                )
+            if not await dir_path.is_dir():
+                return ToolError(
+                    message=f"`{params.directory}` is not a directory.",
+                    brief="Invalid directory",
+                )
+
+            # Perform the glob search - users can use ** directly in pattern
+            matches: list[HostPath] = []
+            async for match in dir_path.glob(params.pattern):
+                matches.append(match)
+
+            # Filter out directories if not requested
+            if not params.include_dirs:
+                matches = [p for p in matches if await p.is_file()]
+
+            # Sort for consistent output
+            matches.sort()
+
+            # Limit matches
+            message = (
+                f"Found {len(matches)} matches for pattern `{params.pattern}`."
+                if len(matches) > 0
+                else f"No matches found for pattern `{params.pattern}`."
+            )
+            if len(matches) > MAX_MATCHES:
+                matches = matches[:MAX_MATCHES]
+                message += (
+                    f" Only the first {MAX_MATCHES} matches are returned. "
+                    "You may want to use a more specific pattern."
+                )
+
+            return ToolOk(
+                output="\n".join(str(p.relative_to(dir_path)) for p in matches),
+                message=message,
+            )
+
+        except Exception as e:
+            logger.warning(
+                "Glob failed: pattern={pattern}: {error}", pattern=params.pattern, error=e
+            )
+            return ToolError(
+                message=f"Failed to search for pattern {params.pattern}. Error: {e}",
+                brief="Glob failed",
+            )

pythinker_code/tools/file/grep.md

@@ -0,0 +1,6 @@
+A powerful search tool based-on ripgrep.
+
+**Tips:**
+- ALWAYS use Grep tool instead of running `grep` or `rg` command with Shell tool.
+- Use the ripgrep pattern syntax, not grep syntax. E.g. you need to escape braces like `\\{` to search for `{`.
+- Hidden files (dotfiles like `.gitlab-ci.yml`, `.eslintrc.json`) are always searched. To also search files excluded by `.gitignore` (e.g. `node_modules`, build outputs), set `include_ignored` to `true`. Sensitive files (such as `.env`) are still skipped for safety, even when `include_ignored` is `true`.