pythinker-code 2.0.0__py3-none-any.whl

pythinker_code/subagents/__init__.py

@@ -0,0 +1,21 @@
+from pythinker_code.subagents.models import (
+    AgentInstanceRecord,
+    AgentLaunchSpec,
+    AgentTypeDefinition,
+    SubagentStatus,
+    ToolPolicy,
+    ToolPolicyMode,
+)
+from pythinker_code.subagents.registry import LaborMarket
+from pythinker_code.subagents.store import SubagentStore
+
+__all__ = [
+    "AgentInstanceRecord",
+    "AgentLaunchSpec",
+    "AgentTypeDefinition",
+    "LaborMarket",
+    "SubagentStatus",
+    "SubagentStore",
+    "ToolPolicy",
+    "ToolPolicyMode",
+]

pythinker_code/subagents/builder.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from pythinker_code.llm import clone_llm_with_model_alias
+from pythinker_code.soul.agent import Agent, Runtime, load_agent
+from pythinker_code.subagents.models import AgentLaunchSpec, AgentTypeDefinition
+
+
+class SubagentBuilder:
+    def __init__(self, root_runtime: Runtime):
+        self._root_runtime = root_runtime
+
+    async def build_builtin_instance(
+        self,
+        *,
+        agent_id: str,
+        type_def: AgentTypeDefinition,
+        launch_spec: AgentLaunchSpec,
+    ) -> Agent:
+        effective_model = self.resolve_effective_model(type_def=type_def, launch_spec=launch_spec)
+        llm_override = clone_llm_with_model_alias(
+            self._root_runtime.llm,
+            self._root_runtime.config,
+            effective_model,
+            session_id=self._root_runtime.session.id,
+            oauth=self._root_runtime.oauth,
+        )
+        runtime = self._root_runtime.copy_for_subagent(
+            agent_id=agent_id,
+            subagent_type=type_def.name,
+            llm_override=llm_override,
+        )
+        return await load_agent(
+            type_def.agent_file,
+            runtime,
+            mcp_configs=[],
+        )
+
+    @staticmethod
+    def resolve_effective_model(
+        *, type_def: AgentTypeDefinition, launch_spec: AgentLaunchSpec
+    ) -> str | None:
+        return launch_spec.model_override or launch_spec.effective_model or type_def.default_model

pythinker_code/subagents/core.py

@@ -0,0 +1,86 @@
+"""Shared core logic for preparing a subagent soul.
+
+Both ``ForegroundSubagentRunner`` and ``BackgroundAgentRunner`` delegate
+the repetitive build-restore-prompt pipeline to :func:`prepare_soul` so
+that prompt enhancements (e.g. git context injection) only need to be
+implemented once.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING
+
+from pythinker_code.soul.context import Context
+from pythinker_code.soul.pythinkersoul import PythinkerSoul
+from pythinker_code.subagents.builder import SubagentBuilder
+from pythinker_code.subagents.models import AgentLaunchSpec, AgentTypeDefinition
+from pythinker_code.subagents.store import SubagentStore
+
+if TYPE_CHECKING:
+    from pythinker_code.soul.agent import Runtime
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SubagentRunSpec:
+    """Everything needed to prepare a soul, without lifecycle concerns."""
+
+    agent_id: str
+    type_def: AgentTypeDefinition
+    launch_spec: AgentLaunchSpec
+    prompt: str
+    resumed: bool
+
+
+async def prepare_soul(
+    spec: SubagentRunSpec,
+    runtime: Runtime,
+    builder: SubagentBuilder,
+    store: SubagentStore,
+    on_stage: Callable[[str], None] | None = None,
+) -> tuple[PythinkerSoul, str]:
+    """Build agent, restore context, handle system prompt, write prompt file.
+
+    Returns ``(soul, final_prompt)`` ready for execution via
+    :func:`run_with_summary_continuation`.
+    """
+
+    # 1. Build agent from type definition
+    agent = await builder.build_builtin_instance(
+        agent_id=spec.agent_id,
+        type_def=spec.type_def,
+        launch_spec=spec.launch_spec,
+    )
+    if on_stage:
+        on_stage("agent_built")
+
+    # 2. Restore conversation context
+    context = Context(store.context_path(spec.agent_id))
+    await context.restore()
+    if on_stage:
+        on_stage("context_restored")
+
+    # 3. System prompt: reuse persisted prompt on resume, persist on first run
+    if context.system_prompt is not None:
+        agent = replace(agent, system_prompt=context.system_prompt)
+    else:
+        await context.write_system_prompt(agent.system_prompt)
+    if on_stage:
+        on_stage("context_ready")
+
+    # 4. For new (non-resumed) explore agents, prepend git context to the prompt
+    prompt = spec.prompt
+    if spec.type_def.name == "explore" and not spec.resumed:
+        from pythinker_code.subagents.git_context import collect_git_context
+
+        git_ctx = await collect_git_context(runtime.builtin_args.PYTHINKER_WORK_DIR)
+        if git_ctx:
+            prompt = f"{git_ctx}\n\n{prompt}"
+
+    # 5. Write prompt snapshot (debugging aid)
+    store.prompt_path(spec.agent_id).write_text(prompt, encoding="utf-8")
+
+    # 6. Create soul
+    soul = PythinkerSoul(agent, context=context)
+    return soul, prompt

pythinker_code/subagents/git_context.py

@@ -0,0 +1,172 @@
+"""Collect git repository context for explore subagents."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from urllib.parse import urlparse
+
+import pythinker_host
+from pythinker_host.path import HostPath
+
+from pythinker_code.utils.logging import logger
+
+_TIMEOUT = 5.0
+_MAX_DIRTY_FILES = 20
+
+
+async def collect_git_context(work_dir: HostPath) -> str:
+    """Collect git context information for the explore agent.
+
+    Returns a formatted ``<git-context>`` block, or an empty string if the
+    directory is not a git repository or all git commands fail.  Every git
+    command is individually guarded so a single failure never breaks the whole
+    collection.
+    """
+    cwd = str(work_dir)
+
+    # Quick check: is this a git repo?
+    if await _run_git(["rev-parse", "--is-inside-work-tree"], cwd) is None:
+        return ""
+
+    # Run all git commands in parallel for speed
+    remote_url, branch, dirty_raw, log_raw = await asyncio.gather(
+        _run_git(["remote", "get-url", "origin"], cwd),
+        _run_git(["branch", "--show-current"], cwd),
+        _run_git(["status", "--porcelain"], cwd),
+        _run_git(["log", "-3", "--format=%h %s"], cwd),
+    )
+
+    sections: list[str] = []
+    sections.append(f"Working directory: {cwd}")
+
+    # Remote origin & project name
+    if remote_url:
+        safe_url = _sanitize_remote_url(remote_url)
+        if safe_url:
+            sections.append(f"Remote: {safe_url}")
+        project = _parse_project_name(remote_url)
+        if project:
+            sections.append(f"Project: {project}")
+
+    # Current branch
+    if branch:
+        sections.append(f"Branch: {branch}")
+
+    # Dirty files
+    if dirty_raw is not None:
+        dirty_lines = [line for line in dirty_raw.splitlines() if line.strip()]
+        if dirty_lines:
+            total = len(dirty_lines)
+            shown = dirty_lines[:_MAX_DIRTY_FILES]
+            header = f"Dirty files ({total}):"
+            body = "\n".join(f"  {line}" for line in shown)
+            if total > _MAX_DIRTY_FILES:
+                body += f"\n  ... and {total - _MAX_DIRTY_FILES} more"
+            sections.append(f"{header}\n{body}")
+
+    # Recent commits
+    if log_raw:
+        log_lines = [line for line in log_raw.splitlines() if line.strip()]
+        if log_lines:
+            body = "\n".join(f"  {line[:200]}" for line in log_lines)
+            sections.append(f"Recent commits:\n{body}")
+
+    if len(sections) <= 1:
+        # Only the working directory line — nothing useful collected
+        return ""
+
+    content = "\n".join(sections)
+    return f"<git-context>\n{content}\n</git-context>"
+
+
+async def _run_git(args: list[str], cwd: str, timeout: float = _TIMEOUT) -> str | None:
+    """Run one git command via pythinker_host.exec.
+
+    Return stripped stdout, or None on failure.
+
+    Uses ``git -C <cwd>`` so the command runs in the specified directory
+    regardless of the host backend's current working directory.  Works
+    transparently on both local and remote (SSH) backends.
+    """
+    proc = None
+    try:
+        proc = await pythinker_host.exec("git", "-C", cwd, *args)
+        proc.stdin.close()
+        stdout_bytes = await asyncio.wait_for(proc.stdout.read(-1), timeout=timeout)
+        exit_code = await asyncio.wait_for(proc.wait(), timeout=timeout)
+        if exit_code != 0:
+            return None
+        return stdout_bytes.decode("utf-8", errors="replace").strip()
+    except TimeoutError:
+        logger.debug("git {args} timed out after {t}s", args=args, t=timeout)
+        if proc is not None:
+            await proc.kill()
+            await proc.wait()
+        return None
+    except Exception:
+        logger.debug("git {args} failed", args=args)
+        if proc is not None and proc.returncode is None:
+            await proc.kill()
+            await proc.wait()
+        return None
+
+
+# Well-known public hosts whose remote URLs are safe to surface and
+# recognizable enough for the model to infer project ecosystem context.
+_ALLOWED_HOSTS = (
+    "github.com",
+    "gitlab.com",
+    "gitee.com",
+    "bitbucket.org",
+    "codeberg.org",
+    "sr.ht",
+)
+
+
+def _sanitize_remote_url(remote_url: str) -> str | None:
+    """Return the remote URL if it points to a well-known public host.
+
+    Credentials are stripped from HTTPS URLs.
+
+    Recognizable remote URLs help orient the agent within the broader project
+    ecosystem (e.g. issue tracker conventions, CI patterns).  Self-hosted or
+    unrecognized hosts are excluded to avoid leaking internal infrastructure.
+    """
+    # SSH format: git@host:owner/repo.git — no credentials possible
+    for host in _ALLOWED_HOSTS:
+        if re.match(rf"^git@{re.escape(host)}:", remote_url):
+            return remote_url
+
+    # HTTPS format: parse hostname exactly, strip userinfo
+    try:
+        parsed = urlparse(remote_url)
+        _ = parsed.port  # raises ValueError on malformed port like :443.evil
+    except ValueError:
+        return None
+    if parsed.hostname in _ALLOWED_HOSTS:
+        # Rebuild without userinfo: https://host[:port]/path
+        port_part = f":{parsed.port}" if parsed.port else ""
+        return f"https://{parsed.hostname}{port_part}{parsed.path}"
+
+    return None
+
+
+def _parse_project_name(remote_url: str) -> str | None:
+    """Extract ``owner/repo`` from a git remote URL.
+
+    Supports typical SSH (e.g. ``git@github.com:owner/repo.git``,
+    ``git@gitlab.com:owner/repo.git``) and HTTPS (e.g.
+    ``https://github.com/owner/repo.git``,
+    ``https://gitee.com/owner/repo.git``) formats by taking the
+    trailing ``owner/repo`` component regardless of host.
+    """
+    # SSH format: git@host:owner/repo.git
+    m = re.search(r":([^/]+/[^/]+?)(?:\.git)?$", remote_url)
+    if m:
+        return m.group(1)
+    # HTTPS format: https://host/owner/repo.git
+    m = re.search(r"/([^/]+/[^/]+?)(?:\.git)?$", remote_url)
+    if m:
+        return m.group(1)
+    return None

pythinker_code/subagents/models.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+type ToolPolicyMode = Literal["inherit", "allowlist"]
+type SubagentStatus = Literal[
+    "idle",
+    "running_foreground",
+    "running_background",
+    "completed",
+    "failed",
+    "killed",
+]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ToolPolicy:
+    mode: ToolPolicyMode
+    tools: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AgentTypeDefinition:
+    name: str
+    description: str
+    agent_file: Path
+    when_to_use: str = ""
+    default_model: str | None = None
+    tool_policy: ToolPolicy = field(default_factory=lambda: ToolPolicy(mode="inherit"))
+    supports_background: bool = True
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AgentLaunchSpec:
+    agent_id: str
+    subagent_type: str
+    model_override: str | None
+    effective_model: str | None
+    created_at: float = field(default_factory=time.time)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AgentInstanceRecord:
+    agent_id: str
+    subagent_type: str
+    status: SubagentStatus
+    description: str
+    created_at: float
+    updated_at: float
+    last_task_id: str | None
+    launch_spec: AgentLaunchSpec

pythinker_code/subagents/output.py

@@ -0,0 +1,71 @@
+"""Unified output writer for subagent executions (foreground and background)."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from pythinker_core.message import TextPart, ToolCall, ToolCallPart
+from pythinker_core.tooling import ToolResult
+
+
+class SubagentOutputWriter:
+    """Appends human-readable transcript lines to one or more output files.
+
+    Both foreground and background runners use this so the output format
+    is identical regardless of execution mode.  When *extra_paths* are
+    provided every write is tee'd to those files as well (used by the
+    background agent runner to keep the task ``output.log`` in sync with
+    the canonical subagent output).
+    """
+
+    def __init__(self, path: Path, *, extra_paths: Sequence[Path] = ()) -> None:
+        self._path = path
+        self._extra_paths = extra_paths
+
+    def stage(self, name: str) -> None:
+        self._append(f"[stage] {name}\n")
+
+    def tool_call(self, tc: ToolCall) -> None:
+        name = tc.function.name if tc.function else "?"
+        self._append(f"[tool] {name}\n")
+
+    def tool_result(self, tr: ToolResult) -> None:
+        status = "error" if tr.return_value.is_error else "success"
+        brief = getattr(tr.return_value, "brief", None)
+        if brief:
+            self._append(f"[tool_result] {status}: {brief}\n")
+        else:
+            self._append(f"[tool_result] {status}\n")
+
+    def text(self, text: str) -> None:
+        if text:
+            self._append(text)
+
+    def summary(self, text: str) -> None:
+        if text:
+            self._append(f"\n[summary]\n{text}\n")
+
+    def error(self, message: str) -> None:
+        self._append(f"[error] {message}\n")
+
+    def write_wire_message(self, msg: object) -> None:
+        """Dispatch a wire message to the appropriate writer method."""
+        if isinstance(msg, TextPart):
+            self.text(msg.text)
+        elif isinstance(msg, ToolCall):
+            self.tool_call(msg)
+        elif isinstance(msg, ToolResult):
+            self.tool_result(msg)
+        elif isinstance(msg, ToolCallPart):
+            pass  # incremental argument chunks — not useful in transcript
+
+    def _append(self, text: str) -> None:
+        with self._path.open("a", encoding="utf-8") as f:
+            f.write(text)
+        for p in self._extra_paths:
+            try:
+                with p.open("a", encoding="utf-8") as f:
+                    f.write(text)
+            except OSError:
+                pass  # best-effort — never interrupt the agent for a tee failure

pythinker_code/subagents/registry.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from pythinker_code.subagents.models import AgentTypeDefinition
+
+
+class LaborMarket:
+    """Registry of built-in subagent types."""
+
+    def __init__(self) -> None:
+        self._builtin_types: dict[str, AgentTypeDefinition] = {}
+
+    @property
+    def builtin_types(self) -> Mapping[str, AgentTypeDefinition]:
+        return self._builtin_types
+
+    def add_builtin_type(self, type_def: AgentTypeDefinition) -> None:
+        self._builtin_types[type_def.name] = type_def
+
+    def get_builtin_type(self, name: str) -> AgentTypeDefinition | None:
+        return self._builtin_types.get(name)
+
+    def require_builtin_type(self, name: str) -> AgentTypeDefinition:
+        type_def = self.get_builtin_type(name)
+        if type_def is None:
+            raise KeyError(f"Builtin subagent type not found: {name}")
+        return type_def