pythinker-code 0.8.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,43 @@
+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,
+            thinking=launch_spec.thinking,
+        )
+        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/discovery.py

@@ -0,0 +1,234 @@
+"""Discovery for markdown-defined subagents from Claude/Agents-style directories."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal, cast
+
+import yaml
+from pythinker_host.path import HostPath
+
+from pythinker_code.subagents.models import AgentTypeDefinition, ToolPolicy
+from pythinker_code.utils.frontmatter import parse_frontmatter, strip_frontmatter
+from pythinker_code.utils.logging import logger
+from pythinker_code.utils.path import find_project_root
+
+AgentScope = Literal["project"]
+
+CLAUDE_TOOL_MAP: dict[str, str] = {
+    "Agent": "pythinker_code.tools.agent:Agent",
+    "Bash": "pythinker_code.tools.shell:Shell",
+    "Edit": "pythinker_code.tools.file:StrReplaceFile",
+    "Fetch": "pythinker_code.tools.web:FetchURL",
+    "Glob": "pythinker_code.tools.file:Glob",
+    "Grep": "pythinker_code.tools.file:Grep",
+    "Read": "pythinker_code.tools.file:ReadFile",
+    "TodoWrite": "pythinker_code.tools.todo:SetTodoList",
+    "WebFetch": "pythinker_code.tools.web:FetchURL",
+    "WebSearch": "pythinker_code.tools.web:SearchWeb",
+    "Write": "pythinker_code.tools.file:WriteFile",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class ScopedAgentRoot:
+    root: HostPath
+    scope: AgentScope
+
+
+@dataclass(frozen=True, slots=True)
+class MarkdownAgentSpec:
+    name: str
+    description: str
+    prompt_file: HostPath
+    scope: AgentScope
+    tools: tuple[str, ...] | None = None
+    model: str | None = None
+    when_to_use: str = ""
+
+
+def _project_agent_dir_candidates(project_root: HostPath) -> tuple[HostPath, ...]:
+    return (
+        project_root / ".pythinker" / "agents",
+        project_root / ".claude" / "agents",
+        project_root / ".agents" / "agents",
+        project_root / ".codex" / "agents",
+    )
+
+
+async def resolve_agent_roots(work_dir: HostPath) -> list[ScopedAgentRoot]:
+    """Return existing markdown-agent roots in priority order."""
+    project_root = await find_project_root(work_dir)
+    roots: list[ScopedAgentRoot] = []
+    seen: set[str] = set()
+
+    async def add_existing(candidates: Iterable[HostPath], scope: AgentScope) -> None:
+        for candidate in candidates:
+            try:
+                if not await candidate.is_dir():
+                    continue
+                canon = candidate.canonical()
+            except OSError as exc:
+                logger.info("Skipping agent directory {path}: {error}", path=candidate, error=exc)
+                continue
+            key = str(canon)
+            if key in seen:
+                continue
+            seen.add(key)
+            roots.append(ScopedAgentRoot(root=canon, scope=scope))
+
+    await add_existing(_project_agent_dir_candidates(project_root), "project")
+    return roots
+
+
+async def discover_markdown_agents(roots: Iterable[ScopedAgentRoot]) -> list[MarkdownAgentSpec]:
+    """Discover Claude/Agents-style ``*.md`` subagent definitions."""
+    by_name: dict[str, MarkdownAgentSpec] = {}
+    for scoped in roots:
+        try:
+            async for entry in scoped.root.iterdir():
+                if not entry.name.lower().endswith(".md"):
+                    continue
+                try:
+                    if await entry.is_dir():
+                        continue
+                    content = await entry.read_text(encoding="utf-8")
+                    spec = parse_markdown_agent(content, prompt_file=entry, scope=scoped.scope)
+                except Exception as exc:
+                    logger.info(
+                        "Skipping invalid markdown agent {path}: {error}",
+                        path=entry,
+                        error=exc,
+                    )
+                    continue
+                by_name.setdefault(spec.name.casefold(), spec)
+        except OSError as exc:
+            logger.warning(
+                "Failed to iterate agent directory {path}: {error}",
+                path=scoped.root,
+                error=exc,
+            )
+    return sorted(by_name.values(), key=lambda s: s.name)
+
+
+def parse_markdown_agent(
+    content: str,
+    *,
+    prompt_file: HostPath,
+    scope: AgentScope,
+) -> MarkdownAgentSpec:
+    """Parse a Claude-style markdown agent file."""
+    fm = parse_frontmatter(content) or {}
+    default_name = Path(prompt_file.name).stem
+    name = _as_nonempty_str(fm.get("name")) or default_name
+    description = _as_nonempty_str(fm.get("description")) or _first_body_line(content) or ""
+    model = _as_nonempty_str(fm.get("model"))
+    when_to_use = _as_nonempty_str(fm.get("when_to_use")) or description
+    tools = _map_tools(fm.get("tools"), source=prompt_file)
+    return MarkdownAgentSpec(
+        name=name,
+        description=description,
+        prompt_file=prompt_file,
+        scope=scope,
+        tools=tools,
+        model=model,
+        when_to_use=when_to_use,
+    )
+
+
+def materialize_markdown_agent_specs(
+    agents: Iterable[MarkdownAgentSpec],
+    *,
+    output_dir: Path,
+    available_models: set[str] | None = None,
+) -> list[AgentTypeDefinition]:
+    """Write small Pythinker YAML wrappers and return registered type definitions."""
+    output_dir.mkdir(parents=True, exist_ok=True)
+    type_defs: list[AgentTypeDefinition] = []
+    for agent in agents:
+        filename = _safe_filename(agent.name)
+        wrapper_path = output_dir / f"{filename}.yaml"
+        prompt_path = output_dir / f"{filename}.system.md"
+        try:
+            prompt_text = Path(str(agent.prompt_file)).read_text(encoding="utf-8")
+        except OSError as exc:
+            logger.warning(
+                "Failed to read markdown agent prompt {path}: {error}",
+                path=agent.prompt_file,
+                error=exc,
+            )
+            prompt_text = ""
+        prompt_path.write_text(strip_frontmatter(prompt_text).strip(), encoding="utf-8")
+        payload: dict[str, Any] = {
+            "version": 1,
+            "agent": {
+                "extend": "default",
+                "name": agent.name,
+                "system_prompt_path": str(prompt_path),
+                "when_to_use": agent.when_to_use,
+            },
+        }
+        model = agent.model if available_models is None or agent.model in available_models else None
+        if model:
+            payload["agent"]["model"] = model
+        if agent.tools is not None:
+            payload["agent"]["allowed_tools"] = list(agent.tools)
+        wrapper_path.write_text(yaml.safe_dump(payload, sort_keys=False), encoding="utf-8")
+        policy = (
+            ToolPolicy(mode="allowlist", tools=agent.tools)
+            if agent.tools is not None
+            else ToolPolicy(mode="inherit")
+        )
+        type_defs.append(
+            AgentTypeDefinition(
+                name=agent.name,
+                description=agent.description,
+                agent_file=wrapper_path,
+                when_to_use=agent.when_to_use,
+                default_model=model,
+                tool_policy=policy,
+            )
+        )
+    return type_defs
+
+
+def _map_tools(value: Any, *, source: HostPath) -> tuple[str, ...] | None:
+    if value is None:
+        return None
+    if not isinstance(value, list):
+        logger.info("Ignoring non-list tools field in markdown agent {path}", path=source)
+        return None
+    mapped: list[str] = []
+    for item in cast(list[Any], value):
+        if not isinstance(item, str):
+            continue
+        tool = CLAUDE_TOOL_MAP.get(item)
+        if tool is None:
+            logger.warning(
+                "Ignoring unknown markdown-agent tool {tool} in {path}",
+                tool=item,
+                path=source,
+            )
+            continue
+        if tool not in mapped:
+            mapped.append(tool)
+    return tuple(mapped)
+
+
+def _as_nonempty_str(value: Any) -> str | None:
+    return value.strip() if isinstance(value, str) and value.strip() else None
+
+
+def _first_body_line(content: str) -> str | None:
+    for line in strip_frontmatter(content).splitlines():
+        stripped = line.strip()
+        if stripped and stripped != "---":
+            return stripped
+    return None
+
+
+def _safe_filename(name: str) -> str:
+    safe = "".join(ch if ch.isalnum() or ch in "._-" else "_" for ch in name).strip("._")
+    return safe or "agent"

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,56 @@
+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
+    thinking: bool | None = None
+    variant: str | None = 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