pythinker-code 0.8.0__py3-none-any.whl

pythinker_code/soul/dynamic_injections/plan_mode.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from pythinker_core.message import Message, TextPart
+
+from pythinker_code.soul.dynamic_injection import DynamicInjection, DynamicInjectionProvider
+
+if TYPE_CHECKING:
+    from pythinker_code.soul.pythinkersoul import PythinkerSoul
+
+# Inject a reminder every N assistant turns.
+_TURN_INTERVAL = 5
+# Every N-th reminder is the full version; others are sparse.
+_FULL_EVERY_N = 5
+
+
+class PlanModeInjectionProvider(DynamicInjectionProvider):
+    """Periodically injects read-only reminders while plan mode is active.
+
+    Throttling is inferred from history: scan backwards to the last
+    plan mode reminder and count assistant messages in between.
+    Only inject when the count exceeds ``_TURN_INTERVAL``.
+    """
+
+    def __init__(self) -> None:
+        self._inject_count: int = 0
+
+    async def get_injections(
+        self,
+        history: Sequence[Message],
+        soul: PythinkerSoul,
+    ) -> list[DynamicInjection]:
+        if not soul.plan_mode:
+            self._inject_count = 0
+            return []
+
+        plan_path = soul.get_plan_file_path()
+        plan_path_str = str(plan_path) if plan_path else None
+        plan_exists = plan_path is not None and plan_path.exists()
+
+        # Manual toggles schedule a one-shot activation reminder for the next LLM step.
+        if soul.consume_pending_plan_activation_injection():
+            self._inject_count = 1
+            # When re-entering with an existing plan, use the reentry reminder.
+            if plan_exists:
+                return [
+                    DynamicInjection(
+                        type="plan_mode_reentry",
+                        content=_reentry_reminder(plan_path_str),
+                    )
+                ]
+            return [
+                DynamicInjection(
+                    type="plan_mode",
+                    content=_full_reminder(plan_path_str, plan_exists),
+                )
+            ]
+
+        # Scan history backwards to find the last plan mode reminder.
+        turns_since_last = 0
+        found_previous = False
+        for msg in reversed(history):
+            if msg.role == "user" and _has_plan_reminder(msg):
+                found_previous = True
+                break
+            if msg.role == "assistant":
+                turns_since_last += 1
+
+        # First time (no reminder in history yet) -> inject full version.
+        if not found_previous:
+            self._inject_count = 1
+            return [
+                DynamicInjection(
+                    type="plan_mode",
+                    content=_full_reminder(plan_path_str, plan_exists),
+                )
+            ]
+
+        # Not enough turns since last reminder -> skip.
+        if turns_since_last < _TURN_INTERVAL:
+            return []
+
+        # Inject.
+        self._inject_count += 1
+        is_full = self._inject_count % _FULL_EVERY_N == 1
+        if is_full:
+            content = _full_reminder(plan_path_str, plan_exists)
+        else:
+            content = _sparse_reminder(plan_path_str)
+        return [DynamicInjection(type="plan_mode", content=content)]
+
+
+def _has_plan_reminder(msg: Message) -> bool:
+    """Check whether a message contains a plan mode reminder.
+
+    Detects by matching against stable prefixes of the actual reminder texts
+    so changes to the reminder wording stay automatically in sync.
+    """
+    keys = (
+        _sparse_reminder().split(".")[0],  # "Plan mode still active ..."
+        _full_reminder().split("\n")[0],  # "Plan mode is active. ..."
+    )
+    for part in msg.content:
+        if isinstance(part, TextPart) and any(key in part.text for key in keys):
+            return True
+    return False
+
+
+def _full_reminder(
+    plan_file_path: str | None = None,
+    plan_exists: bool = False,
+) -> str:
+    lines = [
+        "Plan mode is active. You MUST NOT make any edits "
+        "(with the exception of the plan file below), run non-readonly tools, "
+        "or otherwise make changes to the system. "
+        "This supersedes any other instructions you have received.",
+    ]
+    # Plan file info block
+    if plan_file_path:
+        lines.append("")
+        if plan_exists:
+            lines.append(
+                f"Plan file: {plan_file_path} "
+                "(exists — read first, then update it with WriteFile or StrReplaceFile)"
+            )
+        else:
+            lines.append(
+                f"Plan file: {plan_file_path} "
+                "(create it with WriteFile; once it exists, you can modify it with "
+                "WriteFile or StrReplaceFile)"
+            )
+        lines.append("This is the only file you are allowed to edit.")
+    # Workflow
+    lines.extend(
+        [
+            "",
+            "Workflow:",
+            "1. Understand — explore the codebase with Glob, Grep, ReadFile",
+            "2. Design — converge on the best approach; "
+            "consider trade-offs but aim for a single recommendation",
+            "3. Review — re-read key files to verify understanding",
+            "4. Write Plan — modify the plan file with WriteFile or StrReplaceFile. "
+            "Use WriteFile if the plan file does not exist yet",
+            "5. Exit — call ExitPlanMode for user approval",
+        ]
+    )
+    lines.extend(
+        [
+            "",
+            "## Handling multiple approaches",
+            "Keep it focused: at most 2-3 meaningfully different approaches. "
+            "Do NOT pad with minor variations — if one approach is clearly "
+            "superior, just propose that one.",
+            "When the best approach depends on user preferences, constraints, "
+            "or context you don't have, use AskUserQuestion to clarify first. "
+            "This helps you write a better, more targeted plan rather than "
+            "dumping multiple options for the user to sort through.",
+            "When you do include multiple approaches in the plan, you MUST pass them "
+            "as the `options` parameter when calling ExitPlanMode, so the user can "
+            "select which approach to execute at approval time.",
+            "NEVER write multiple approaches in the plan and call ExitPlanMode without "
+            "the `options` parameter — the user will only see Approve/Reject with "
+            "no way to choose.",
+            "",
+            "AskUserQuestion is for clarifying missing requirements or user preferences "
+            "that affect the plan.",
+            "Never ask about plan approval via text or AskUserQuestion.",
+            "Your turn must end with either AskUserQuestion "
+            "(to clarify requirements or preferences) "
+            "or ExitPlanMode (to request plan approval). "
+            "Do NOT end your turn any other way.",
+            "Do NOT use AskUserQuestion to ask about plan approval or reference "
+            '"the plan" — the user cannot see the plan until you call ExitPlanMode.',
+        ]
+    )
+    return "\n".join(lines)
+
+
+def _sparse_reminder(plan_file_path: str | None = None) -> str:
+    parts = [
+        "Plan mode still active (see full instructions earlier).",
+    ]
+    if plan_file_path:
+        parts.append(f"Read-only except plan file ({plan_file_path}).")
+    else:
+        parts.append("Read-only.")
+    parts.append(
+        "Use WriteFile or StrReplaceFile to modify the plan file. "
+        "If it does not exist yet, create it with WriteFile first."
+    )
+    parts.extend(
+        [
+            "Use AskUserQuestion to clarify user preferences "
+            "when it helps you write a better plan.",
+            "If the plan has multiple approaches, "
+            "pass options to ExitPlanMode so the user can choose.",
+            "End turns with AskUserQuestion (for clarifications) or ExitPlanMode (for approval).",
+            "Never ask about plan approval via text or AskUserQuestion.",
+        ]
+    )
+    return " ".join(parts)
+
+
+def _reentry_reminder(plan_file_path: str | None = None) -> str:
+    """One-shot reminder when re-entering plan mode with an existing plan."""
+    lines = [
+        "Plan mode is active. You MUST NOT make any edits "
+        "(with the exception of the plan file below), run non-readonly tools, "
+        "or otherwise make changes to the system. "
+        "This supersedes any other instructions you have received.",
+        "",
+        "## Re-entering Plan Mode",
+        (
+            f"A plan file exists at {plan_file_path} from a previous planning session."
+            if plan_file_path
+            else "A plan file from a previous planning session already exists."
+        ),
+        "Before proceeding:",
+        "1. Read the existing plan file to understand what was previously planned",
+        "2. Evaluate the user's current request against that plan",
+        "3. If different task: replace the old plan with a fresh one. "
+        "If same task: update the existing plan.",
+        "4. You may use WriteFile or StrReplaceFile to modify the plan file. "
+        "If the file does not exist yet, create it with WriteFile first.",
+    ]
+    lines.extend(
+        [
+            "5. Use AskUserQuestion to clarify missing requirements "
+            "or user preferences that affect the plan.",
+            "6. Always edit the plan file before calling ExitPlanMode.",
+            "",
+            "Your turn must end with either AskUserQuestion (to clarify requirements) "
+            "or ExitPlanMode (to request plan approval).",
+        ]
+    )
+    return "\n".join(lines)

pythinker_code/soul/message.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from pythinker_core.message import Message
+from pythinker_core.tooling.error import ToolRuntimeError
+
+from pythinker_code.llm import ModelCapability
+from pythinker_code.wire.types import (
+    ContentPart,
+    ImageURLPart,
+    TextPart,
+    ThinkPart,
+    ToolResult,
+    VideoURLPart,
+)
+
+
+def system(message: str) -> ContentPart:
+    return TextPart(text=f"<system>{message}</system>")
+
+
+def system_reminder(message: str) -> TextPart:
+    return TextPart(text=f"<system-reminder>\n{message}\n</system-reminder>")
+
+
+def is_system_reminder_message(message: Message) -> bool:
+    """Check whether a message is an internal system-reminder user message."""
+    if message.role != "user" or len(message.content) != 1:
+        return False
+    part = message.content[0]
+    return isinstance(part, TextPart) and part.text.strip().startswith("<system-reminder>")
+
+
+def tool_result_to_message(tool_result: ToolResult) -> Message:
+    """Convert a tool result to a message."""
+    if tool_result.return_value.is_error:
+        assert tool_result.return_value.message, "Error return value should have a message"
+        message = tool_result.return_value.message
+        if isinstance(tool_result.return_value, ToolRuntimeError):
+            message += "\nThis is an unexpected error and the tool is probably not working."
+        content: list[ContentPart] = [system(f"ERROR: {message}")]
+        if tool_result.return_value.output:
+            content.extend(_output_to_content_parts(tool_result.return_value.output))
+    else:
+        content: list[ContentPart] = []
+        if tool_result.return_value.message:
+            content.append(system(tool_result.return_value.message))
+        if tool_result.return_value.output:
+            content.extend(_output_to_content_parts(tool_result.return_value.output))
+        if not content:
+            content.append(system("Tool output is empty."))
+        elif not any(isinstance(part, TextPart) for part in content):
+            # Ensure at least one TextPart exists so the LLM API won't reject
+            # the message with "text content is empty" (see #1663).
+            content.insert(0, system("Tool returned non-text content."))
+
+    return Message(
+        role="tool",
+        content=content,
+        tool_call_id=tool_result.tool_call_id,
+    )
+
+
+def _output_to_content_parts(
+    output: str | ContentPart | Sequence[ContentPart],
+) -> list[ContentPart]:
+    content: list[ContentPart] = []
+    match output:
+        case str(text):
+            if text:
+                content.append(TextPart(text=text))
+        case ContentPart():
+            content.append(output)
+        case _:
+            content.extend(output)
+    return content
+
+
+def check_message(
+    message: Message, model_capabilities: set[ModelCapability]
+) -> set[ModelCapability]:
+    """Check the message content, return the missing model capabilities."""
+    capabilities_needed = set[ModelCapability]()
+    for part in message.content:
+        if isinstance(part, ImageURLPart):
+            capabilities_needed.add("image_in")
+        elif isinstance(part, VideoURLPart):
+            capabilities_needed.add("video_in")
+        elif isinstance(part, ThinkPart):
+            capabilities_needed.add("thinking")
+    return capabilities_needed - model_capabilities

pythinker_code/soul/permission.py

@@ -0,0 +1,368 @@
+from __future__ import annotations
+
+import re
+import shlex
+from contextvars import ContextVar, Token
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+from pythinker_core.tooling import ToolError
+
+if TYPE_CHECKING:
+    from pythinker_code.soul.agent import Runtime
+
+
+PermissionProfileName = Literal["read_only", "plan", "ask", "implement", "review", "verify"]
+
+
+@dataclass(frozen=True, slots=True)
+class PermissionProfile:
+    name: PermissionProfileName
+    description: str
+    allow_file_mutation: bool
+    allow_shell_mutation: bool
+    allow_plan_file_mutation: bool = False
+
+
+_PERMISSION_PROFILES: dict[PermissionProfileName, PermissionProfile] = {
+    "read_only": PermissionProfile(
+        name="read_only",
+        description="read-only exploration",
+        allow_file_mutation=False,
+        allow_shell_mutation=False,
+    ),
+    "plan": PermissionProfile(
+        name="plan",
+        description="plan mode",
+        allow_file_mutation=False,
+        allow_shell_mutation=False,
+        allow_plan_file_mutation=True,
+    ),
+    "ask": PermissionProfile(
+        name="ask",
+        description="ask-only mode",
+        allow_file_mutation=False,
+        allow_shell_mutation=False,
+    ),
+    "implement": PermissionProfile(
+        name="implement",
+        description="implementation mode",
+        allow_file_mutation=True,
+        allow_shell_mutation=True,
+    ),
+    "review": PermissionProfile(
+        name="review",
+        description="review mode",
+        allow_file_mutation=False,
+        allow_shell_mutation=False,
+    ),
+    "verify": PermissionProfile(
+        name="verify",
+        description="verification mode",
+        allow_file_mutation=False,
+        allow_shell_mutation=False,
+    ),
+}
+
+_SUBAGENT_PROFILES: dict[str, PermissionProfileName] = {
+    "explore": "read_only",
+    "plan": "plan",
+    "review": "review",
+    "verifier": "verify",
+    "coder": "implement",
+    "implementer": "implement",
+    "code-reviewer": "review",
+    "security-reviewer": "review",
+    "debugger": "verify",
+}
+
+_STEP_PERMISSION_PROFILE: ContextVar[PermissionProfile | None] = ContextVar(
+    "pythinker_step_permission_profile", default=None
+)
+
+_SHELL_SEGMENT_SEPARATORS = {";", "&&", "||", "|"}
+_WRITING_REDIRECTION_RE = re.compile(r"(?:^|\s)(?:[0-9]*>>?|&>)\s*(\S+)")
+_MUTATING_COMMANDS = {
+    "chmod",
+    "chown",
+    "cp",
+    "dd",
+    "install",
+    "ln",
+    "mkdir",
+    "mktemp",
+    "mv",
+    "patch",
+    "rm",
+    "rmdir",
+    "rsync",
+    "tee",
+    "touch",
+    "truncate",
+    "unlink",
+    # Shell interpreters: a wrapped `bash -c "rm -rf X"` would otherwise pass
+    # the gate because only the wrapper name `bash` is checked, not the script.
+    "bash",
+    "csh",
+    "dash",
+    "fish",
+    "ksh",
+    "sh",
+    "tcsh",
+    "zsh",
+    # Script runtimes with `-c`/`-e` execute arbitrary code; treat the runtime
+    # itself as mutating in read-only/review/verify profiles.
+    "lua",
+    "node",
+    "perl",
+    "python",
+    "python3",
+    "ruby",
+    # Container/orchestration commands with side effects on host or cluster.
+    "docker",
+    "helm",
+    "kubectl",
+    "podman",
+}
+_PACKAGE_MANAGER_COMMANDS = {
+    "apt",
+    "apt-get",
+    "brew",
+    "cargo",
+    "dnf",
+    "gem",
+    "go",
+    "npm",
+    "pnpm",
+    "pip",
+    "pip3",
+    "poetry",
+    "uv",
+    "yarn",
+}
+_PACKAGE_MANAGER_MUTATIONS = {
+    "add",
+    "build",
+    "compile",
+    "install",
+    "publish",
+    "remove",
+    "sync",
+    "uninstall",
+    "update",
+    "upgrade",
+}
+_GIT_MUTATIONS = {
+    "add",
+    "am",
+    "apply",
+    "bisect",
+    "branch",
+    "checkout",
+    "cherry-pick",
+    "clean",
+    "commit",
+    "merge",
+    "mv",
+    "pull",
+    "push",
+    "rebase",
+    "reset",
+    "restore",
+    "revert",
+    "rm",
+    "stash",
+    "switch",
+    "tag",
+}
+_WRAPPER_COMMANDS = {"command", "env", "nohup", "sudo", "time"}
+
+
+def permission_profile_for_runtime(runtime: Runtime) -> PermissionProfile:
+    """Return the hard permission profile currently enforced for a runtime."""
+    if runtime.role == "subagent" and runtime.subagent_type:
+        profile_name = _SUBAGENT_PROFILES.get(runtime.subagent_type, "read_only")
+    elif runtime.session.state.plan_mode:
+        profile_name = "plan"
+    else:
+        profile_name = "implement"
+    return _PERMISSION_PROFILES[profile_name]
+
+
+def active_permission_profile(runtime: Runtime) -> PermissionProfile:
+    """Return the effective profile for this task.
+
+    A single LLM step snapshots the profile before tool calls start. Tool tasks inherit that
+    ContextVar value, so plan/read-only checks cannot race with an ExitPlanMode tool call from the
+    same assistant response.
+    """
+    return _STEP_PERMISSION_PROFILE.get() or permission_profile_for_runtime(runtime)
+
+
+def set_step_permission_profile(profile: PermissionProfile) -> Token[PermissionProfile | None]:
+    """Freeze permission checks for all tool tasks spawned in the current context."""
+    return _STEP_PERMISSION_PROFILE.set(profile)
+
+
+def reset_step_permission_profile(token: Token[PermissionProfile | None]) -> None:
+    _STEP_PERMISSION_PROFILE.reset(token)
+
+
+def check_file_mutation_allowed(
+    runtime: Runtime, *, is_plan_artifact: bool = False
+) -> ToolError | None:
+    profile = active_permission_profile(runtime)
+    if profile.allow_file_mutation:
+        return None
+    if is_plan_artifact and profile.allow_plan_file_mutation:
+        return None
+    return ToolError(
+        message=(
+            f"The active {profile.description} permission profile blocks file mutations. "
+            "Switch to an implementation/coder profile before editing files."
+        ),
+        brief="Permission profile restriction",
+    )
+
+
+def check_shell_command_allowed(runtime: Runtime, command: str) -> ToolError | None:
+    profile = active_permission_profile(runtime)
+    if profile.allow_shell_mutation:
+        return None
+    reason = shell_mutation_reason(command)
+    if reason is None:
+        return None
+    return ToolError(
+        message=(
+            f"The active {profile.description} permission profile blocks this shell command "
+            f"because it appears to mutate the workspace or environment ({reason}). "
+            "Use a read-only command or switch to an implementation/coder profile."
+        ),
+        brief="Permission profile restriction",
+    )
+
+
+def check_external_tool_allowed(runtime: Runtime, tool_name: str) -> ToolError | None:
+    """Fail closed for tools whose side effects are not classified by built-in guards."""
+    profile = active_permission_profile(runtime)
+    if profile.allow_file_mutation and profile.allow_shell_mutation:
+        return None
+    return ToolError(
+        message=(
+            f"The active {profile.description} permission profile blocks external tool "
+            f"`{tool_name}` because its side effects are not known to be read-only. "
+            "Switch to an implementation/coder profile before using external tools."
+        ),
+        brief="Permission profile restriction",
+    )
+
+
+def check_tool_call_allowed(
+    runtime: Runtime, tool_name: str, arguments: dict[str, Any], *, tool: object | None = None
+) -> ToolError | None:
+    """Central permission guard for tool adapters that can bypass per-tool checks."""
+    if tool_name == "Shell" and isinstance(arguments.get("command"), str):
+        return check_shell_command_allowed(runtime, arguments["command"])
+
+    tool_type = type(tool)
+    module = getattr(tool_type, "__module__", "")
+    qualname = getattr(tool_type, "__qualname__", "")
+    if module == "pythinker_code.plugin.tool" and qualname.endswith("PluginTool"):
+        return check_external_tool_allowed(runtime, tool_name)
+    if module == "pythinker_code.soul.toolset" and qualname in {"MCPTool", "WireExternalTool"}:
+        return check_external_tool_allowed(runtime, tool_name)
+    return None
+
+
+def shell_mutation_reason(command: str) -> str | None:
+    """Best-effort guard for obviously mutating shell commands.
+
+    This is intentionally conservative for common destructive/write forms. It is not a shell
+    sandbox; it prevents accidental tool-level bypasses of read-only/plan/review/verify profiles.
+    """
+    for match in _WRITING_REDIRECTION_RE.finditer(command):
+        target = match.group(1)
+        if target.startswith("&") or target in {"/dev/null", "NUL"}:
+            continue
+        return "output redirection"
+
+    try:
+        tokens = shlex.split(command, posix=True)
+    except ValueError:
+        return "unparsable shell command"
+
+    segment: list[str] = []
+    for token in [*tokens, ";"]:
+        if token in _SHELL_SEGMENT_SEPARATORS:
+            reason = _segment_mutation_reason(segment)
+            if reason is not None:
+                return reason
+            segment = []
+        else:
+            segment.append(token)
+    return None
+
+
+def _segment_mutation_reason(tokens: list[str]) -> str | None:
+    if not tokens:
+        return None
+    command, args = _unwrap_command(tokens)
+    if command is None:
+        return None
+    base = command.rsplit("/", 1)[-1]
+
+    if base in _MUTATING_COMMANDS:
+        return f"{base} command"
+    if base == "sed" and any(arg == "-i" or arg.startswith("-i") for arg in args):
+        return "sed in-place edit"
+    if base == "perl" and any(arg == "-i" or arg.startswith("-i") for arg in args):
+        return "perl in-place edit"
+    if base == "git":
+        subcommand = _git_subcommand(args)
+        if subcommand in _GIT_MUTATIONS:
+            return f"git {subcommand}"
+    if base in _PACKAGE_MANAGER_COMMANDS:
+        subcommand = _first_non_option(args)
+        if subcommand in _PACKAGE_MANAGER_MUTATIONS:
+            return f"{base} {subcommand}"
+    return None
+
+
+def _unwrap_command(tokens: list[str]) -> tuple[str | None, list[str]]:
+    remaining = list(tokens)
+    while remaining:
+        command = remaining.pop(0)
+        base = command.rsplit("/", 1)[-1]
+        if "=" in command and not command.startswith("=") and command.split("=", 1)[0]:
+            continue
+        if base not in _WRAPPER_COMMANDS:
+            return command, remaining
+        if base in {"sudo", "time", "nohup", "command"}:
+            while remaining and remaining[0].startswith("-"):
+                remaining.pop(0)
+        elif base == "env":
+            while remaining and (remaining[0].startswith("-") or "=" in remaining[0]):
+                remaining.pop(0)
+    return None, []
+
+
+def _git_subcommand(args: list[str]) -> str | None:
+    remaining = list(args)
+    while remaining:
+        arg = remaining.pop(0)
+        if arg == "-C" and remaining:
+            remaining.pop(0)
+            continue
+        if arg.startswith("--git-dir=") or arg.startswith("--work-tree="):
+            continue
+        if arg.startswith("-"):
+            continue
+        return arg
+    return None
+
+
+def _first_non_option(args: list[str]) -> str | None:
+    for arg in args:
+        if not arg.startswith("-"):
+            return arg
+    return None