pythinker-code 2.0.0__py3-none-any.whl

pythinker_code/tools/plan/heroes.py

@@ -0,0 +1,277 @@
+"""Plan file slug generation using Marvel and DC hero names."""
+
+from __future__ import annotations
+
+import secrets
+from pathlib import Path
+
+PLANS_DIR = Path.home() / ".pythinker" / "plans"
+
+HERO_NAMES: list[str] = [
+    # --- Marvel ---
+    "iron-man",
+    "spider-man",
+    "captain-america",
+    "thor",
+    "hulk",
+    "black-widow",
+    "hawkeye",
+    "black-panther",
+    "doctor-strange",
+    "scarlet-witch",
+    "vision",
+    "falcon",
+    "war-machine",
+    "ant-man",
+    "wasp",
+    "captain-marvel",
+    "gamora",
+    "star-lord",
+    "groot",
+    "rocket",
+    "drax",
+    "mantis",
+    "nebula",
+    "shang-chi",
+    "moon-knight",
+    "ms-marvel",
+    "she-hulk",
+    "echo",
+    "wolverine",
+    "cyclops",
+    "storm",
+    "jean-grey",
+    "rogue",
+    "beast",
+    "nightcrawler",
+    "colossus",
+    "shadowcat",
+    "jubilee",
+    "cable",
+    "deadpool",
+    "bishop",
+    "magik",
+    "iceman",
+    "archangel",
+    "psylocke",
+    "dazzler",
+    "forge",
+    "havok",
+    "polaris",
+    "emma-frost",
+    "namor",
+    "silver-surfer",
+    "adam-warlock",
+    "nova",
+    "quasar",
+    "sentry",
+    "blue-marvel",
+    "spectrum",
+    "squirrel-girl",
+    "cloak",
+    "dagger",
+    "punisher",
+    "elektra",
+    "luke-cage",
+    "iron-fist",
+    "jessica-jones",
+    "daredevil",
+    "blade",
+    "ghost-rider",
+    "morbius",
+    "venom",
+    "carnage",
+    "silk",
+    "spider-gwen",
+    "miles-morales",
+    "america-chavez",
+    "kate-bishop",
+    "yelena-belova",
+    "white-tiger",
+    "moon-girl",
+    "devil-dinosaur",
+    "amadeus-cho",
+    "riri-williams",
+    "kamala-khan",
+    "sam-alexander",
+    "nova-prime",
+    "medusa",
+    "black-bolt",
+    "crystal",
+    "karnak",
+    "gorgon",
+    "lockjaw",
+    "quake",
+    "mockingbird",
+    "bobbi-morse",
+    "maria-hill",
+    "nick-fury",
+    "phil-coulson",
+    "winter-soldier",
+    "us-agent",
+    "patriot",
+    "speed",
+    "wiccan",
+    "hulkling",
+    "stature",
+    "yellowjacket",
+    "tigra",
+    "hellcat",
+    "valkyrie",
+    "sif",
+    "beta-ray-bill",
+    "hercules",
+    "wonder-man",
+    "taskmaster",
+    "domino",
+    "cannonball",
+    "sunspot",
+    "wolfsbane",
+    "warpath",
+    "multiple-man",
+    "banshee",
+    "siryn",
+    "monet",
+    "rictor",
+    "shatterstar",
+    "longshot",
+    "daken",
+    "x-23",
+    "fantomex",
+    "batman",
+    "superman",
+    "wonder-woman",
+    "flash",
+    "aquaman",
+    "green-lantern",
+    "martian-manhunter",
+    "cyborg",
+    "hawkgirl",
+    "green-arrow",
+    "black-canary",
+    "zatanna",
+    "constantine",
+    "shazam",
+    "blue-beetle",
+    "booster-gold",
+    "firestorm",
+    "atom",
+    "hawkman",
+    "plastic-man",
+    "red-tornado",
+    "starfire",
+    "raven",
+    "beast-boy",
+    "robin",
+    "nightwing",
+    "batgirl",
+    "batwoman",
+    "red-hood",
+    "signal",
+    "orphan",
+    "spoiler",
+    "catwoman",
+    "huntress",
+    "supergirl",
+    "superboy",
+    "power-girl",
+    "steel",
+    "stargirl",
+    "wildcat",
+    "doctor-fate",
+    "mister-terrific",
+    "hourman",
+    "sandman",
+    "spectre",
+    "phantom-stranger",
+    "swamp-thing",
+    "animal-man",
+    "deadman",
+    "vixen",
+    "black-lightning",
+    "static",
+    "icon",
+    "rocket-dc",
+    "captain-atom",
+    "fire",
+    "ice",
+    "elongated-man",
+    "metamorpho",
+    "black-hawk",
+    "crimson-avenger",
+    "doctor-mid-nite",
+    "jakeem-thunder",
+    "mister-miracle",
+    "big-barda",
+    "orion",
+    "lightray",
+    "forager",
+    "killer-frost",
+    "jessica-cruz",
+    "simon-baz",
+    "john-stewart",
+    "guy-gardner",
+    "kyle-rayner",
+    "hal-jordan",
+    "wally-west",
+    "barry-allen",
+    "jay-garrick",
+    "impulse",
+    "kid-flash",
+    "donna-troy",
+    "tempest",
+    "aqualad",
+    "miss-martian",
+    "terra",
+    "jericho",
+    "ravager",
+    "red-star",
+    "pantha",
+    "argent",
+    "damage",
+    "jade",
+    "obsidian",
+    "cyclone",
+    "atom-smasher",
+    "maxima",
+    "starman",
+    "liberty-belle",
+]
+
+_slug_cache: dict[str, str] = {}
+
+
+def seed_slug_cache(session_id: str, slug: str) -> None:
+    """Pre-warm the in-process slug cache with a previously persisted slug."""
+    _slug_cache[session_id] = slug
+
+
+def get_or_create_slug(session_id: str) -> str:
+    """Get or create a plan file slug for the given session."""
+    if session_id in _slug_cache:
+        return _slug_cache[session_id]
+    PLANS_DIR.mkdir(parents=True, exist_ok=True)
+    slug = ""
+    for _ in range(20):
+        words = [secrets.choice(HERO_NAMES) for _ in range(3)]
+        slug = "-".join(words)
+        if not (PLANS_DIR / f"{slug}.md").exists():
+            break
+    else:
+        # All 20 attempts collided; append session prefix for uniqueness
+        slug = f"{slug}-{session_id[:8]}"
+    _slug_cache[session_id] = slug
+    return slug
+
+
+def get_plan_file_path(session_id: str) -> Path:
+    """Get the plan file path for the given session."""
+    return PLANS_DIR / f"{get_or_create_slug(session_id)}.md"
+
+
+def read_plan_file(session_id: str) -> str | None:
+    """Read the plan file content for the given session, or None if not found."""
+    path = get_plan_file_path(session_id)
+    if path.exists():
+        return path.read_text(encoding="utf-8", errors="replace")
+    return None

pythinker_code/tools/shell/__init__.py

@@ -0,0 +1,253 @@
+import asyncio
+from collections.abc import Callable
+from pathlib import Path
+from typing import Self, override
+
+import pythinker_host
+from pydantic import BaseModel, Field, model_validator
+from pythinker_core.tooling import CallableTool2, ToolReturnValue
+from pythinker_host import AsyncReadable
+
+from pythinker_code.background import TaskView, format_task
+from pythinker_code.soul.agent import Runtime
+from pythinker_code.soul.approval import Approval
+from pythinker_code.soul.toolset import get_current_tool_call_or_none
+from pythinker_code.tools.display import BackgroundTaskDisplayBlock, ShellDisplayBlock
+from pythinker_code.tools.utils import ToolResultBuilder, load_desc
+from pythinker_code.utils.environment import Environment
+from pythinker_code.utils.logging import logger
+from pythinker_code.utils.subprocess_env import get_noninteractive_env
+
+MAX_FOREGROUND_TIMEOUT = 5 * 60
+MAX_BACKGROUND_TIMEOUT = 24 * 60 * 60
+
+
+class Params(BaseModel):
+    command: str = Field(description="The command to execute.")
+    timeout: int = Field(
+        description=(
+            "The timeout in seconds for the command to execute. "
+            "If the command takes longer than this, it will be killed."
+        ),
+        default=60,
+        ge=1,
+        le=MAX_BACKGROUND_TIMEOUT,
+    )
+    run_in_background: bool = Field(
+        default=False,
+        description="Whether to run the command as a background task.",
+    )
+    description: str = Field(
+        default="",
+        description=(
+            "A short description for the background task. Required when run_in_background=true."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def _validate_background_fields(self) -> Self:
+        if self.run_in_background and not self.description.strip():
+            raise ValueError("description is required when run_in_background is true")
+        if not self.run_in_background and self.timeout > MAX_FOREGROUND_TIMEOUT:
+            raise ValueError(
+                f"timeout must be <= {MAX_FOREGROUND_TIMEOUT}s for foreground commands; "
+                f"use run_in_background=true for longer timeouts (up to {MAX_BACKGROUND_TIMEOUT}s)"
+            )
+        return self
+
+
+class Shell(CallableTool2[Params]):
+    name: str = "Shell"
+    params: type[Params] = Params
+
+    def __init__(self, approval: Approval, environment: Environment, runtime: Runtime):
+        is_powershell = environment.shell_name == "Windows PowerShell"
+        super().__init__(
+            description=load_desc(
+                Path(__file__).parent / ("powershell.md" if is_powershell else "bash.md"),
+                {"SHELL": f"{environment.shell_name} (`{environment.shell_path}`)"},
+            )
+        )
+        self._approval = approval
+        self._is_powershell = is_powershell
+        self._shell_path = environment.shell_path
+        self._runtime = runtime
+
+    @override
+    async def __call__(self, params: Params) -> ToolReturnValue:
+        builder = ToolResultBuilder()
+
+        if not params.command:
+            return builder.error("Command cannot be empty.", brief="Empty command")
+
+        if params.run_in_background:
+            return await self._run_in_background(params)
+
+        result = await self._approval.request(
+            self.name,
+            "run command",
+            f"Run command `{params.command}`",
+            display=[
+                ShellDisplayBlock(
+                    language="powershell" if self._is_powershell else "bash",
+                    command=params.command,
+                )
+            ],
+        )
+        if not result:
+            return result.rejection_error()
+
+        def stdout_cb(line: bytes):
+            line_str = line.decode(encoding="utf-8", errors="replace")
+            builder.write(line_str)
+
+        def stderr_cb(line: bytes):
+            line_str = line.decode(encoding="utf-8", errors="replace")
+            builder.write(line_str)
+
+        try:
+            exitcode = await self._run_shell_command(
+                params.command, stdout_cb, stderr_cb, params.timeout
+            )
+
+            if exitcode == 0:
+                return builder.ok("Command executed successfully.")
+            else:
+                return builder.error(
+                    f"Command failed with exit code: {exitcode}.",
+                    brief=f"Failed with exit code: {exitcode}",
+                )
+        except TimeoutError:
+            return builder.error(
+                f"Command killed by timeout ({params.timeout}s)",
+                brief=f"Killed by timeout ({params.timeout}s)",
+            )
+        except Exception as e:
+            logger.error(
+                "Shell command execution failed: {command}: {error}",
+                command=params.command,
+                error=e,
+            )
+            return builder.error(
+                f"Command execution failed: {e}",
+                brief="Execution failed",
+            )
+
+    async def _run_in_background(self, params: Params) -> ToolReturnValue:
+        tool_call = get_current_tool_call_or_none()
+        if tool_call is None:
+            return ToolResultBuilder().error(
+                "Background shell requires a tool call context.",
+                brief="No tool call context",
+            )
+
+        result = await self._approval.request(
+            self.name,
+            "run background command",
+            f"Run background command `{params.command}`",
+            display=[
+                ShellDisplayBlock(
+                    language="powershell" if self._is_powershell else "bash",
+                    command=params.command,
+                )
+            ],
+        )
+        if not result:
+            return result.rejection_error()
+
+        try:
+            view = self._runtime.background_tasks.create_bash_task(
+                command=params.command,
+                description=params.description.strip(),
+                timeout_s=params.timeout,
+                tool_call_id=tool_call.id,
+                shell_name="Windows PowerShell" if self._is_powershell else "bash",
+                shell_path=str(self._shell_path),
+                cwd=str(self._runtime.session.work_dir),
+            )
+        except Exception as exc:
+            logger.error(
+                "Failed to start background shell task: {command}: {error}",
+                command=params.command,
+                error=exc,
+            )
+            builder = ToolResultBuilder()
+            return builder.error(f"Failed to start background task: {exc}", brief="Start failed")
+
+        return self._background_ok(view)
+
+    def _background_ok(self, view: TaskView) -> ToolReturnValue:
+        builder = ToolResultBuilder()
+        builder.write(
+            "\n".join(
+                [
+                    format_task(view, include_command=True),
+                    "automatic_notification: true",
+                    "next_step: You will be automatically notified when it completes.",
+                    (
+                        "next_step: Use TaskOutput with this task_id for a non-blocking "
+                        "status/output snapshot. Only set block=true when you intentionally "
+                        "want to wait."
+                    ),
+                    "next_step: Use TaskStop only if the task must be cancelled.",
+                    (
+                        "human_shell_hint: For users in the interactive shell, "
+                        "the only task-management slash command is /task. "
+                        "Do not suggest /task list, /task output, /task stop, or /tasks."
+                    ),
+                ]
+            )
+        )
+        builder.display(
+            BackgroundTaskDisplayBlock(
+                task_id=view.spec.id,
+                kind=view.spec.kind,
+                status=view.runtime.status,
+                description=view.spec.description,
+            )
+        )
+        return builder.ok("Background task started", brief=f"Started {view.spec.id}")
+
+    async def _run_shell_command(
+        self,
+        command: str,
+        stdout_cb: Callable[[bytes], None],
+        stderr_cb: Callable[[bytes], None],
+        timeout: int,
+    ) -> int:
+        async def _read_stream(stream: AsyncReadable, cb: Callable[[bytes], None]):
+            while True:
+                line = await stream.readline()
+                if line:
+                    cb(line)
+                else:
+                    break
+
+        process = await pythinker_host.exec(
+            *self._shell_args(command), env=get_noninteractive_env()
+        )
+
+        # Close stdin immediately so interactive prompts (e.g. git password) get
+        # EOF instead of hanging forever waiting for input that will never come.
+        process.stdin.close()
+
+        try:
+            await asyncio.wait_for(
+                asyncio.gather(
+                    _read_stream(process.stdout, stdout_cb),
+                    _read_stream(process.stderr, stderr_cb),
+                ),
+                timeout,
+            )
+            return await process.wait()
+        except asyncio.CancelledError:
+            await process.kill()
+            raise
+        except TimeoutError:
+            await process.kill()
+            raise
+
+    def _shell_args(self, command: str) -> tuple[str, ...]:
+        if self._is_powershell:
+            return (str(self._shell_path), "-command", command)
+        return (str(self._shell_path), "-c", command)

pythinker_code/tools/shell/bash.md

@@ -0,0 +1,35 @@
+Execute a ${SHELL} command. Use this tool to explore the filesystem, edit files, run scripts, get system information, etc.
+
+**Output:**
+The stdout and stderr will be combined and returned as a string. The output may be truncated if it is too long. If the command failed, the exit code will be provided in a system tag.
+
+If `run_in_background=true`, the command will be started as a background task and this tool will return a task ID instead of waiting for command completion. When doing that, you must provide a short `description`. You will be automatically notified when the task completes. Use `TaskOutput` for a non-blocking status/output snapshot, and only set `block=true` when you explicitly want to wait for completion. Use `TaskStop` only if the task must be cancelled. For human users in the interactive shell, background tasks are managed through `/task` only; do not suggest `/task list`, `/task output`, `/task stop`, `/tasks`, or any other invented shell subcommands.
+
+**Guidelines for safety and security:**
+- Each shell tool call will be executed in a fresh shell environment. The shell variables, current working directory changes, and the shell history is not preserved between calls.
+- The tool call will return after the command is finished. You shall not use this tool to execute an interactive command or a command that may run forever. For possibly long-running commands, you shall set `timeout` argument to a reasonable value.
+- Avoid using `..` to access files or directories outside of the working directory.
+- Avoid modifying files outside of the working directory unless explicitly instructed to do so.
+- Never run commands that require superuser privileges unless explicitly instructed to do so.
+
+**Guidelines for efficiency:**
+- For multiple related commands, use `&&` to chain them in a single call, e.g. `cd /path && ls -la`
+- Use `;` to run commands sequentially regardless of success/failure
+- Use `||` for conditional execution (run second command only if first fails)
+- Use pipe operations (`|`) and redirections (`>`, `>>`) to chain input and output between commands
+- Always quote file paths containing spaces with double quotes (e.g., cd "/path with spaces/")
+- Use `if`, `case`, `for`, `while` control flows to execute complex logic in a single call.
+- Verify directory structure before create/edit/delete files or directories to reduce the risk of failure.
+- Prefer `run_in_background=true` for long-running builds, tests, watchers, or servers when you need the conversation to continue before the command finishes.
+- After starting a background task, do not guess its outcome. Rely on the automatic completion notification whenever possible. Use `TaskOutput` for non-blocking progress snapshots by default, and set `block=true` only when you intentionally want to wait.
+- If you need to tell a human shell user how to manage background tasks, only mention `/task`. Do not invent `/task list`, `/task output`, `/task stop`, or `/tasks`.
+
+**Commands available:**
+- Shell environment: cd, pwd, export, unset, env
+- File system operations: ls, find, mkdir, rm, cp, mv, touch, chmod, chown
+- File viewing/editing: cat, grep, head, tail, diff, patch
+- Text processing: awk, sed, sort, uniq, wc
+- System information/operations: ps, kill, top, df, free, uname, whoami, id, date
+- Network operations: curl, wget, ping, telnet, ssh
+- Archive operations: tar, zip, unzip
+- Other: Other commands available in the shell environment. Check the existence of a command by running `which <command>` before using it.

pythinker_code/tools/shell/powershell.md

@@ -0,0 +1,30 @@
+Execute a ${SHELL} command. Use this tool to explore the filesystem, inspect or edit files, run Windows scripts, collect system information, etc., whenever the agent is running on Windows.
+
+Note that you are running on Windows, so make sure to use Windows commands, paths, and conventions.
+
+**Output:**
+The stdout and stderr streams are combined and returned as a single string. Extremely long output may be truncated. When a command fails, the exit code is provided in a system tag.
+
+If `run_in_background=true`, the command will be started as a background task and this tool will return a task ID instead of waiting for completion. When doing that, you must provide a short `description`. You will be automatically notified when the task completes. Use `TaskOutput` for a non-blocking status/output snapshot, and only set `block=true` when you explicitly want to wait for completion. Use `TaskStop` only if the task must be cancelled. For human users in the interactive shell, background tasks are managed through `/task` only; do not suggest `/task list`, `/task output`, `/task stop`, `/tasks`, or any other invented shell subcommands.
+
+**Guidelines for safety and security:**
+- Every tool call starts a fresh ${SHELL} session. Environment variables, `cd` changes, and command history do not persist between calls.
+- Do not launch interactive programs or anything that is expected to block indefinitely; ensure each command finishes promptly. Provide a `timeout` argument for potentially long runs.
+- Avoid using `..` to leave the working directory, and never touch files outside that directory unless explicitly instructed.
+- Never attempt commands that require elevated (Administrator) privileges unless explicitly authorized.
+
+**Guidelines for efficiency:**
+- Chain related commands with `;` and use `if ($?)` or `if (-not $?)` to conditionally execute commands based on the success or failure of previous ones.
+- Redirect or pipe output with `>`, `>>`, `|`, and leverage `for /f`, `if`, and `set` to build richer one-liners instead of multiple tool calls.
+- Reuse built-in utilities (e.g., `findstr`, `where`) to filter, transform, or locate data in a single invocation.
+- Prefer `run_in_background=true` for long-running builds, tests, watchers, or servers when you need the conversation to continue before the command finishes.
+- After starting a background task, do not guess its outcome. Rely on the automatic completion notification whenever possible. Use `TaskOutput` for non-blocking progress snapshots by default, and set `block=true` only when you intentionally want to wait.
+- If you need to tell a human shell user how to manage background tasks, only mention `/task`. Do not invent `/task list`, `/task output`, `/task stop`, or `/tasks`.
+
+**Commands available:**
+- Shell environment: `cd`, `dir`, `set`, `setlocal`, `echo`, `call`, `where`
+- File operations: `type`, `copy`, `move`, `del`, `erase`, `mkdir`, `rmdir`, `attrib`, `mklink`
+- Text/search: `find`, `findstr`, `more`, `sort`, `Get-Content`
+- System info: `ver`, `systeminfo`, `tasklist`, `wmic`, `hostname`
+- Archives/scripts: `tar`, `Compress-Archive`, `powershell`, `python`, `node`
+- Other: Any other binaries available on the system PATH; run `where <command>` first if unsure.

pythinker_code/tools/test.py

@@ -0,0 +1,55 @@
+import asyncio
+from typing import override
+
+from pydantic import BaseModel
+from pythinker_core.tooling import CallableTool2, ToolOk, ToolReturnValue
+
+
+class PlusParams(BaseModel):
+    a: float
+    b: float
+
+
+class Plus(CallableTool2[PlusParams]):
+    name: str = "plus"
+    description: str = "Add two numbers"
+    params: type[PlusParams] = PlusParams
+
+    @override
+    async def __call__(self, params: PlusParams) -> ToolReturnValue:
+        return ToolOk(output=str(params.a + params.b))
+
+
+class CompareParams(BaseModel):
+    a: float
+    b: float
+
+
+class Compare(CallableTool2[CompareParams]):
+    name: str = "compare"
+    description: str = "Compare two numbers"
+    params: type[CompareParams] = CompareParams
+
+    @override
+    async def __call__(self, params: CompareParams) -> ToolReturnValue:
+        if params.a > params.b:
+            return ToolOk(output="greater")
+        elif params.a < params.b:
+            return ToolOk(output="less")
+        else:
+            return ToolOk(output="equal")
+
+
+class PanicParams(BaseModel):
+    message: str
+
+
+class Panic(CallableTool2[PanicParams]):
+    name: str = "panic"
+    description: str = "Raise an exception to cause the tool call to fail."
+    params: type[PanicParams] = PanicParams
+
+    @override
+    async def __call__(self, params: PanicParams) -> ToolReturnValue:
+        await asyncio.sleep(2)
+        raise Exception(f"panicked with a message with {len(params.message)} characters")

pythinker_code/tools/think/__init__.py

@@ -0,0 +1,21 @@
+from pathlib import Path
+from typing import override
+
+from pydantic import BaseModel, Field
+from pythinker_core.tooling import CallableTool2, ToolOk, ToolReturnValue
+
+from pythinker_code.tools.utils import load_desc
+
+
+class Params(BaseModel):
+    thought: str = Field(description=("A thought to think about."))
+
+
+class Think(CallableTool2[Params]):
+    name: str = "Think"
+    description: str = load_desc(Path(__file__).parent / "think.md", {})
+    params: type[Params] = Params
+
+    @override
+    async def __call__(self, params: Params) -> ToolReturnValue:
+        return ToolOk(output="", message="Thought logged")

pythinker_code/tools/think/think.md

@@ -0,0 +1 @@
+Use the tool to think about something. It will not obtain new information or change the database, but just append the thought to the log. Use it when complex reasoning or some cache memory is needed.