feat: add python tool timeout param

[Fronut]

Fixes #7952
Refs #7925
This PR implements LLM-controlled timeouts for Python execution tools. The previous local Python execution timeout was effectively hardcoded at 30 seconds, not configurable and not LLM-controlled. Following maintainer @Soulter 's guidance, the timeout is now provided as a tool parameter and capped by the global tool_call_timeout so all tools respect the same upper bound.

Modifications / 改动点

• Expose a timeout parameter on astrbot_execute_python and astrbot_execute_ipython.

• Clamp per-call timeout to tool_call_timeout and fall back to the global limit when omitted or invalid.

• Core file modified: astrbot/core/tools/computer_tools/python.py

• This is NOT a breaking change. / 这不是一个破坏性变更。

Screenshots or Test Results / 运行截图或测试结果

ruff format .
ruff check .

---

Checklist / 检查清单

• 😊 If there are new features added in the PR, I have discussed it with the authors through issues/emails, etc.
  / 如果 PR 中有新加入的功能，已经通过 Issue / 邮件等方式和作者讨论过。

• 👀 My changes have been well-tested, and "Verification Steps" and "Screenshots" have been provided above.
  / 我的更改经过了良好的测试，并已在上方提供了“验证步骤”和“运行截图”。

• 🤓 I have ensured that no new dependencies are introduced, OR if new dependencies are introduced, they have been added to the appropriate locations in requirements.txt and pyproject.toml.
  / 我确保没有引入新依赖库，或者引入了新依赖库的同时将其添加到 requirements.txt 和 pyproject.toml 文件相应位置。

• 😮 My changes do not introduce malicious code.
  / 我的更改没有引入恶意代码。

Summary by Sourcery

Add LLM-controlled, per-call timeouts to Python execution tools while respecting the global tool_call_timeout cap.

New Features:

• Expose an optional timeout parameter on the astrbot Python and local Python execution tools to control per-call execution duration.

Enhancements:

• Clamp the per-call Python execution timeout to the global tool_call_timeout and fall back to the global limit when the parameter is omitted or invalid.

Summary by Sourcery

Add LLM-controlled per-call timeouts to Python execution tools while respecting the global tool_call_timeout cap.

New Features:

• Expose an optional timeout parameter on the remote and local Python execution tools to control per-call code execution duration.

Enhancements:

• Derive an effective timeout per call that falls back to the global tool_call_timeout and clamps user-specified values to this upper bound.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• The timeout computation logic is duplicated in both PythonTool.call and LocalPythonTool.call; consider extracting a small helper (e.g., _compute_effective_timeout(context, timeout)) to keep the behavior consistent and easier to maintain.
• The parameter schema uses a default of 0 while the function signatures use timeout: int | None = None and then special-case None; you could simplify and align these by using timeout: int = 0 and treating <= 0 as "use tool_call_timeout" to remove the None branch.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The timeout computation logic is duplicated in both PythonTool.call and LocalPythonTool.call; consider extracting a small helper (e.g., _compute_effective_timeout(context, timeout)) to keep the behavior consistent and easier to maintain.
- The parameter schema uses a default of 0 while the function signatures use timeout: int | None = None and then special-case None; you could simplify and align these by using timeout: int = 0 and treating <= 0 as "use tool_call_timeout" to remove the None branch.

## Individual Comments

### Comment 1
<location path="astrbot/core/tools/computer_tools/python.py" line_range="97" />
<code_context>
             context.context.context,
             context.context.event.unified_msg_origin,
         )
+        effective_timeout = context.tool_call_timeout
+        if timeout is not None:
+            try:
</code_context>
<issue_to_address>
**issue (complexity):** Consider extracting a shared helper to compute the effective timeout and reuse it in both tools to avoid duplicated timeout-handling logic.

You can simplify the timeout handling and remove duplication without changing behavior.

1. Extract a shared helper for the timeout semantics:

```python
def _get_effective_timeout(
    context: ContextWrapper[AstrAgentContext],
    timeout: int | None,
) -> int:
    # None or <= 0 → use tool_call_timeout
    if not timeout or timeout <= 0:
        return context.tool_call_timeout
    # cap at tool_call_timeout
    return min(timeout, context.tool_call_timeout)
```

2. Use this helper in both tools and drop the `int()` casting / try-except, relying on the schema’s integer type:

```python
async def call(
    self,
    context: ContextWrapper[AstrAgentContext],
    code: str,
    silent: bool = False,
    timeout: int | None = None,
) -> ToolExecResult:
    if permission_error := check_admin_permission(context, "Python execution"):
        return permission_error

    sb = await get_booter(
        context.context.context,
        context.context.event.unified_msg_origin,
    )
    effective_timeout = _get_effective_timeout(context, timeout)

    try:
        result = await sb.python.exec(
            code,
            timeout=effective_timeout,
            silent=silent,
        )
        return await handle_result(result, context.context.event)
    except Exception as e:
        return f"Error executing code: {str(e)}"
```

Apply the same pattern in `LocalPythonTool.call`:

```python
sb = get_local_booter()
effective_timeout = _get_effective_timeout(context, timeout)
```

This keeps all current semantics (schema default `0`, `None` allowed in signature, capping to `tool_call_timeout`) while reducing duplication and cognitive load.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[gemini-code-assist]

Code Review

This pull request introduces an optional timeout parameter to the PythonTool and LocalPythonTool classes, allowing users to specify an execution time limit that is capped by the system's tool_call_timeout. The reviewer noted that the logic for calculating the effective timeout is duplicated across both tool implementations and recommended refactoring this logic into a shared helper function to improve maintainability and simplify the code.

[Fronut]

@Soulter According to your advice in #7925 , I have submitted a new PR expecting for your review.

[Fronut]

@sourcery-ai review

[Fronut]

/gemini review

[sourcery-ai]

Hey - I've left some high level feedback:

• The effective_timeout calculation is duplicated between PythonTool and LocalPythonTool; consider extracting this into a small shared helper (e.g., compute_effective_timeout(timeout, context.tool_call_timeout)) to keep behavior consistent and reduce future maintenance overhead.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The `effective_timeout` calculation is duplicated between `PythonTool` and `LocalPythonTool`; consider extracting this into a small shared helper (e.g., `compute_effective_timeout(timeout, context.tool_call_timeout)`) to keep behavior consistent and reduce future maintenance overhead.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[gemini-code-assist]

Code Review

This pull request introduces an optional timeout parameter for Python execution tools, allowing for more granular control over code execution duration. The logic for calculating the effective timeout, which ensures the provided value does not exceed the system's default limit, is implemented in both PythonTool and LocalPythonTool. A review comment suggests refactoring this duplicated logic into a shared helper function to improve maintainability.