python-agent-harness 1.5.0__py3-none-any.whl

python_agent_harness/subagent.py

@@ -0,0 +1,61 @@
+"""Sub-agent runner: delegated agent tasks with error containment.
+
+Mirrors gptel-agent-harness-agent.el: unexpected response shapes become
+error strings fed back to the parent instead of crashing it.  In plan
+mode, sub-agents receive the read-only reminder.
+"""
+
+from __future__ import annotations
+
+from . import config
+from .agent import run_agent_loop
+from .models import Message
+from .prompts import load_agent_prompt
+
+
+def _subagent_system_prompt(session: object) -> str | None:
+    """The sub-agent's system prompt: its OWN prompt only.
+
+    Never falls back to the parent's `system_prompt` (which carries the
+    parent's project context and task-completion rules) — a sub-agent
+    must not inherit any context from the parent.  When the session has
+    no sub-agent prompt configured, the default bundled one is used.
+    """
+    own = getattr(session, "subagent_system_prompt", None)
+    if own:
+        return own
+    return load_agent_prompt(config.DEFAULT_SUBAGENT_PROMPT_FILE)
+
+
+def run_subagent(
+    parent_session: object,
+    description: str,
+    prompt: str,
+    client: object | None = None,
+) -> str:
+    """Run a sub-agent task; return a result string (never raises).
+
+    ``client`` (when given) is the per-invocation dedicated client
+    (see ``Session.run_subagent``); the loop falls back to the
+    session's shared sub-agent client otherwise.
+    """
+    session = parent_session
+    try:
+        messages = [Message(role="user", content=prompt)]
+        # NOTE: the plan-mode read-only reminder is injected by the agent
+        # loop itself (`AgentLoop._inject_pending_prompts`, once per
+        # sub-agent loop) — do NOT insert it here as well, or it appears
+        # twice in the request.
+        result = run_agent_loop(
+            session=session,
+            messages=messages,
+            top_level=False,
+            system=_subagent_system_prompt(session),
+            max_rounds=config.SUBAGENT_MAX_ROUNDS,
+            client=client,
+        )
+        if isinstance(result, str):
+            return result
+        return f"Error: Task {description!r} returned an unexpected response {result!r}"
+    except Exception as e:  # noqa: BLE001 - containment boundary
+        return f'Error: Task "{description}" returned an unexpected response — {e}'

python_agent_harness/token_estimator.py

@@ -0,0 +1,125 @@
+"""Token estimation and calibration, ported from gptel-agent-harness.el.
+
+Estimates are heuristic (Latin ~4 chars/token, CJK ~2 chars/token);
+a calibration factor derived from API-reported input tokens is applied
+to reduce drift.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+from . import config
+
+
+def is_cjk_char(c: str) -> bool:
+    """Return True if C is a CJK or full-width character."""
+    cp = ord(c)
+    return (
+        0x3000 <= cp <= 0x9FFF  # CJK + kana + punctuation
+        or 0xF900 <= cp <= 0xFAFF  # CJK compat ideographs
+        or 0xFF00 <= cp <= 0xFFEF  # full-width forms
+        or 0x20000 <= cp <= 0x2FA1F  # CJK extensions B-F
+    )
+
+
+# The same ranges as `is_cjk_char`, as a single compiled character class.
+# Scanning for CJK runs in C (the regex engine) instead of a per-character
+# Python loop, so large payloads count CJK chars much faster.
+_CJK_RE = re.compile(r"[\u3000-\u9fff\uf900-\ufaff\uff00-\uffef\U00020000-\U0002fa1f]")
+
+
+def estimate_tokens(text: str) -> int:
+    """Estimate tokens in TEXT: Latin ~4 chars/token, CJK ~2 chars/token."""
+    if not text:
+        return 0
+    cjk = len(_CJK_RE.findall(text))
+    latin = len(text) - cjk
+    return round(latin / 4.0 + cjk / 2.0)
+
+
+def context_window_for(model: str) -> int:
+    """Return the context window for MODEL, or a safe fallback.
+
+    Entries are matched in order using substring matching, so more
+    specific patterns must come before general ones (see config).
+    """
+    lowered = model.lower()
+    for pattern, size in config.CONTEXT_WINDOWS:
+        if pattern in lowered:
+            return size
+    return config.DEFAULT_CONTEXT_WINDOW
+
+
+class TokenCalibrator:
+    """Calibration factor: actual_tokens / estimated_tokens.
+
+    Updated after each response using the API-reported input token
+    count.  Applied to future estimations to reduce drift.  Clamped
+    to [CALIBRATION_MIN, CALIBRATION_MAX] to avoid pathological values.
+    """
+
+    def __init__(self) -> None:
+        self.factor = 1.0
+        self.last_raw_estimate: int | None = None
+
+    def update(self, actual_input: int | None) -> None:
+        raw = self.last_raw_estimate
+        if actual_input is None or actual_input <= 0 or raw is None or raw <= 0:
+            return
+        ratio = actual_input / float(raw)
+        ratio = max(config.CALIBRATION_MIN, min(config.CALIBRATION_MAX, ratio))
+        self.factor = ratio
+
+    def calibrate(self, estimated: int) -> int:
+        return round(estimated * self.factor)
+
+
+def payload_text(system: object, messages: list[dict], tools: list[dict]) -> str:
+    """Serialize the full prompt payload into one plain-text buffer."""
+    buf: list[str] = []
+    if isinstance(system, str):
+        buf.append(system)
+    elif isinstance(system, dict) and isinstance(system.get("parts"), list):
+        for part in system["parts"]:
+            if isinstance(part, dict) and isinstance(part.get("text"), str):
+                buf.append(part["text"])
+    elif isinstance(system, list):
+        for s in system:
+            if isinstance(s, str):
+                buf.append(s)
+            elif isinstance(s, dict) and isinstance(s.get("text"), str):
+                buf.append(s["text"])
+    for msg in messages:
+        content = msg.get("content")
+        if isinstance(content, str):
+            buf.append(content)
+        elif isinstance(content, list):
+            for p in content:
+                if isinstance(p, str):
+                    buf.append(p)
+                elif isinstance(p, dict):
+                    for key in ("thinking", "text", "arguments"):
+                        v = p.get(key)
+                        if isinstance(v, str):
+                            buf.append(v)
+                            break
+        reasoning = msg.get("reasoning_content")
+        if isinstance(reasoning, str):
+            buf.append(reasoning)
+        for tc in msg.get("tool_calls") or []:
+            fn = tc.get("function", {}) if isinstance(tc, dict) else {}
+            name = fn.get("name") if isinstance(fn, dict) else None
+            args = fn.get("arguments") if isinstance(fn, dict) else None
+            if isinstance(name, str):
+                buf.append(name)
+            if isinstance(args, str):
+                buf.append(args)
+    for tool in tools:
+        buf.append(json.dumps(tool, separators=(",", ":")))
+    return "\n".join(buf)
+
+
+def estimate_payload_tokens(system: object, messages: list[dict], tools: list[dict]) -> int:
+    return estimate_tokens(payload_text(system, messages, tools))

python_agent_harness/tool_runner.py

@@ -0,0 +1,247 @@
+"""Tool execution for the agent FSM: run/deliver tool calls, salvage history.
+
+Extracted from agent.py (no logic changes): the FSM driver delegates
+tool plumbing to ``ToolRunner``, which reads/writes the loop's shared
+state (``messages`` / ``pending`` / ``info``) through the loop
+reference.  Tool calls are always executed and delivered via the
+loop's ``_execute_tool_call`` / ``_deliver_tool_result`` methods so
+subclass or test overrides of those methods keep working.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any
+
+from . import config
+from .models import Message, ToolCall
+from .tools.base import PendingToolResult
+
+NIL_RESULT_PLACEHOLDER = (
+    "Error: tool produced no result (it may have been interrupted or failed to return)."
+)
+
+
+def sanitize_tool_result(result: object) -> str:
+    """Sanitize a tool result for the model.
+
+    - str (incl. empty) kept as-is
+    - None -> error placeholder (backends reject JSON null content)
+    - anything else -> str()
+    """
+    if result is None:
+        return NIL_RESULT_PLACEHOLDER
+    if isinstance(result, str):
+        return result
+    return str(result)
+
+
+class ToolRunner:
+    """Runs and delivers tool calls for one agent loop.
+
+    Mirrors gptel's `gptel--handle-tool-use': synchronous tools
+    (Read, Edit, Glob, ...) execute ONE AT A TIME, in call order;
+    asynchronous tools (Bash, Agent — those whose ``run`` returns a
+    ``PendingToolResult``) are dispatched in line and run concurrently
+    in the background, their results awaited afterwards, again in
+    original call order.
+    """
+
+    def __init__(self, loop: Any) -> None:
+        self.loop = loop
+
+    def execute_tool_call(self, call: ToolCall) -> str | PendingToolResult:
+        loop = self.loop
+        if not loop.top_level and call.name in config.SUBAGENT_EXCLUDED_TOOLS:
+            # defense in depth: a hallucinated call must never reach the
+            # registry — the spec was filtered, so refuse it here too
+            return f"Error: {call.name} is not available to sub-agents — it is a parent-only tool"
+        args = call.arguments
+        if isinstance(args, str):
+            try:
+                args = json.loads(args)
+            except json.JSONDecodeError:
+                args = {}
+        if not isinstance(args, dict):
+            args = {}
+        # Validate required parameters from the tool schema
+        tool = loop.session.registry.get(call.name)
+        if tool is not None:
+            required = tool.parameters.get("required", [])
+            missing = [k for k in required if k not in args]
+            if missing:
+                return f"Error: {call.name} is missing required argument(s): {', '.join(missing)}"
+        return loop.session.execute_tool(call.name, args, call_id=call.id)
+
+    def deliver_tool_result(self, p: ToolCall, result: str) -> None:
+        """Append one tool result message for call P (parent thread only)."""
+        loop = self.loop
+        p.result = result
+        if hasattr(loop.session, "take_diff"):
+            p.diff = loop.session.take_diff(p.id)
+        loop.messages.append(
+            Message(
+                role="tool",
+                content=result,
+                tool_call_id=p.id,
+                name=p.name,
+            )
+        )
+        if loop.top_level and not loop._is_cancelled():
+            # only the top-level loop mirrors its messages onto the
+            # shared session: a sub-agent runs inside the parent's
+            # tool round and must never clobber the parent's
+            # conversation history (the TUI renders from it)
+            loop.session.last_messages = list(loop.messages)
+
+    def run_tools(self, calls: list[ToolCall], results: dict[str, str]) -> None:
+        """Run CALLS in model-emitted order, filling RESULTS.
+
+        Mirrors gptel's `gptel--handle-tool-use': synchronous tools
+        (Read, Edit, Glob, ...) execute ONE AT A TIME, in call order;
+        asynchronous tools (Bash, Agent — those whose ``run`` returns a
+        ``PendingToolResult``) are dispatched in line and run
+        concurrently in the background, their results awaited
+        afterwards, again in original call order.  Delivery happens
+        later, in original tool-call order, by the caller.
+
+        A cancel landing before a call starts skips it (tools have side
+        effects); a call already running — or an async tool already
+        dispatched — cannot be stopped, but its result stays local to
+        the (dead) run.
+        """
+        loop = self.loop
+        async_calls: list[tuple[ToolCall, PendingToolResult]] = []
+        for p in calls:
+            # A cancel landing while a call is still QUEUED must skip
+            # it (tools have side effects): the sequential loop checks
+            # before every call, so a call that has not started yet must
+            # not run after Ctrl-C.
+            if loop._is_cancelled():
+                results[p.id] = "Error: tool call cancelled (user aborted the run)."
+                continue
+            # Notify the TUI which tool is currently executing so the
+            # status bar can show the active tool name beside the spinner.
+            if loop.top_level:
+                loop.session.notify("tool_running", p.name)
+            start = time.monotonic()
+            try:
+                result = loop._execute_tool_call(p)
+            except Exception as e:  # noqa: BLE001 - containment boundary
+                p.elapsed = time.monotonic() - start
+                results[p.id] = f"Error: tool {p.name!r} crashed during execution — {e}"
+                continue
+            if isinstance(result, PendingToolResult):
+                # async tool (e.g. Bash): run() spawned the work and
+                # returned its handle immediately; await the real result
+                # after the sequential loop so sibling calls keep
+                # executing in the meantime
+                async_calls.append((p, result))
+            else:
+                p.elapsed = time.monotonic() - start
+                results[p.id] = sanitize_tool_result(result)
+        for p, pending in async_calls:
+            start = time.monotonic()
+            try:
+                result = pending.wait()
+            except Exception as e:  # noqa: BLE001 - containment boundary
+                results[p.id] = f"Error: tool {p.name!r} crashed during execution — {e}"
+            else:
+                p.elapsed = time.monotonic() - start
+                results[p.id] = sanitize_tool_result(result)
+
+    def execute_pending(self) -> None:
+        """TOOL state: run the round's pending tool calls.
+
+        The assistant message carrying the tool calls was already
+        appended by the WAIT state.  Results land in
+        ``self.info["tool_result"]`` and are delivered by the TRET
+        state in original tool-call order.
+
+        Synchronous tools run ONE AT A TIME in model-emitted order
+        (gptel-style); asynchronous tools (Bash, Agent) are dispatched
+        in line and run concurrently in the background.
+        """
+        loop = self.loop
+        pending = list(loop.pending)
+        if not pending:
+            return
+        if loop._is_cancelled():
+            # Ctrl-C before the round started: do not run tools (they
+            # have side effects) and do not touch shared state — a stale
+            # worker must never mirror its partial history over the next
+            # run's `session.last_messages`.
+            return
+        results: dict[str, str] = {}
+        loop._run_tools(pending, results)
+        if loop._is_cancelled():
+            # cancelled mid-round: tools already submitted may have run
+            # (their side effects are done), but the results stay local
+            # to this (dead) run
+            loop.pending = []
+            return
+        loop.info["tool_result"] = results
+
+    def deliver_results(self) -> None:
+        """TRET state: deliver the round's results to the conversation.
+
+        Results are appended as tool messages in the original
+        tool-call order regardless of execution order.  On cancel the
+        partial delivery is discarded — the shared history salvage
+        cuts the dangling round so no tool call is left unanswered.
+        """
+        loop = self.loop
+        pending = list(loop.pending)
+        if not pending:
+            return
+        if loop._is_cancelled():
+            loop.pending = []
+            return
+        results = loop.info.get("tool_result", {})
+        for p in pending:
+            if loop._is_cancelled():
+                loop.pending = []
+                return
+            loop._deliver_tool_result(p, results[p.id])
+            # Notify per-tool so the TUI rebuilds history progressively
+            # (each tool result appears as soon as it is committed to
+            # the conversation, instead of all at once at the end)
+            if loop.top_level:
+                loop.session.notify("tools")
+        loop.pending = []
+
+    def salvage_messages(self) -> list[Message]:
+        """Longest valid prefix of ``self.messages`` for the shared history.
+
+        A cancelled run may end mid-tool-round: the assistant message
+        carrying the tool calls is present but some (or all) results are
+        missing.  Committing that as-is would hand the next turn an
+        invalid request (a tool call without its response), so cut back
+        to the last complete round — the model redoes the dangling work
+        on the next turn.
+        """
+        loop = self.loop
+        msgs = loop.messages
+        open_round: int | None = None
+        pending: dict[str, bool] = {}
+        for i, m in enumerate(msgs):
+            if m.role == "assistant":
+                if m.tool_calls:
+                    if open_round is not None:
+                        return msgs[:open_round]
+                    open_round = i
+                    pending = {tc.id: False for tc in m.tool_calls}
+                elif open_round is not None:
+                    return msgs[:open_round]
+            elif m.role == "tool":
+                if m.tool_call_id in pending:
+                    pending[m.tool_call_id] = True
+                    if all(pending.values()):
+                        open_round = None
+                        pending = {}
+            elif open_round is not None:
+                return msgs[:open_round]
+        if open_round is not None:
+            return msgs[:open_round]
+        return msgs

python_agent_harness/tools/__init__.py

@@ -0,0 +1,56 @@
+"""Tool registry with default tools."""
+
+from __future__ import annotations
+
+from .agent_tool import AgentTool
+from .base import PendingToolResult, Registry, Tool, ToolContext
+from .bash import Bash
+from .filesystem import Edit, GlobTool, Grep, Insert, Mkdir, Read, Write
+from .mcp import MCPTool, mcp_tools_from_manager, normalize_mcp_result
+from .planexit import PlanExit
+from .question import Question
+from .skill import Skill
+from .todo import TodoWrite
+
+__all__ = [
+    "PendingToolResult",
+    "Registry",
+    "Tool",
+    "ToolContext",
+    "AgentTool",
+    "Bash",
+    "Edit",
+    "GlobTool",
+    "Grep",
+    "Insert",
+    "MCPTool",
+    "Mkdir",
+    "PlanExit",
+    "Question",
+    "Read",
+    "Skill",
+    "TodoWrite",
+    "Write",
+    "mcp_tools_from_manager",
+    "normalize_mcp_result",
+]
+
+
+def default_registry() -> Registry:
+    reg = Registry()
+    for tool in (
+        AgentTool(),
+        TodoWrite(),
+        GlobTool(),
+        Grep(),
+        Read(),
+        Insert(),
+        Edit(),
+        Write(),
+        Mkdir(),
+        Bash(),
+        Skill(),
+        Question(),
+    ):
+        reg.register(tool)
+    return reg

python_agent_harness/tools/agent_tool.py

@@ -0,0 +1,75 @@
+"""Agent tool: spawn sub-agents for delegated work.
+
+Asynchronous (mirrors ``:async t``): ``run`` returns a
+``PendingToolResult`` immediately and a background thread runs the
+sub-agent loop, delivering the result string when it finishes — a
+long-running sub-agent never blocks the parent's sequential tool loop.
+
+Sub-agents run the same agent loop with a fresh loop instance; their
+backend/model can be overridden (see config).  Results flow back to the
+parent as a single tool result string.  Errors are contained: an
+unexpected sub-agent response becomes an error string fed to the parent,
+never a crash.
+
+Tool execution mirrors gptel: synchronous tools (Read, Edit, ...) run
+ONE AT A TIME in model-emitted order, while asynchronous tools — Agent
+and Bash — are dispatched in line and run concurrently in the
+background.  Each sub-agent is fully isolated (own loop, own history,
+own stream), so independent tasks can be delegated in parallel.
+"""
+
+from __future__ import annotations
+
+import threading
+
+from .base import PendingToolResult, Tool, ToolContext
+
+DESCRIPTION = (
+    "Launch a specialized sub-agent to handle complex, multi-step tasks "
+    "autonomously. Sub-agents run independently and return results in one "
+    "message. Use for open-ended searches, complex research, or when "
+    "uncertain about finding results in the first few tries.\n\n"
+    "Multiple Agent calls issued in the same round run concurrently (like "
+    "Bash), while other tools execute one by one — delegate independent "
+    "tasks in parallel for efficiency."
+)
+
+PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "subagent_type": {
+            "type": "string",
+            "description": "Type of sub-agent: 'subagent' or 'gptel-opencode-agent'",
+        },
+        "description": {"type": "string", "description": "Short 3-5 word description of the task"},
+        "prompt": {"type": "string", "description": "The detailed task for the sub-agent"},
+    },
+    "required": ["subagent_type", "description", "prompt"],
+}
+
+
+class AgentTool(Tool):
+    name = "Agent"
+    description = DESCRIPTION
+    parameters = PARAMETERS
+
+    def run(self, args: dict, ctx: ToolContext) -> str | PendingToolResult:
+        prompt = args.get("prompt", "")
+        description = args.get("description", "task")
+        subagent_type = args.get("subagent_type", "subagent")
+        if not prompt:
+            return "Error: prompt must not be empty"
+
+        pending = PendingToolResult()
+
+        def worker() -> None:
+            # containment boundary: a sub-agent failure becomes an error
+            # string for the parent, never a crash in the delivery thread
+            try:
+                result = ctx.run_subagent(subagent_type, description, prompt)
+            except Exception as e:  # noqa: BLE001 - error string for the parent
+                result = f"Error: Task {description!r} failed — {e}"
+            pending.deliver(result)
+
+        threading.Thread(target=worker, daemon=True, name="subagent-tool").start()
+        return pending