python-agent-harness 1.5.5.0__tar.gz → 1.5.5.2__tar.gz

{python_agent_harness-1.5.5.0 → python_agent_harness-1.5.5.2}/PKG-INFO

@@ -1,9 +1,19 @@
 Metadata-Version: 2.4
 Name: python-agent-harness
-Version: 1.5.5.0
+Version: 1.5.5.2
 Summary: A lightweight, hackable mini-OpenCode written in Python.
-Author: huming
+Author-email: Huming Chen <chenhuming@gmail.com>
 License-Expression: MIT
+Project-URL: Homepage, https://github.com/beacoder/python-agent-harness
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -31,6 +41,7 @@ FSM-driven execution · OpenAI-compatible · built for daily use and easy custom
 [![CI](https://github.com/beacoder/python-agent-harness/actions/workflows/ci.yml/badge.svg)](https://github.com/beacoder/python-agent-harness/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/python-agent-harness.svg)](https://pypi.org/project/python-agent-harness/)
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/python-agent-harness?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/python-agent-harness)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 </div>
@@ -99,6 +110,7 @@ Edit `~/.config/python-agent-harness/config.json` and set your `base_url`, `api_
 - **Focused TUI** — a Rich-based interface with a pinned status bar, Todos panel, inline red/green diff rendering for `Edit` and `Write`, and a `prompt_toolkit` editor with history and completion. `Esc+Enter` submits, `Ctrl-D` quits, and `Ctrl-C` cancels without leaving the application.
 - **MCP support** — optional MCP integration through the `[mcp]` extra. MCP tools become ordinary agent tools such as `mcp__<server>__<tool>`. Supports `stdio`, `streamable-http`, and `sse` transports.
 - **Slash commands** — built-in `/init`, `/review`, `/explain`, and other commands, plus custom commands loaded from `prompts/commands/*.md`.
+- **Custom agents** — switch the main agent's system prompt at runtime with `/agent`. Agent prompt files live in `prompts/agents/*.md`. Use `default_agent` in the config file to start sessions with a specific agent.
 
 ## Inspired by opencode
 
@@ -160,6 +172,7 @@ All LLM settings live in a single JSON configuration file. Environment variables
     "reasoning_effort": null,
     "stream": null
   },
+  "default_agent": null,
   "paths": {
     "context_path": null,
     "skill_path": null
@@ -190,6 +203,7 @@ All LLM settings live in a single JSON configuration file. Environment variables
 - **`models`** — named LLM profiles for runtime switching with `/model`. A profile is a partial settings dictionary; unset keys inherit from the main `llm`. `default` restores the main LLM configuration.
 - **`context_windows`** — optional per-model context-window overrides (tokens). Keys are model names or substrings (e.g., `deepseek-v4`); matched in file order, first match wins. Overrides the built-in `CONTEXT_WINDOWS` table in `config.py`.
 - **`subagent_llm`** — LLM configuration for `Agent` tool requests. Unset values inherit from the main `llm`. Set `profile` to reuse a profile from `models`. Precedence is: profile settings > explicit `subagent_llm` settings > main `llm` > environment variables.
+- **`default_agent`** — name of the agent to use at session start (instead of the built-in `agent.md`). The agent must exist as a `.md` file in the `prompts/agents/` directory. When unset or `null`, the built-in default agent is used. Use `/agent default` in the TUI to switch back to the built-in at any time.
 - **`paths.context_path` / `paths.skill_path`** — locations from which to load context files and skills. When unset, the project-local `<project>/contexts` and `<project>/skills` directories are used.
 - **`mcp.servers`** — MCP server configuration. Requires the `[mcp]` extra. Each server supports `transport`, `command`, `args`, `env`, `url`, `headers`, `parallel`, `timeout`, and `enabled`.
 - **Configuration precedence** — code defaults < config file < `OPENAI_*` environment variables. Sub-agent settings also support `OPENAI_SUBAGENT_*` (`_BASE_URL`, `_API_KEY`, `_MODEL`).
@@ -219,10 +233,24 @@ Launches the interactive TUI agent. If `project-dir` is omitted, the current dir
 | `/restore [path\|title\|--latest\|latest]` | Restore a session; title matching uses substring search |
 | `/clear` | Start a fresh conversation |
 | `/model [name]` | Switch LLM profiles; `default` restores the session's original model |
+| `/agent [name]` | Switch agent system prompt; `default` restores the built-in `agent.md` |
 | `/exit` | Quit |
 
 Custom commands from `prompts/commands/*.md` are registered as slash commands as well (TUI only).
 
+### Custom agents
+
+Agent prompt files are markdown files (`.md`) placed in the `prompts/agents/` directory. Each file becomes a switchable agent profile available via the `/agent` TUI command. 
+
+#### Commands vs Agents
+
+| | Commands (`/review`) | Agents (`/agent reviewer`) |
+|---|---|---|
+| **Scope** | One-shot (prompt resets after run) | Persistent (stays until next `/agent`) |
+| **Kickoff** | Hardcoded kickoff message | User types their own prompt |
+| **Tools** | Can restrict (`allow_planexit=False`) | All tools |
+| **Ctrl-C** | Restores to default prompt | Stays on the custom agent |
+
 ## Project layout
 
 ```text

python_agent_harness-1.5.5.0/python_agent_harness.egg-info/PKG-INFO → python_agent_harness-1.5.5.2/README.md

@@ -1,26 +1,3 @@
-Metadata-Version: 2.4
-Name: python-agent-harness
-Version: 1.5.5.0
-Summary: A lightweight, hackable mini-OpenCode written in Python.
-Author: huming
-License-Expression: MIT
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: rich>=13.0
-Requires-Dist: httpx>=0.27
-Requires-Dist: prompt_toolkit>=3.0
-Provides-Extra: mcp
-Requires-Dist: mcp<3,>=2.0; extra == "mcp"
-Provides-Extra: dev
-Requires-Dist: ruff>=0.6; extra == "dev"
-Requires-Dist: pyright>=1.1.380; extra == "dev"
-Requires-Dist: build>=1.2; extra == "dev"
-Requires-Dist: coverage[toml]>=7.0; extra == "dev"
-Requires-Dist: pip-audit>=2.7; extra == "dev"
-Requires-Dist: mcp<3,>=2.0; extra == "dev"
-Dynamic: license-file
-
 <div align="center">
 
 # python-agent-harness
@@ -31,6 +8,7 @@ FSM-driven execution · OpenAI-compatible · built for daily use and easy custom
 [![CI](https://github.com/beacoder/python-agent-harness/actions/workflows/ci.yml/badge.svg)](https://github.com/beacoder/python-agent-harness/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/python-agent-harness.svg)](https://pypi.org/project/python-agent-harness/)
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/python-agent-harness?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/python-agent-harness)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 </div>
@@ -99,6 +77,7 @@ Edit `~/.config/python-agent-harness/config.json` and set your `base_url`, `api_
 - **Focused TUI** — a Rich-based interface with a pinned status bar, Todos panel, inline red/green diff rendering for `Edit` and `Write`, and a `prompt_toolkit` editor with history and completion. `Esc+Enter` submits, `Ctrl-D` quits, and `Ctrl-C` cancels without leaving the application.
 - **MCP support** — optional MCP integration through the `[mcp]` extra. MCP tools become ordinary agent tools such as `mcp__<server>__<tool>`. Supports `stdio`, `streamable-http`, and `sse` transports.
 - **Slash commands** — built-in `/init`, `/review`, `/explain`, and other commands, plus custom commands loaded from `prompts/commands/*.md`.
+- **Custom agents** — switch the main agent's system prompt at runtime with `/agent`. Agent prompt files live in `prompts/agents/*.md`. Use `default_agent` in the config file to start sessions with a specific agent.
 
 ## Inspired by opencode
 
@@ -160,6 +139,7 @@ All LLM settings live in a single JSON configuration file. Environment variables
     "reasoning_effort": null,
     "stream": null
   },
+  "default_agent": null,
   "paths": {
     "context_path": null,
     "skill_path": null
@@ -190,6 +170,7 @@ All LLM settings live in a single JSON configuration file. Environment variables
 - **`models`** — named LLM profiles for runtime switching with `/model`. A profile is a partial settings dictionary; unset keys inherit from the main `llm`. `default` restores the main LLM configuration.
 - **`context_windows`** — optional per-model context-window overrides (tokens). Keys are model names or substrings (e.g., `deepseek-v4`); matched in file order, first match wins. Overrides the built-in `CONTEXT_WINDOWS` table in `config.py`.
 - **`subagent_llm`** — LLM configuration for `Agent` tool requests. Unset values inherit from the main `llm`. Set `profile` to reuse a profile from `models`. Precedence is: profile settings > explicit `subagent_llm` settings > main `llm` > environment variables.
+- **`default_agent`** — name of the agent to use at session start (instead of the built-in `agent.md`). The agent must exist as a `.md` file in the `prompts/agents/` directory. When unset or `null`, the built-in default agent is used. Use `/agent default` in the TUI to switch back to the built-in at any time.
 - **`paths.context_path` / `paths.skill_path`** — locations from which to load context files and skills. When unset, the project-local `<project>/contexts` and `<project>/skills` directories are used.
 - **`mcp.servers`** — MCP server configuration. Requires the `[mcp]` extra. Each server supports `transport`, `command`, `args`, `env`, `url`, `headers`, `parallel`, `timeout`, and `enabled`.
 - **Configuration precedence** — code defaults < config file < `OPENAI_*` environment variables. Sub-agent settings also support `OPENAI_SUBAGENT_*` (`_BASE_URL`, `_API_KEY`, `_MODEL`).
@@ -219,10 +200,24 @@ Launches the interactive TUI agent. If `project-dir` is omitted, the current dir
 | `/restore [path\|title\|--latest\|latest]` | Restore a session; title matching uses substring search |
 | `/clear` | Start a fresh conversation |
 | `/model [name]` | Switch LLM profiles; `default` restores the session's original model |
+| `/agent [name]` | Switch agent system prompt; `default` restores the built-in `agent.md` |
 | `/exit` | Quit |
 
 Custom commands from `prompts/commands/*.md` are registered as slash commands as well (TUI only).
 
+### Custom agents
+
+Agent prompt files are markdown files (`.md`) placed in the `prompts/agents/` directory. Each file becomes a switchable agent profile available via the `/agent` TUI command. 
+
+#### Commands vs Agents
+
+| | Commands (`/review`) | Agents (`/agent reviewer`) |
+|---|---|---|
+| **Scope** | One-shot (prompt resets after run) | Persistent (stays until next `/agent`) |
+| **Kickoff** | Hardcoded kickoff message | User types their own prompt |
+| **Tools** | Can restrict (`allow_planexit=False`) | All tools |
+| **Ctrl-C** | Restores to default prompt | Stays on the custom agent |
+
 ## Project layout
 
 ```text

{python_agent_harness-1.5.5.0 → python_agent_harness-1.5.5.2}/pyproject.toml

@@ -4,21 +4,34 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-agent-harness"
-version = "1.5.5.0"
+version = "1.5.5.2"
 description = "A lightweight, hackable mini-OpenCode written in Python."
+authors = [
+    {name = "Huming Chen", email = "chenhuming@gmail.com"}
+]
+license = "MIT"
 readme = "README.md"
 requires-python = ">=3.11"
-authors = [
-    { name = "huming" }
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14"
 ]
-license = 'MIT'
-license-files = ["LICENSE"]
 dependencies = [
     "rich>=13.0",
     "httpx>=0.27",
     "prompt_toolkit>=3.0",
 ]
 
+[project.urls]
+Homepage = "https://github.com/beacoder/python-agent-harness"
+
 [project.optional-dependencies]
 # MCP (Model Context Protocol) client support: exposes MCP server tools to
 # the agent as namespaced mcp__<server>__<tool> tools.  Install with:
@@ -49,7 +62,7 @@ python-agent-harness = "python_agent_harness.cli:main"
 include = ["python_agent_harness*"]
 
 [tool.setuptools.package-data]
-python_agent_harness = ["prompts/*.md", "prompts/commands/*.md"]
+python_agent_harness = ["prompts/*.md", "prompts/commands/*.md", "prompts/agents/*.md"]
 
 [tool.ruff]
 line-length = 100

{python_agent_harness-1.5.5.0 → python_agent_harness-1.5.5.2}/python_agent_harness/__init__.py

@@ -5,7 +5,7 @@ from .mcp.manager import MCPManager
 from .models import AgentMode, Message, ToolCall, ToolSpec
 from .session import Session
 
-__version__ = "1.5.5.0"
+__version__ = "1.5.5.2"
 
 __all__ = [
     "Session",

{python_agent_harness-1.5.5.0 → python_agent_harness-1.5.5.2}/python_agent_harness/agent.py

@@ -493,7 +493,10 @@ class AgentLoop:
                 return  # cancelled (Ctrl-C), not an error
             self.error = f"Error: {e}"
             self.info["error"] = self.error
-            session.notify("error")
+            # the detail travels with the notification so the TUI can
+            # show WHAT failed (e.g. "no quota") in the status bar
+            # instead of a bare red "error"
+            session.notify("error", self.error)
             return
 
         if self._is_cancelled():
@@ -634,14 +637,25 @@ def run_agent_loop(
 
     ``client`` (when given) overrides the session's client for this
     run — the per-invocation sub-agent clone."""
-    return AgentLoop(
+    loop = AgentLoop(
         session,
         messages=messages,
         top_level=top_level,
         system=system,
         max_rounds=max_rounds,
         client=client,
-    ).run()
+    )
+    result = loop.run()
+    # Notify run_done only for a successfully completed top-level run:
+    # - top_level: sub-agents share the parent's session (notify_fn
+    #   included) and must not mark the parent run finished while it is
+    #   still executing tools
+    # - DONE only: ERRS already notifies "error" with the detail, and
+    #   ABRT is cancellation/supersession (TUI sets that status).  DONE
+    #   also implies not cancelled — the FSM routes cancelled to ABRT.
+    if loop.top_level and loop.state == AgentLoop.DONE:
+        session.notify("run_done")
+    return result
 
 
 class Supervisor:

{python_agent_harness-1.5.5.0 → python_agent_harness-1.5.5.2}/python_agent_harness/cli.py

@@ -20,6 +20,7 @@ import sys
 
 from . import config
 from .client import Client
+from .prompts import RESERVED_AGENT_NAME
 from .session import Session
 from .tools import default_registry
 
@@ -91,13 +92,14 @@ def make_session(
     # (same precedence as the main agent's stream).
     effective_stream = settings["stream"] if stream is None else stream
     model_profiles = config.load_models_config(config_path)
+    default_agent = config.load_default_agent(config_path)
     # Base settings for /model switching: the main llm settings as
     # resolved at session start (incl. the CLI --model/--no-stream
     # overrides above), so a profile's unset keys inherit these
     # instead of values drifted by earlier switches.
     llm_settings = dict(settings)
     llm_settings["stream"] = effective_stream
-    return Session(
+    session = Session(
         project_dir=abs_project,
         client=client,
         model=model,
@@ -117,9 +119,18 @@ def make_session(
         skill_path=paths.get("skill_path"),
         mcp=mcp_config,
         model_profiles=model_profiles,
+        default_agent=default_agent,
         llm_settings=llm_settings,
         config_path=config_path,
     )
+    if default_agent and default_agent != RESERVED_AGENT_NAME:
+        ok, msg = session.switch_agent(default_agent)
+        if not ok:
+            # A typo'd/missing default_agent must not silently start the
+            # session with the built-in prompt — record the config error
+            # so the TUI can surface it (see Tui.run).
+            session.startup_warnings.append(f"default_agent: {msg}")
+    return session
 
 
 def make_session_with_mcp(
@@ -132,14 +143,14 @@ def make_session_with_mcp(
 
     Wraps ``make_session``: the session's MCP servers are connected and
     their tools registered before the session is returned (discovery
-    happens once, at session start).  Per-server failures are printed
-    to stderr and never prevent the session from running — the agent
-    keeps working with the built-in tools.
+    happens once, at session start).  Per-server failures are recorded
+    as startup warnings (rendered by the TUI banner) and never prevent
+    the session from running — the agent keeps working with the
+    built-in tools.
     """
     session = make_session(project_dir, config_path=config_path, model=model, stream=stream)
-    failures = session.connect_mcp()
-    for server, err in failures:
-        print(f"python-agent-harness: [{server}] {err}", file=sys.stderr)
+    for server, err in session.connect_mcp():
+        session.startup_warnings.append(f"MCP [{server}]: {err}")
     return session
 
 
@@ -228,6 +239,9 @@ def cmd_config(args: argparse.Namespace) -> int:
             print(f"  {pattern}: {size}")
     else:
         print("context_windows: (none configured — built-in table in config.py applies)")
+    # Show default agent
+    default_agent = config.load_default_agent(args.path)
+    print(f"default_agent: {default_agent or '(default: agent.md)'}")
     return 0
 
 

{python_agent_harness-1.5.5.0 → python_agent_harness-1.5.5.2}/python_agent_harness/client.py

@@ -36,6 +36,14 @@ class ApiError(Exception):
     """Raised when the API call itself fails (network/HTTP)."""
 
 
+# Grace between shutdown(SHUT_RDWR) and close() of an in-flight socket
+# on macOS (see _shutdown_and_close): 50ms proved too tight under load
+# (the woken thread can still be parked in select() when the fd is
+# released, losing the wakeup).  200ms keeps Ctrl-C responsive while
+# making the fd-reuse race vanishingly unlikely.
+_ABORT_SHUTDOWN_GRACE_S = 0.2
+
+
 class RetryableApiError(ApiError):
     """A transient failure (rate limit, server error) safe to retry.
 
@@ -865,12 +873,17 @@ def _shutdown_and_close(sock: _socket.socket) -> None:
     settimeout for the read timeout), so a blocked recv parks in
     select(); closing the fd before that select has processed the
     shutdown wakeup can lose the wakeup and leave the read parked
-    forever.  Give the woken thread a moment to observe the EOF first.
+    forever.  Worse, ``abort()`` swaps in a fresh httpx client right
+    after, so a new socket could reuse the fd number before the
+    reader observed the EOF.  The grace sleep delays the fd release
+    so the woken thread can observe the EOF on the old fd first.
     """
     with contextlib.suppress(OSError):
         sock.shutdown(_socket.SHUT_RDWR)
     if sys.platform == "darwin":
-        time.sleep(0.05)
+        # macOS only; on Linux shutdown() alone reliably wakes the
+        # blocked recv (measured: <200ms unblock, no sleeps needed).
+        time.sleep(_ABORT_SHUTDOWN_GRACE_S)
     with contextlib.suppress(OSError):
         sock.close()
 

{python_agent_harness-1.5.5.0 → python_agent_harness-1.5.5.2}/python_agent_harness/commands.py

@@ -63,7 +63,6 @@ class SessionCommand:
         name: str,
         prompt_file: str,
         kickoff: str,
-        buffer_name: str,
         status: str,
         validate_dir: bool = False,
         allow_planexit: bool = True,
@@ -71,7 +70,6 @@ class SessionCommand:
         self.name = name
         self.prompt_file = prompt_file
         self.kickoff = kickoff
-        self.buffer_name = buffer_name
         self.status = status
         self.validate_dir = validate_dir
         self.allow_planexit = allow_planexit
@@ -99,7 +97,6 @@ def initialize_command() -> SessionCommand:
         name="initialize",
         prompt_file="initialize.md",
         kickoff="Analyze the repository at ${path} and create/update AGENTS.md.\n",
-        buffer_name="*gptel-agent-init:*",
         status=" Initializing...",
         validate_dir=True,
         allow_planexit=False,
@@ -111,7 +108,6 @@ def review_command() -> SessionCommand:
         name="review",
         prompt_file="review.md",
         kickoff="Review the requested code changes.",
-        buffer_name="*gptel-agent-review*",
         status=" Reviewing...",
         allow_planexit=False,
     )
@@ -161,7 +157,6 @@ def load_custom_commands() -> list[SessionCommand]:
                 name=name,
                 prompt_file=str(f.relative_to(PROMPTS_DIR)),
                 kickoff="Proceed with the task described in your instructions.\n",
-                buffer_name=f"*gptel-agent-{name}*",
                 status=f" Running {name}...",
             )
         )

{python_agent_harness-1.5.5.0 → python_agent_harness-1.5.5.2}/python_agent_harness/config.py

@@ -239,6 +239,7 @@ CONFIG_TEMPLATE = """\
     "reasoning_effort": null,
     "stream": null
   }},
+  "default_agent": null,
   "paths": {{
     "_comment": "Optional overrides for context and skill directories. Absolute paths or ~ expansion supported.",
     "context_path": null,
@@ -458,6 +459,23 @@ def load_models_config(path: str | os.PathLike | None = None) -> dict[str, dict]
     return profiles
 
 
+def load_default_agent(path: str | os.PathLike | None = None) -> str | None:
+    """Load the default agent name from the config file's ``default_agent`` key.
+
+    Returns the agent name (str) when set, or None when unset (meaning
+    use the built-in ``default`` agent, i.e. ``prompts/agent.md``).
+    """
+    data = _read_config(path)
+    val = data.get("default_agent")
+    if val is None:
+        return None
+    if not isinstance(val, str) or not val.strip():
+        raise ValueError(
+            f"config file {_config_path(path)}: default_agent must be a non-empty string"
+        )
+    return val.strip()
+
+
 def mask_secret(value: str | None) -> str:
     return "****" if value else "(unset)"
 

{python_agent_harness-1.5.5.0 → python_agent_harness-1.5.5.2}/python_agent_harness/persistence.py

@@ -170,18 +170,12 @@ class SessionPersistence:
         lines = [";; Local Variables:"]
         pairs = [
             ("python-agent-harness--project-dir", self.project_dir),
-            ("gptel-model", self.model),
-            ("gptel-system-prompt", self.system_prompt),
-            ("gptel-temperature", self.temperature),
-            ("gptel-max-tokens", self.max_tokens),
+            ("python-agent-harness--model", self.model),
         ]
         for name, value in pairs:
             if value is None:
                 continue
             lines.append(f";; {name}: {value!r}")
-        if self.tool_names:
-            names = " ".join(f'"{n}"' for n in self.tool_names)
-            lines.append(f";; gptel--tool-names: ({names})")
         if self.round_times:
             stamps = " ".join(repr(float(t)) for t in self.round_times)
             lines.append(f";; python-agent-harness--round-times: {stamps}")

python_agent_harness-1.5.5.2/python_agent_harness/prompts/agents/reviewer.md

@@ -0,0 +1,12 @@
+# Role and Behavior
+You are a code reviewer agent. Your job is to review code changes
+thoroughly and provide constructive feedback.
+
+Focus on:
+- Correctness and potential bugs
+- Code style and readability
+- Performance implications
+- Security concerns
+- Test coverage
+
+Always provide actionable suggestions with specific file and line references.

{python_agent_harness-1.5.5.0 → python_agent_harness-1.5.5.2}/python_agent_harness/prompts.py

@@ -1,7 +1,7 @@
 """Prompt loading and assembly.
 
 Ported from gptel-agent-harness.el: loads bundled prompt files
-(agent/subagent/commands), strips YAML frontmatter, discovers skills
+(agent/subagent/commands/custom agents), strips YAML frontmatter, discovers skills
 for the {{SKILLS}} placeholder, assembles the effective system prompt
 from project context files + task-completion rules + agent prompt, and
 provides the compaction flow helpers (summarize the conversation with
@@ -22,10 +22,16 @@ from typing import Any
 from . import config
 from .models import Message
 
+PROMPTS_DIR = Path(__file__).parent / "prompts"
+AGENTS_DIR = PROMPTS_DIR / "agents"
+# Reserved pseudo-name that restores the built-in agent (prompts/agent.md);
+# custom agent files cannot claim it (see discover_agents).
+RESERVED_AGENT_NAME = "default"
+
 
 def read_prompt_file(name: str) -> str:
     """Read a prompt file from the package prompts dir."""
-    path = Path(__file__).parent / "prompts" / name
+    path = PROMPTS_DIR / name
     return path.read_text(encoding="utf-8")
 
 
@@ -496,3 +502,52 @@ def compacted_messages(summary: str, prompts: list[str]) -> list[Message]:
         Message(role="user", content=frame),
         *[Message(role="user", content=p) for p in prompts],
     ]
+
+
+# ---- custom agent discovery -----------------------------------------------
+# Agent prompt files are markdown files (``*.md``) in
+# ``prompts/agents/``.  Each file becomes a switchable agent profile
+# available via the ``/agent`` TUI command.  The file's stem (e.g.
+# ``reviewer.md`` → ``reviewer``) is the agent name; an optional YAML
+# frontmatter ``name:`` can override it.  The built-in ``default``
+# agent (``prompts/agent.md``) is always available and cannot be
+# overridden by a file in this directory.
+
+
+def _agent_name_from_file(path: Path) -> str:
+    """Derive agent name from a file: frontmatter ``name:`` if present,
+    otherwise the file stem (lowercased, non-alphanumerics → ``-``)."""
+    try:
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+    m = _FRONTMATTER_RE.match(text)
+    if m:
+        for line in m.group(0).splitlines():
+            if line.startswith("name:"):
+                name = line[len("name:") :].strip()
+                if name:
+                    return name
+    base = path.stem.lower()
+    base = re.sub(r"[^a-z0-9]+", "-", base)
+    return base.strip("-")
+
+
+def discover_agents() -> dict[str, str]:
+    """Discover all custom agents in the ``prompts/agents/`` directory.
+
+    Returns a dict mapping agent name → absolute path to the prompt
+    file.  Files without a valid name are skipped.  The built-in
+    ``default`` agent is NOT included here — callers add it separately.
+    A file claiming the reserved name ``default`` (via stem or
+    frontmatter) is skipped: the built-in agent always wins.
+    """
+    if not AGENTS_DIR.is_dir():
+        return {}
+    agents: dict[str, str] = {}
+    for f in sorted(AGENTS_DIR.glob("*.md")):
+        name = _agent_name_from_file(f)
+        if not name or name == RESERVED_AGENT_NAME:
+            continue
+        agents[name] = str(f.resolve())
+    return agents

{python_agent_harness-1.5.5.0 → python_agent_harness-1.5.5.2}/python_agent_harness/session.py

@@ -22,7 +22,7 @@ from .mcp.manager import MCPManager
 from .models import AgentMode
 from .persistence import SessionPersistence, escape_role_headers
 from .planmode import PlanMode
-from .prompts import index_skills
+from .prompts import RESERVED_AGENT_NAME, discover_agents, index_skills
 from .subagent import run_subagent
 from .token_estimator import TokenCalibrator
 from .tools import Registry, ToolContext
@@ -89,6 +89,7 @@ class Session:
         mcp: MCPConfig | None = None,
         mcp_manager: MCPManager | None = None,
         model_profiles: dict[str, dict] | None = None,
+        default_agent: str | None = None,
         llm_settings: dict | None = None,
         config_path: str | None = None,
     ) -> None:
@@ -183,6 +184,17 @@ class Session:
         # model profile's unset keys inherit these values, so switching
         # between profiles never drifts settings from earlier switches.
         self.llm_settings: dict = dict(llm_settings) if llm_settings else {}
+        # Default agent name: when set, the session starts with this
+        # agent's prompt instead of the built-in default (agent.md).
+        # ``/agent default`` restores the built-in, not this setting.
+        self.default_agent = default_agent
+        # Non-fatal startup warnings (e.g. a default_agent that could not
+        # be applied); the TUI renders these in its banner so they are
+        # visible inside the interface rather than on stderr.
+        self.startup_warnings: list[str] = []
+        # Original system prompt assembled at session start — used by
+        # /agent default to restore the original agent.md prompt.
+        self._default_system_prompt = system_prompt
         # Monotonic cancel identity: cancel() bumps this counter, so a
         # worker from a cancelled run can tell it was cancelled even
         # after the next run clears the shared event.
@@ -708,6 +720,37 @@ class Session:
         self.stream = merged["stream"]
         return True, f"switched to {name} ({self.model})"
 
+    def switch_agent(self, name: str) -> tuple[bool, str]:
+        """Switch the main agent's system prompt to a named agent.
+
+        Agent prompt files are discovered from the ``prompts/agents/`` package
+        directory (see ``python_agent_harness.prompts.discover_agents``).
+        The pseudo-name ``default`` restores the original system prompt
+        saved at session construction.  Returns (success, message).
+        """
+        if name == RESERVED_AGENT_NAME:
+            self.system_prompt = self._default_system_prompt
+            self.store.system_prompt = self._default_system_prompt
+            return True, "switched to default agent"
+
+        agents = discover_agents()
+        prompt_file = agents.get(name)
+        if prompt_file is None:
+            available = ", ".join(sorted([RESERVED_AGENT_NAME, *agents.keys()]))
+            return False, f"unknown agent: {name} (available: {available})"
+        from .prompts import assemble_agent_prompt, load_agent_prompt
+
+        agent_prompt = load_agent_prompt(prompt_file, skill_dir=self._skill_dir)
+        if agent_prompt is None:
+            return False, f"agent {name}: prompt file not found or empty: {prompt_file}"
+        self.system_prompt = assemble_agent_prompt(
+            self.project_dir,
+            agent_prompt,
+            context_path=self._configured_context_path,
+        )
+        self.store.system_prompt = self.system_prompt
+        return True, f"switched to {name}"
+
     # ------------------------------------------------------------------
     # direct commands: compact / summary (no agent loop)
     # ------------------------------------------------------------------
@@ -752,7 +795,7 @@ class Session:
             self.last_messages = compacted_messages(summary, user_prompt_texts(messages))
             self.auto_save(self.last_messages, self.system_prompt)
             self.notify("compact")
-            return True, "Buffer compacted successfully."
+            return True, "Session compacted successfully."
         except Exception as e:  # noqa: BLE001 - compaction failure is non-fatal
             self.log(f"compaction failed: {e}")
             return False, f"Compaction failed: {e}"