pythinker-code 2.0.0__py3-none-any.whl

pythinker_code/soul/approval.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable
+from typing import Literal
+
+from pythinker_code.approval_runtime import (
+    ApprovalCancelledError,
+    ApprovalRuntime,
+    ApprovalSource,
+    get_current_approval_source_or_none,
+)
+from pythinker_code.soul.toolset import get_current_tool_call_or_none
+from pythinker_code.tools.utils import ToolRejectedError
+from pythinker_code.utils.logging import logger
+from pythinker_code.wire.types import DisplayBlock
+
+type Response = Literal["approve", "approve_for_session", "reject"]
+
+
+class ApprovalResult:
+    """Result of an approval request. Behaves as bool for backward compatibility."""
+
+    __slots__ = ("approved", "feedback")
+
+    def __init__(self, approved: bool, feedback: str = ""):
+        self.approved = approved
+        self.feedback = feedback
+
+    def __bool__(self) -> bool:
+        return self.approved
+
+    def rejection_error(self) -> ToolRejectedError:
+        if self.feedback:
+            return ToolRejectedError(
+                message=(f"The tool call is rejected by the user. User feedback: {self.feedback}"),
+                brief=f"Rejected: {self.feedback}",
+                has_feedback=True,
+            )
+        source = get_current_approval_source_or_none()
+        is_subagent = source is not None and source.agent_id is not None
+        if is_subagent:
+            return ToolRejectedError(
+                message=(
+                    "The tool call is rejected by the user. "
+                    "Try a different approach to complete your task, or explain the "
+                    "limitation in your summary if no alternative is available. "
+                    "Do not retry the same tool call, and do not attempt to bypass "
+                    "this restriction through indirect means."
+                ),
+            )
+        return ToolRejectedError()
+
+
+class ApprovalState:
+    def __init__(
+        self,
+        yolo: bool = False,
+        auto: bool = False,
+        runtime_auto: bool = False,
+        auto_approve_actions: set[str] | None = None,
+        on_change: Callable[[], None] | None = None,
+    ):
+        self.yolo = yolo
+        self.auto = auto
+        """Persisted session flag. True when no user is present (auto mode).
+
+        Implies auto-approve and is restored with the session.
+        """
+        self.runtime_auto = runtime_auto
+        """Invocation-only auto flag, e.g. ``--auto`` or ``--print``. Not persisted."""
+        self.auto_approve_actions: set[str] = auto_approve_actions or set()
+        """Set of action names that should automatically be approved."""
+        self._on_change = on_change
+
+    def notify_change(self) -> None:
+        if self._on_change is not None:
+            self._on_change()
+
+
+class Approval:
+    def __init__(
+        self,
+        yolo: bool = False,
+        *,
+        state: ApprovalState | None = None,
+        runtime: ApprovalRuntime | None = None,
+    ):
+        self._state = state or ApprovalState(yolo=yolo)
+        self._runtime = runtime or ApprovalRuntime()
+
+    def share(self) -> Approval:
+        """Create a new approval queue that shares approval state."""
+        return Approval(state=self._state, runtime=self._runtime)
+
+    def set_runtime(self, runtime: ApprovalRuntime) -> None:
+        self._runtime = runtime
+
+    @property
+    def runtime(self) -> ApprovalRuntime:
+        return self._runtime
+
+    def set_yolo(self, yolo: bool) -> None:
+        self._state.yolo = yolo
+        self._state.notify_change()
+
+    def set_auto(self, auto: bool) -> None:
+        """Toggle persisted auto (unattended, no user present) mode.
+
+        Turning it off also clears any invocation-only auto overlay so an
+        interactive session started with ``--auto`` can return to interactive
+        behavior via ``/auto``.
+        """
+        self._state.auto = auto
+        if not auto:
+            self._state.runtime_auto = False
+        self._state.notify_change()
+
+    def set_runtime_auto(self, auto: bool) -> None:
+        """Toggle invocation-only auto mode without persisting it."""
+        self._state.runtime_auto = auto
+
+    def is_auto_approve(self) -> bool:
+        """True when tool calls should be auto-approved.
+
+        Auto mode implies auto-approve, so this returns True whenever either the
+        explicit yolo flag or auto mode is set.
+        """
+        return self._state.yolo or self.is_auto()
+
+    def is_yolo(self) -> bool:
+        """True only when the user explicitly opted into yolo."""
+        return self._state.yolo
+
+    def is_yolo_flag(self) -> bool:
+        """True only when the user explicitly opted into yolo (not via auto)."""
+        return self.is_yolo()
+
+    def is_auto(self) -> bool:
+        """True when no user is present (auto mode)."""
+        return self._state.auto or self._state.runtime_auto
+
+    def is_auto_flag(self) -> bool:
+        """True only when persisted auto mode is active."""
+        return self._state.auto
+
+    def is_runtime_auto(self) -> bool:
+        """True only when auto mode came from this invocation."""
+        return self._state.runtime_auto
+
+    async def request(
+        self,
+        sender: str,
+        action: str,
+        description: str,
+        display: list[DisplayBlock] | None = None,
+    ) -> ApprovalResult:
+        """
+        Request approval for the given action. Intended to be called by tools.
+
+        Args:
+            sender (str): The name of the sender.
+            action (str): The action to request approval for.
+                This is used to identify the action for auto-approval.
+            description (str): The description of the action. This is used to display to the user.
+
+        Returns:
+            ApprovalResult: Result with ``approved`` flag and optional ``feedback``.
+                Behaves as ``bool`` via ``__bool__``, so ``if not result:`` works.
+
+        Raises:
+            RuntimeError: If the approval is requested from outside a tool call.
+        """
+        tool_call = get_current_tool_call_or_none()
+        if tool_call is None:
+            raise RuntimeError("Approval must be requested from a tool call.")
+
+        logger.debug(
+            "{tool_name} ({tool_call_id}) requesting approval: {action} {description}",
+            tool_name=tool_call.function.name,
+            tool_call_id=tool_call.id,
+            action=action,
+            description=description,
+        )
+        if self.is_auto_approve():
+            from pythinker_code.telemetry import track
+
+            track(
+                "tool_approved",
+                tool_name=tool_call.function.name,
+                approval_mode="auto" if self.is_auto() else "yolo",
+            )
+            return ApprovalResult(approved=True)
+
+        if action in self._state.auto_approve_actions:
+            from pythinker_code.telemetry import track
+
+            track(
+                "tool_approved",
+                tool_name=tool_call.function.name,
+                approval_mode="auto_session",
+            )
+            return ApprovalResult(approved=True)
+
+        request_id = str(uuid.uuid4())
+        display_blocks = display or []
+        source = get_current_approval_source_or_none() or ApprovalSource(
+            kind="foreground_turn",
+            id=tool_call.id,
+        )
+        self._runtime.create_request(
+            request_id=request_id,
+            tool_call_id=tool_call.id,
+            sender=sender,
+            action=action,
+            description=description,
+            display=display_blocks,
+            source=source,
+        )
+        try:
+            response, feedback = await self._runtime.wait_for_response(request_id)
+        except ApprovalCancelledError:
+            from pythinker_code.telemetry import track
+
+            track(
+                "tool_rejected",
+                tool_name=tool_call.function.name,
+                approval_mode="cancelled",
+            )
+            record = self._runtime.get_request(request_id)
+            return ApprovalResult(approved=False, feedback=record.feedback if record else "")
+        from pythinker_code.telemetry import track
+
+        match response:
+            case "approve":
+                track(
+                    "tool_approved",
+                    tool_name=tool_call.function.name,
+                    approval_mode="manual",
+                )
+                return ApprovalResult(approved=True)
+            case "approve_for_session":
+                track(
+                    "tool_approved",
+                    tool_name=tool_call.function.name,
+                    approval_mode="manual",
+                )
+                self._state.auto_approve_actions.add(action)
+                self._state.notify_change()
+                for pending in self._runtime.list_pending():
+                    if pending.action == action:
+                        self._runtime.resolve(pending.id, "approve")
+                return ApprovalResult(approved=True)
+            case "reject":
+                track(
+                    "tool_rejected",
+                    tool_name=tool_call.function.name,
+                    approval_mode="manual",
+                )
+                return ApprovalResult(approved=False, feedback=feedback)
+            case _:
+                track(
+                    "tool_rejected",
+                    tool_name=tool_call.function.name,
+                    approval_mode="manual",
+                )
+                return ApprovalResult(approved=False)

pythinker_code/soul/btw.py

@@ -0,0 +1,214 @@
+"""Side question ("/btw") - answer a quick question without interrupting the main conversation.
+
+Uses the same system_prompt + normalized history + tool definitions as the main
+agent to maximize prompt cache hits.  Tools are declared (for cache) but denied
+at execution time.  maxTurns=2 so if the LLM mistakenly calls a tool on the
+first turn, the error result gives it a second chance to answer with text.
+
+The question and response are NOT written to the main context history.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+import pythinker_core
+from pythinker_core.message import Message, ToolCall
+from pythinker_core.tooling import Tool, ToolError, ToolResult
+
+from pythinker_code.soul import LLMNotSet, wire_send
+from pythinker_code.soul.dynamic_injection import normalize_history
+from pythinker_code.soul.message import system_reminder
+from pythinker_code.utils.logging import logger
+from pythinker_code.wire.types import BtwBegin, BtwEnd, TextPart
+
+if TYPE_CHECKING:
+    from pythinker_core.chat_provider import StreamedMessagePart
+
+    from pythinker_code.soul.pythinkersoul import PythinkerSoul
+
+_BTW_MAX_TURNS = 2
+
+SIDE_QUESTION_SYSTEM_REMINDER = """\
+This is a side question from the user. Answer directly in a single response.
+
+IMPORTANT:
+- You are a separate, lightweight instance answering one question.
+- The main agent continues independently — do NOT reference being interrupted.
+- Do NOT call any tools. All tool calls are disabled and will be rejected.
+  Even though tool definitions are visible in this request, they exist only
+  for technical reasons (prompt cache). You MUST NOT use them.
+- Respond ONLY with text based on what you already know from the conversation.
+- This is a one-off response — no follow-up turns.
+- If you don't know the answer, say so directly."""
+
+
+# ---------------------------------------------------------------------------
+# DenyAllToolset: advertises tools (cache match) but rejects every call
+# ---------------------------------------------------------------------------
+
+
+class _DenyAllToolset:
+    """A toolset that exposes the same tool definitions as the agent (for prompt
+    cache matching) but rejects every tool call with an error message."""
+
+    def __init__(self, source_tools: list[Tool]) -> None:
+        self._tools = source_tools
+
+    @property
+    def tools(self) -> list[Tool]:
+        return self._tools
+
+    def handle(self, tool_call: ToolCall) -> ToolResult:
+        return ToolResult(
+            tool_call_id=tool_call.id,
+            return_value=ToolError(
+                message="Tool calls are disabled for side questions. Answer with text only.",
+                brief="denied",
+            ),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Context construction
+# ---------------------------------------------------------------------------
+
+
+def _build_btw_context(
+    soul: PythinkerSoul, question: str
+) -> tuple[str, list[Message], _DenyAllToolset]:
+    """Build (system_prompt, history, toolset) aligned with the main agent.
+
+    Uses the same system_prompt, normalize_history(), and tool definitions
+    as ``PythinkerSoul._step`` so the LLM provider can reuse the prompt cache.
+    """
+    system_prompt = soul._agent.system_prompt  # pyright: ignore[reportPrivateUsage]
+    effective_history = normalize_history(soul.context.history)
+
+    wrapped = f"{system_reminder(SIDE_QUESTION_SYSTEM_REMINDER).text}\n\n{question}"
+    side_message = Message(role="user", content=wrapped)
+
+    toolset = _DenyAllToolset(soul._agent.toolset.tools)  # pyright: ignore[reportPrivateUsage]
+
+    return system_prompt, [*effective_history, side_message], toolset
+
+
+# ---------------------------------------------------------------------------
+# Execution
+# ---------------------------------------------------------------------------
+
+
+async def execute_side_question(
+    soul: PythinkerSoul,
+    question: str,
+    on_text_chunk: Callable[[str], None] | None = None,
+) -> tuple[str | None, str | None]:
+    """Execute a side question and return (response, error).
+
+    Runs up to ``_BTW_MAX_TURNS`` steps.  On the first step, if the LLM
+    returns a tool call instead of text, the denied tool result is appended
+    to the history and a second step gives the LLM another chance.
+
+    Args:
+        soul: The PythinkerSoul instance (for context and chat_provider access).
+        question: The user's side question.
+        on_text_chunk: Optional callback for streaming text chunks.
+
+    Returns:
+        (response_text, None) on success, (None, error_message) on failure.
+    """
+    if soul._runtime.llm is None:  # pyright: ignore[reportPrivateUsage]
+        return None, "LLM is not set."
+
+    try:
+        chat_provider = soul._runtime.llm.chat_provider  # pyright: ignore[reportPrivateUsage]
+        system_prompt, history, toolset = _build_btw_context(soul, question)
+
+        text_chunks: list[str] = []
+
+        def _on_part(part: StreamedMessagePart) -> None:
+            if isinstance(part, TextPart) and part.text:
+                text_chunks.append(part.text)
+                if on_text_chunk is not None:
+                    on_text_chunk(part.text)
+
+        # Multi-turn loop: give the LLM a second chance if it calls tools
+        for turn in range(_BTW_MAX_TURNS):
+            result = await pythinker_core.step(
+                chat_provider,
+                system_prompt,
+                toolset,
+                history,
+                on_message_part=_on_part,
+            )
+
+            # Check for text response — but only accept it if the LLM
+            # didn't also call tools (mixed text+tool = incomplete preamble).
+            response_text = "".join(text_chunks).strip()
+            if response_text and not result.tool_calls:
+                return response_text, None
+
+            # No text — did the LLM try to call a tool?
+            tool_results = await result.tool_results()
+            if not result.tool_calls:
+                break  # No text, no tool calls — give up
+
+            # Tool calls were denied. If we have turns left, feed the error
+            # back so the LLM can try again with text.
+            if turn + 1 < _BTW_MAX_TURNS:
+                # Build the next history: original + assistant message + tool error results
+                history = [
+                    *history,
+                    result.message,
+                    *[_tool_result_to_message(tr) for tr in tool_results],
+                ]
+                text_chunks.clear()  # Reset for next turn
+                continue
+
+            # Last turn and still no text — report the tool call attempt
+            tool_names = [tc.function.name for tc in result.tool_calls]
+            return None, (
+                f"Side question tried to call tools ({', '.join(tool_names)}) "
+                "instead of answering directly. Try rephrasing or ask in the main conversation."
+            )
+
+        return None, "No response received."
+    except Exception as e:
+        logger.warning("Side question failed: {error}", error=e)
+        return None, str(e)
+
+
+def _tool_result_to_message(tool_result: ToolResult) -> Message:
+    """Convert a ToolResult to a tool-result Message for history."""
+    content = tool_result.return_value.message or "Tool call denied."
+    return Message(
+        role="tool",
+        content=content,
+        tool_call_id=tool_result.tool_call_id,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Wire-based entry point (for web UI / non-interactive)
+# ---------------------------------------------------------------------------
+
+
+async def run_side_question(soul: PythinkerSoul, question: str) -> None:
+    """Execute a side question via wire events."""
+    if soul._runtime.llm is None:  # pyright: ignore[reportPrivateUsage]
+        raise LLMNotSet()
+
+    btw_id = uuid.uuid4().hex[:12]
+    wire_send(BtwBegin(id=btw_id, question=question))
+
+    try:
+        response, error = await execute_side_question(soul, question)
+        if response:
+            wire_send(BtwEnd(id=btw_id, response=response))
+        else:
+            wire_send(BtwEnd(id=btw_id, error=error or "No response received."))
+    except Exception as e:
+        logger.warning("Side question failed: {error}", error=e)
+        wire_send(BtwEnd(id=btw_id, error=str(e)))

pythinker_code/soul/compaction.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, NamedTuple, Protocol, runtime_checkable
+
+import pythinker_core
+from pythinker_core.chat_provider import TokenUsage
+from pythinker_core.message import Message
+from pythinker_core.tooling.empty import EmptyToolset
+
+import pythinker_code.prompts as prompts
+from pythinker_code.llm import LLM
+from pythinker_code.soul.message import system
+from pythinker_code.utils.logging import logger
+from pythinker_code.wire.types import ContentPart, TextPart, ThinkPart
+
+
+class CompactionResult(NamedTuple):
+    messages: Sequence[Message]
+    usage: TokenUsage | None
+
+    @property
+    def estimated_token_count(self) -> int:
+        """Estimate the token count of the compacted messages.
+
+        When LLM usage is available, ``usage.output`` gives the exact token count
+        of the generated summary (the first message).  Preserved messages (all
+        subsequent messages) are estimated from their text length.
+
+        When usage is not available (no compaction LLM call was made), all
+        messages are estimated from text length.
+
+        The estimate is intentionally conservative — it will be replaced by the
+        real value on the next LLM call.
+        """
+        if self.usage is not None and len(self.messages) > 0:
+            summary_tokens = self.usage.output
+            preserved_tokens = estimate_text_tokens(self.messages[1:])
+            return summary_tokens + preserved_tokens
+
+        return estimate_text_tokens(self.messages)
+
+
+def estimate_text_tokens(messages: Sequence[Message]) -> int:
+    """Estimate tokens from message text content using a character-based heuristic."""
+    total_chars = 0
+    for msg in messages:
+        for part in msg.content:
+            if isinstance(part, TextPart):
+                total_chars += len(part.text)
+    # ~4 chars per token for English; somewhat underestimates for CJK text,
+    # but this is a temporary estimate that gets corrected on the next LLM call.
+    return total_chars // 4
+
+
+def should_auto_compact(
+    token_count: int,
+    max_context_size: int,
+    *,
+    trigger_ratio: float,
+    reserved_context_size: int,
+) -> bool:
+    """Determine whether auto-compaction should be triggered.
+
+    Returns True when either condition is met (whichever fires first):
+    - Ratio-based: token_count >= max_context_size * trigger_ratio
+    - Reserved-based: token_count + reserved_context_size >= max_context_size
+    """
+    return (
+        token_count >= max_context_size * trigger_ratio
+        or token_count + reserved_context_size >= max_context_size
+    )
+
+
+@runtime_checkable
+class Compaction(Protocol):
+    async def compact(
+        self, messages: Sequence[Message], llm: LLM, *, custom_instruction: str = ""
+    ) -> CompactionResult:
+        """
+        Compact a sequence of messages into a new sequence of messages.
+
+        Args:
+            messages (Sequence[Message]): The messages to compact.
+            llm (LLM): The LLM to use for compaction.
+            custom_instruction: Optional user instruction to guide compaction focus.
+
+        Returns:
+            CompactionResult: The compacted messages and token usage from the compaction LLM call.
+
+        Raises:
+            ChatProviderError: When the chat provider returns an error.
+        """
+        ...
+
+
+if TYPE_CHECKING:
+
+    def type_check(simple: SimpleCompaction):
+        _: Compaction = simple
+
+
+class SimpleCompaction:
+    def __init__(self, max_preserved_messages: int = 2) -> None:
+        self.max_preserved_messages = max_preserved_messages
+
+    async def compact(
+        self, messages: Sequence[Message], llm: LLM, *, custom_instruction: str = ""
+    ) -> CompactionResult:
+        compact_message, to_preserve = self.prepare(messages, custom_instruction=custom_instruction)
+        if compact_message is None:
+            return CompactionResult(messages=to_preserve, usage=None)
+
+        # Call pythinker_core.step to get the compacted context
+        # TODO: set max completion tokens
+        logger.debug("Compacting context...")
+        result = await pythinker_core.step(
+            chat_provider=llm.chat_provider,
+            system_prompt="You are a helpful assistant that compacts conversation context.",
+            toolset=EmptyToolset(),
+            history=[compact_message],
+        )
+        if result.usage:
+            logger.debug(
+                "Compaction used {input} input tokens and {output} output tokens",
+                input=result.usage.input,
+                output=result.usage.output,
+            )
+
+        content: list[ContentPart] = [
+            system("Previous context has been compacted. Here is the compaction output:")
+        ]
+        compacted_msg = result.message
+
+        # drop thinking parts if any
+        content.extend(part for part in compacted_msg.content if not isinstance(part, ThinkPart))
+        compacted_messages: list[Message] = [Message(role="user", content=content)]
+        compacted_messages.extend(to_preserve)
+        return CompactionResult(messages=compacted_messages, usage=result.usage)
+
+    class PrepareResult(NamedTuple):
+        compact_message: Message | None
+        to_preserve: Sequence[Message]
+
+    def prepare(
+        self, messages: Sequence[Message], *, custom_instruction: str = ""
+    ) -> PrepareResult:
+        if not messages or self.max_preserved_messages <= 0:
+            return self.PrepareResult(compact_message=None, to_preserve=messages)
+
+        history = list(messages)
+        preserve_start_index = len(history)
+        n_preserved = 0
+        for index in range(len(history) - 1, -1, -1):
+            if history[index].role in {"user", "assistant"}:
+                n_preserved += 1
+                if n_preserved == self.max_preserved_messages:
+                    preserve_start_index = index
+                    break
+
+        if n_preserved < self.max_preserved_messages:
+            return self.PrepareResult(compact_message=None, to_preserve=messages)
+
+        to_compact = history[:preserve_start_index]
+        to_preserve = history[preserve_start_index:]
+
+        if not to_compact:
+            # Let's hope this won't exceed the context size limit
+            return self.PrepareResult(compact_message=None, to_preserve=to_preserve)
+
+        # Create input message for compaction
+        compact_message = Message(role="user", content=[])
+        for i, msg in enumerate(to_compact):
+            compact_message.content.append(
+                TextPart(text=f"## Message {i + 1}\nRole: {msg.role}\nContent:\n")
+            )
+            compact_message.content.extend(
+                part for part in msg.content if isinstance(part, TextPart)
+            )
+        prompt_text = "\n" + prompts.COMPACT
+        if custom_instruction:
+            prompt_text += (
+                "\n\n**User's Custom Compaction Instruction:**\n"
+                "The user has specifically requested the following focus during compaction. "
+                "You MUST prioritize this instruction above the default compression priorities:\n"
+                f"{custom_instruction}"
+            )
+        compact_message.content.append(TextPart(text=prompt_text))
+        return self.PrepareResult(compact_message=compact_message, to_preserve=to_preserve)