pythinker-code 2.0.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