pythinker-code 0.8.0__py3-none-any.whl

pythinker_code/tools/agent/__init__.py

@@ -0,0 +1,326 @@
+import asyncio
+from pathlib import Path
+from typing import Literal, override
+
+from pydantic import BaseModel, Field
+from pythinker_core.tooling import CallableTool2, ToolError, ToolReturnValue
+
+from pythinker_code.soul.agent import Runtime
+from pythinker_code.soul.toolset import get_current_tool_call_or_none
+from pythinker_code.subagents.models import AgentLaunchSpec, AgentTypeDefinition
+from pythinker_code.subagents.runner import ForegroundRunRequest, ForegroundSubagentRunner
+from pythinker_code.tools.utils import load_desc
+from pythinker_code.utils.logging import logger
+
+NAME = "Agent"
+
+MAX_FOREGROUND_TIMEOUT = 60 * 60  # 1 hour
+MAX_BACKGROUND_TIMEOUT = 60 * 60  # 1 hour
+
+
+class Params(BaseModel):
+    description: str = Field(description="A short (3-5 word) description of the task")
+    prompt: str = Field(description="The task for the agent to perform")
+    subagent_type: str = Field(
+        default="coder",
+        description="The built-in agent type to use. Defaults to `coder`.",
+    )
+    model: str | None = Field(
+        default=None,
+        description=(
+            "Optional model override. Selection priority is: this parameter, then the built-in "
+            "type default model, then the parent agent's current model."
+        ),
+    )
+    resume: str | None = Field(
+        default=None,
+        description="Optional agent ID to resume instead of creating a new instance.",
+    )
+    run_in_background: bool = Field(
+        default=False,
+        description=(
+            "Whether to run the agent in the background. Prefer false unless the task can "
+            "continue independently and there is a clear benefit to returning control before "
+            "the result is needed."
+        ),
+    )
+    timeout: int | None = Field(
+        default=None,
+        description=(
+            "Timeout in seconds for the agent task. "
+            "Foreground: no default timeout (runs until completion), max 3600s (1hr). "
+            "Background: default from config (15min), max 3600s (1hr). "
+            "The agent is stopped if it exceeds this limit."
+        ),
+        ge=30,
+        le=MAX_BACKGROUND_TIMEOUT,
+    )
+    dependencies: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Optional background task IDs this task depends on. Metadata only; the parent "
+            "agent should launch dependent tasks after prerequisites are ready."
+        ),
+    )
+    budget_seconds: int | None = Field(
+        default=None,
+        description="Optional budget in seconds for planning/synthesis metadata.",
+        ge=1,
+        le=MAX_BACKGROUND_TIMEOUT,
+    )
+    isolation: Literal["none", "worktree"] = Field(
+        default="none",
+        description=(
+            "Optional isolation request for background agents. `worktree` records a git-worktree "
+            "isolation intent for orchestration/recovery; unsupported callers should leave `none`."
+        ),
+    )
+
+    @property
+    def effective_timeout(self) -> int | None:
+        """Return the user-specified timeout, or None to use the system default."""
+        return self.timeout
+
+
+class AgentTool(CallableTool2[Params]):
+    name: str = NAME
+    params: type[Params] = Params
+
+    def __init__(self, runtime: Runtime):
+        super().__init__(
+            description=load_desc(
+                Path(__file__).parent / "description.md",
+                {
+                    "BUILTIN_AGENT_TYPES_MD": self._builtin_type_lines(runtime),
+                },
+            )
+        )
+        self._runtime = runtime
+
+    @staticmethod
+    def _builtin_type_lines(runtime: Runtime) -> str:
+        lines: list[str] = []
+        for name, type_def in runtime.labor_market.builtin_types.items():
+            tool_names = AgentTool._tool_summary(type_def)
+            model = type_def.default_model or "inherit"
+            suffix = (
+                f" When to use: {AgentTool._normalize_summary(type_def.when_to_use)}"
+                if type_def.when_to_use
+                else ""
+            )
+            background = "yes" if type_def.supports_background else "no"
+            lines.append(
+                f"- `{name}`: {type_def.description} "
+                f"(Tools: {tool_names}, Model: {model}, Background: {background}).{suffix}"
+            )
+        return "\n".join(lines)
+
+    @staticmethod
+    def _normalize_summary(text: str) -> str:
+        return " ".join(text.split())
+
+    @staticmethod
+    def _tool_summary(type_def: AgentTypeDefinition) -> str:
+        if type_def.tool_policy.mode != "allowlist":
+            return "*"
+        if not type_def.tool_policy.tools:
+            return "(none)"
+        return ", ".join(AgentTool._unique_tool_names(type_def.tool_policy.tools))
+
+    @staticmethod
+    def _unique_tool_names(tool_paths: tuple[str, ...]) -> list[str]:
+        names: list[str] = []
+        for path in tool_paths:
+            name = path.split(":")[-1]
+            if name not in names:
+                names.append(name)
+        return names
+
+    @override
+    async def __call__(self, params: Params) -> ToolReturnValue:
+        if self._runtime.role != "root":
+            return ToolError(
+                message="Subagents cannot launch other subagents.",
+                brief="Agent unavailable",
+            )
+        if params.model is not None and params.model not in self._runtime.config.models:
+            return ToolError(
+                message=f"Unknown model alias: {params.model}",
+                brief="Invalid model alias",
+            )
+        if params.run_in_background:
+            return await self._run_in_background(params)
+        timeout = params.effective_timeout
+        try:
+            runner = ForegroundSubagentRunner(self._runtime)
+            req = ForegroundRunRequest(
+                description=params.description,
+                prompt=params.prompt,
+                requested_type=params.subagent_type or "coder",
+                model=params.model,
+                resume=params.resume,
+            )
+            if timeout is not None:
+                return await asyncio.wait_for(runner.run(req), timeout=timeout)
+            return await runner.run(req)
+        except TimeoutError as exc:
+            # Note: TimeoutError from run_soul internals (e.g. aiohttp) is now caught
+            # by run_soul_checked and converted to SoulRunFailure. This handler mainly
+            # covers wait_for's task-level timeout and pre-run_soul TimeoutErrors.
+            if isinstance(exc.__cause__, asyncio.CancelledError):
+                logger.warning("Foreground agent timed out after {t}s", t=timeout)
+                return ToolError(
+                    message=f"Agent timed out after {timeout}s.",
+                    brief=f"Agent timed out ({timeout}s)",
+                )
+            # Internal timeout (e.g. aiohttp request) — treat as generic failure
+            logger.exception("Foreground agent run failed")
+            return ToolError(message=f"Failed to run agent: {exc}", brief="Agent failed")
+        except FileNotFoundError as exc:
+            logger.warning("Foreground agent resume target was not found: {err}", err=exc)
+            return ToolError(message=str(exc), brief="Agent not found")
+        except RuntimeError as exc:
+            if "cannot be resumed concurrently" in str(exc):
+                logger.warning("Foreground agent resume rejected: {err}", err=exc)
+                return ToolError(message=str(exc), brief="Agent already running")
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(exc, site="tool.agent.foreground", tool="Agent")
+            logger.exception("Foreground agent run failed")
+            return ToolError(message=f"Failed to run agent: {exc}", brief="Agent failed")
+        except Exception as exc:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(exc, site="tool.agent.foreground", tool="Agent")
+            logger.exception("Foreground agent run failed")
+            return ToolError(message=f"Failed to run agent: {exc}", brief="Agent failed")
+
+    async def _run_in_background(self, params: Params) -> ToolReturnValue:
+        assert self._runtime.subagent_store is not None
+        try:
+            tool_call = get_current_tool_call_or_none()
+            if tool_call is None:
+                return ToolError(
+                    message="Background agent requires a tool call context.",
+                    brief="No tool call context",
+                )
+
+            requested_type = params.subagent_type or "coder"
+            if params.resume:
+                record = self._runtime.subagent_store.require_instance(params.resume)
+                if record.status in {"running_foreground", "running_background"}:
+                    return ToolError(
+                        message=(
+                            f"Agent instance {record.agent_id} is still {record.status} and cannot "
+                            "be resumed concurrently."
+                        ),
+                        brief="Agent already running",
+                    )
+                actual_type = record.subagent_type
+                agent_id = record.agent_id
+                # Validate the effective model for resumed instances — the model
+                # stored in the launch spec may have been removed from config since
+                # the instance was created.  params.model is already validated in
+                # __call__, so only check the stored effective_model fallback here.
+                if params.model is None:
+                    type_def = self._runtime.labor_market.require_builtin_type(actual_type)
+                    effective = record.launch_spec.effective_model or type_def.default_model
+                    if effective is not None and effective not in self._runtime.config.models:
+                        return ToolError(
+                            message=f"Unknown model alias: {effective}",
+                            brief="Invalid model alias",
+                        )
+            else:
+                actual_type = requested_type
+                import uuid
+
+                agent_id = f"a{uuid.uuid4().hex[:8]}"
+                record = None
+
+            created_instance = False
+            if not params.resume:
+                type_def = self._runtime.labor_market.require_builtin_type(actual_type)
+                self._runtime.subagent_store.create_instance(
+                    agent_id=agent_id,
+                    description=params.description.strip(),
+                    launch_spec=AgentLaunchSpec(
+                        agent_id=agent_id,
+                        subagent_type=actual_type,
+                        model_override=params.model,
+                        effective_model=params.model or type_def.default_model,
+                        thinking=self._runtime.llm.thinking
+                        if self._runtime.llm is not None
+                        else None,
+                    ),
+                )
+                created_instance = True
+
+            # Mark running_background synchronously before dispatching the
+            # async task so that concurrent resume attempts see the guard
+            # immediately (asyncio.create_task only queues the coroutine).
+            self._runtime.subagent_store.update_instance(
+                agent_id,
+                status="running_background",
+            )
+            try:
+                view = self._runtime.background_tasks.create_agent_task(
+                    agent_id=agent_id,
+                    subagent_type=actual_type,
+                    prompt=params.prompt,
+                    description=params.description.strip(),
+                    tool_call_id=tool_call.id,
+                    model_override=params.model,
+                    timeout_s=params.effective_timeout,
+                    resumed=params.resume is not None,
+                    dependencies=params.dependencies,
+                    budget_seconds=params.budget_seconds,
+                    isolation=params.isolation,
+                )
+            except Exception:
+                self._runtime.subagent_store.update_instance(
+                    agent_id,
+                    status="idle",
+                )
+                if created_instance:
+                    self._runtime.subagent_store.delete_instance(agent_id)
+                raise
+            dependency_text = ", ".join(params.dependencies) if params.dependencies else "(none)"
+            budget_text = (
+                str(params.budget_seconds) if params.budget_seconds is not None else "(none)"
+            )
+            lines = [
+                f"task_id: {view.spec.id}",
+                f"kind: {view.spec.kind}",
+                f"status: {view.runtime.status}",
+                f"description: {view.spec.description}",
+                f"agent_id: {agent_id}",
+                f"actual_subagent_type: {actual_type}",
+                f"dependencies: {dependency_text}",
+                f"budget_seconds: {budget_text}",
+                f"isolation: {params.isolation}",
+                f"synthesis_state: {getattr(view.spec, 'synthesis_state', None) or 'pending'}",
+                "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."
+                ),
+                f'resume_hint: Use Agent(resume="{agent_id}", prompt="...") to continue this '
+                "instance later.",
+            ]
+            return ToolReturnValue(
+                is_error=False,
+                output="\n".join(lines),
+                message="Background task started.",
+                display=[],
+            )
+        except FileNotFoundError as exc:
+            return ToolError(message=str(exc), brief="Agent not found")
+        except KeyError as exc:
+            return ToolError(message=str(exc), brief="Invalid subagent type")
+        except RuntimeError as exc:
+            logger.exception("Background agent launch failed")
+            return ToolError(message=str(exc), brief="Background start failed")
+
+
+Agent = AgentTool

pythinker_code/tools/agent/description.md

@@ -0,0 +1,65 @@
+Start a subagent instance to work on a focused task.
+
+The Agent tool can either create a new subagent instance or resume an existing one by `agent_id`.
+Each instance keeps its own context history under the current session, so repeated use of the same
+instance can preserve previous findings and work.
+
+**Available Built-in Agent Types**
+
+${BUILTIN_AGENT_TYPES_MD}
+
+**Usage**
+
+- Always provide a short `description` (3-5 words).
+- Use `subagent_type` to select a built-in agent type. If omitted, `coder` is used.
+- Use `model` when you need to override the built-in type's default model or the parent agent's current model.
+- Use `resume` when you want to continue an existing instance instead of starting a new one.
+- If an existing subagent already has relevant context or the task is a continuation of its prior work, prefer `resume` over creating a new instance.
+- Default to foreground execution. Use `run_in_background=true` only when the task can continue independently, you do not need the result immediately, and there is a clear benefit to returning control before it finishes.
+- Be explicit about whether the subagent should write code, only research, review, or verify.
+- Provide the subagent all required context and success criteria. New subagents do not inherit your transcript automatically.
+- Spawn multiple subagents in the same turn when they can investigate independent regions concurrently.
+- Cross-check at least one load-bearing subagent finding before making changes from it.
+- The subagent result is only visible to you. If the user should see it, summarize it yourself.
+
+**Agent Workflow Design**
+
+Use subagents as focused logical roles, not just extra tool capacity:
+
+- `explore` / scout: collect facts, relevant files, constraints, and risks. Read-only.
+- `plan`: turn gathered context into an implementation plan. Read-only.
+- `coder`: general software engineering work when the brief still needs judgment.
+- `implementer`: land a specific, already-scoped change with minimum edits.
+- `review`: read and grade changed code with severity-scored findings.
+- `verifier`: run validation gates and report PASS / FAIL / FLAKY without fixing.
+
+Recommended workflows:
+
+- Scout → Plan → Implement: run `explore`, then `plan` with the explorer's findings, then `implementer` or `coder` with the plan.
+- Implement → Review → Fix → Verify: run `implementer`, then `review`, then resume/launch `implementer` to apply feedback, then `verifier` for the relevant gate.
+- Parallel scouting: launch multiple `explore` agents for independent questions, then synthesize their findings before editing.
+- Parallel review/verification: when review and tests do not depend on each other, run `review` and `verifier` concurrently.
+
+When chaining manually, include the previous agent's summary in the next agent prompt. Newly-created
+subagents do not see your current context automatically.
+
+**Explore Agent — Preferred for Codebase Research**
+
+When you need to understand the codebase before making changes, fixing bugs, or planning features,
+prefer `subagent_type="explore"` over doing the search yourself. The explore agent is optimized for
+fast, read-only codebase investigation. Use it when:
+- Your task will clearly require more than 3 search queries
+- You need to understand how a module, feature, or code path works
+- You are about to enter plan mode and want to gather context first
+- You want to investigate multiple independent questions — launch multiple explore agents concurrently
+
+When calling explore, specify the desired thoroughness in the prompt:
+- "quick": targeted lookups — find a specific file, function, or config value
+- "medium": understand a module — how does auth work, what calls this API
+- "thorough": cross-cutting analysis — architecture overview, dependency mapping, multi-module investigation
+
+**When Not To Use Agent**
+
+- Reading a known file path
+- Searching a small number of known files
+- Tasks that can be completed in one or two direct tool calls

pythinker_code/tools/ask_user/__init__.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Callable
+from pathlib import Path
+from typing import override
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+from pythinker_core.tooling import BriefDisplayBlock, CallableTool2, ToolError, ToolReturnValue
+
+from pythinker_code.soul import get_wire_or_none, wire_send
+from pythinker_code.soul.toolset import get_current_tool_call_or_none
+from pythinker_code.tools.utils import load_desc
+from pythinker_code.wire.types import (
+    QuestionItem,
+    QuestionNotSupported,
+    QuestionOption,
+    QuestionRequest,
+)
+
+logger = logging.getLogger(__name__)
+
+NAME = "AskUserQuestion"
+
+_BASE_DESCRIPTION = load_desc(Path(__file__).parent / "description.md")
+
+
+class QuestionOptionParam(BaseModel):
+    label: str = Field(
+        description="Concise display text (1-5 words). If recommended, append '(Recommended)'."
+    )
+    description: str = Field(
+        default="",
+        description="Brief explanation of trade-offs or implications of choosing this option.",
+    )
+
+
+class QuestionParam(BaseModel):
+    question: str = Field(description="A specific, actionable question. End with '?'.")
+    header: str = Field(
+        default="", description="Short category tag (max 12 chars, e.g. 'Auth', 'Style')."
+    )
+    options: list[QuestionOptionParam] = Field(
+        description=(
+            "2-4 meaningful, distinct options. Do NOT include an 'Other' option — "
+            "the system adds one automatically."
+        ),
+        min_length=2,
+        max_length=4,
+    )
+    multi_select: bool = Field(
+        default=False,
+        description="Whether the user can select multiple options.",
+    )
+
+
+class Params(BaseModel):
+    questions: list[QuestionParam] = Field(
+        description="The questions to ask the user (1-4 questions).",
+        min_length=1,
+        max_length=4,
+    )
+
+
+class AskUserQuestion(CallableTool2[Params]):
+    name: str = NAME
+    description: str = _BASE_DESCRIPTION
+    params: type[Params] = Params
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._is_auto: Callable[[], bool] | None = None
+
+    def bind_auto(self, is_auto: Callable[[], bool]) -> None:
+        """Late-bind auto-mode checker so we can auto-dismiss when no user is present."""
+        self._is_auto = is_auto
+
+    @override
+    async def __call__(self, params: Params) -> ToolReturnValue:
+        if self._is_auto and self._is_auto():
+            return ToolReturnValue(
+                is_error=False,
+                output=(
+                    '{"answers": {}, "note": "Running in auto mode.'
+                    ' No user is present. Make your own decision."}'
+                ),
+                message="Auto mode, auto-dismissed.",
+                display=[BriefDisplayBlock(text="Auto-dismissed (auto mode)")],
+            )
+
+        wire = get_wire_or_none()
+        if wire is None:
+            return ToolError(
+                message="Cannot ask user questions: Wire is not available.",
+                brief="Wire unavailable",
+            )
+
+        tool_call = get_current_tool_call_or_none()
+        if tool_call is None:
+            return ToolError(
+                message="AskUserQuestion must be called from a tool call context.",
+                brief="Invalid context",
+            )
+
+        questions = [
+            QuestionItem(
+                question=q.question,
+                header=q.header,
+                options=[
+                    QuestionOption(label=o.label, description=o.description) for o in q.options
+                ],
+                multi_select=q.multi_select,
+            )
+            for q in params.questions
+        ]
+
+        request = QuestionRequest(
+            id=str(uuid4()),
+            tool_call_id=tool_call.id,
+            questions=questions,
+        )
+
+        wire_send(request)
+
+        try:
+            answers = await request.wait()
+        except QuestionNotSupported:
+            return ToolError(
+                message=(
+                    "The connected client does not support interactive questions. "
+                    "Do NOT call this tool again. "
+                    "Ask the user directly in your text response instead."
+                ),
+                brief="Client unsupported",
+            )
+        except Exception as exc:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(exc, site="tool.ask_user", tool="AskUser")
+            logger.exception("Failed to get user response for question %s", request.id)
+            return ToolError(
+                message="Failed to get user response.",
+                brief="Question failed",
+            )
+
+        if not answers:
+            return ToolReturnValue(
+                is_error=False,
+                output='{"answers": {}, "note": "User dismissed the question without answering."}',
+                message="User dismissed the question without answering.",
+                display=[BriefDisplayBlock(text="User dismissed")],
+            )
+
+        formatted = json.dumps({"answers": answers}, ensure_ascii=False)
+        return ToolReturnValue(
+            is_error=False,
+            output=formatted,
+            message="User has answered.",
+            display=[BriefDisplayBlock(text="User answered")],
+        )

pythinker_code/tools/ask_user/description.md

@@ -0,0 +1,19 @@
+Use this tool when you need to ask the user questions with structured options during execution. This allows you to:
+1. Collect user preferences or requirements before proceeding
+2. Resolve ambiguous or underspecified instructions
+3. Let the user decide between implementation approaches as you work
+4. Present concrete options when multiple valid directions exist
+
+**When NOT to use:**
+- When you can infer the answer from context — be decisive and proceed
+- Trivial decisions that don't materially affect the outcome
+
+Overusing this tool interrupts the user's flow. Only use it when the user's input genuinely changes your next action.
+
+**Usage notes:**
+- Users always have an "Other" option for custom input — don't create one yourself
+- Use multi_select to allow multiple answers to be selected for a question
+- Keep option labels concise (1-5 words), use descriptions for trade-offs and details
+- Each question should have 2-4 meaningful, distinct options
+- You can ask 1-4 questions at a time; group related questions to minimize interruptions
+- If you recommend a specific option, list it first and append "(Recommended)" to its label