python-agent-harness 1.5.4.9__tar.gz → 1.5.5.1__tar.gz

{python_agent_harness-1.5.4.9/python_agent_harness.egg-info → python_agent_harness-1.5.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-agent-harness
-Version: 1.5.4.9
+Version: 1.5.5.1
 Summary: A lightweight, hackable mini-OpenCode written in Python.
 Author: huming
 License-Expression: MIT
@@ -91,14 +91,15 @@ Edit `~/.config/python-agent-harness/config.json` and set your `base_url`, `api_
 
 ## Features
 
-- **FSM-driven execution** — explicit `WAIT` / `TOOL` / `TRET` / `SUPERVISE` / `DONE` / `ERRS` / `ABRT` states. Completion supervision nudges the model when it stops early, while failed tool calls are sanitized so they never strand the agent. Transient API failures (`429` / `5xx`) retry with exponential backoff and jitter.
+- **FSM-driven execution** — explicit `WAIT` / `TOOL` / `TRET` / `SUPERVISE` / `DONE` / `ERRS` / `ABRT` states. Completion supervision nudges the model when it stops early, while failed tool calls are sanitized so they never strand the agent. Transient API failures (`429` / `5xx`) retry with exponential backoff and jitter. Auth-expired status codes (configurable via `AUTH_REFRESH_STATUS_CODES` in `config.py`; defaults to `[401, 502]`) trigger automatic API key re-read from config/env — some API gateways return `502` instead of `401` when the backend auth token has expired. Note: codes in this list are treated as auth-expired exclusively and will not be retried with backoff, so only include codes that are unambiguously auth-related in your environment.
 - **Context management** — CJK-aware token estimation, per-model context windows, and automatic compaction at 70% usage.
-- **Coding tools** — `Agent`, `TodoWrite`, `Glob`, `Grep`, `Read`, `Insert`, `Edit` (including unified diffs), `Write`, `Mkdir`, `Bash`, `Skill`, `Question`, and `PlanExit`. Synchronous tools execute sequentially; asynchronous tools such as `Bash` and `Agent` can run concurrently while preserving emitted order.
+- **Coding tools** — `Agent`, `TodoWrite`, `Glob`, `Grep`, `Read`, `Insert`, `Edit` (including unified diffs), `Write`, `Mkdir`, `Bash`, `Skill`, `Question`, and `PlanExit`. Synchronous tools execute sequentially, but a round made up entirely of read-only tools (`Read`, `Glob`, `Grep`, `Skill`) is dispatched concurrently via a bounded thread pool; asynchronous tools such as `Bash` and `Agent` can run concurrently as well. Results are always delivered in the model's emitted order.
 - **Plan / Build modes** — plan mode is read-only except for the per-session plan file.
 - **Persistent sessions** — sessions are automatically saved after every response to `~/.local/share/python-agent-harness/sessions/`, with LLM-generated titles and support for `/restore --latest` and `/sessions`.
 - **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 +161,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 +192,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 +222,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.4.9 → python_agent_harness-1.5.5.1}/README.md

@@ -68,14 +68,15 @@ Edit `~/.config/python-agent-harness/config.json` and set your `base_url`, `api_
 
 ## Features
 
-- **FSM-driven execution** — explicit `WAIT` / `TOOL` / `TRET` / `SUPERVISE` / `DONE` / `ERRS` / `ABRT` states. Completion supervision nudges the model when it stops early, while failed tool calls are sanitized so they never strand the agent. Transient API failures (`429` / `5xx`) retry with exponential backoff and jitter.
+- **FSM-driven execution** — explicit `WAIT` / `TOOL` / `TRET` / `SUPERVISE` / `DONE` / `ERRS` / `ABRT` states. Completion supervision nudges the model when it stops early, while failed tool calls are sanitized so they never strand the agent. Transient API failures (`429` / `5xx`) retry with exponential backoff and jitter. Auth-expired status codes (configurable via `AUTH_REFRESH_STATUS_CODES` in `config.py`; defaults to `[401, 502]`) trigger automatic API key re-read from config/env — some API gateways return `502` instead of `401` when the backend auth token has expired. Note: codes in this list are treated as auth-expired exclusively and will not be retried with backoff, so only include codes that are unambiguously auth-related in your environment.
 - **Context management** — CJK-aware token estimation, per-model context windows, and automatic compaction at 70% usage.
-- **Coding tools** — `Agent`, `TodoWrite`, `Glob`, `Grep`, `Read`, `Insert`, `Edit` (including unified diffs), `Write`, `Mkdir`, `Bash`, `Skill`, `Question`, and `PlanExit`. Synchronous tools execute sequentially; asynchronous tools such as `Bash` and `Agent` can run concurrently while preserving emitted order.
+- **Coding tools** — `Agent`, `TodoWrite`, `Glob`, `Grep`, `Read`, `Insert`, `Edit` (including unified diffs), `Write`, `Mkdir`, `Bash`, `Skill`, `Question`, and `PlanExit`. Synchronous tools execute sequentially, but a round made up entirely of read-only tools (`Read`, `Glob`, `Grep`, `Skill`) is dispatched concurrently via a bounded thread pool; asynchronous tools such as `Bash` and `Agent` can run concurrently as well. Results are always delivered in the model's emitted order.
 - **Plan / Build modes** — plan mode is read-only except for the per-session plan file.
 - **Persistent sessions** — sessions are automatically saved after every response to `~/.local/share/python-agent-harness/sessions/`, with LLM-generated titles and support for `/restore --latest` and `/sessions`.
 - **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
 
@@ -137,6 +138,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
@@ -167,6 +169,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`).
@@ -196,10 +199,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.4.9 → python_agent_harness-1.5.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-agent-harness"
-version = "1.5.4.9"
+version = "1.5.5.1"
 description = "A lightweight, hackable mini-OpenCode written in Python."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -49,7 +49,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.4.9 → python_agent_harness-1.5.5.1}/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.4.9"
+__version__ = "1.5.5.1"
 
 __all__ = [
     "Session",

{python_agent_harness-1.5.4.9 → python_agent_harness-1.5.5.1}/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():

{python_agent_harness-1.5.4.9 → python_agent_harness-1.5.5.1}/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.4.9 → python_agent_harness-1.5.5.1}/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.
 
@@ -49,9 +57,12 @@ class RetryableApiError(ApiError):
 
 
 class AuthExpiredError(ApiError):
-    """Raised on HTTP 401 — the credential may have expired.
+    """Raised on auth-expired HTTP status codes.
 
-    Handled specially in the retry loop: the API key is re-read from
+    By default HTTP 401, but customizable via
+    ``config.AUTH_REFRESH_STATUS_CODES`` — some API gateways return 502
+    or other codes when the backend auth token has expired.  Handled
+    specially in the retry loop: the API key is re-read from
     config/environment (an external process may have refreshed the
     token) and the request is retried once with the new key.  If the
     key hasn't changed, the error is permanent and propagated as a
@@ -60,7 +71,13 @@ class AuthExpiredError(ApiError):
 
 
 def _retryable_status(status: int) -> bool:
-    """429 and 5xx are transient; every other error is permanent."""
+    """429 and 5xx are transient; every other error is permanent.
+
+    Status codes in ``config.AUTH_REFRESH_STATUS_CODES`` are excluded —
+    they are handled as auth-expired, not retried with backoff.
+    """
+    if status in config.AUTH_REFRESH_STATUS_CODES:
+        return False
     return status == 429 or status >= 500
 
 
@@ -508,12 +525,14 @@ class Client:
                 if self._sleep_backoff(attempt, e.retry_after, cancel_check):
                     raise
             except AuthExpiredError as e:
-                # HTTP 401: the credential (often a JWT with a short
-                # TTL) may have expired.  Re-read the API key from the
-                # config file / environment — an external token-refresh
-                # process may have written a new one.  Poll for up to
-                # 30s waiting for the key to change; retry once if it
-                # does.  Fail immediately if already refreshed once
+                # Auth-expired status code (401, or any code in
+                # config.AUTH_REFRESH_STATUS_CODES): the credential
+                # (often a JWT with a short TTL) may have expired.
+                # Re-read the API key from the config file / environment
+                # — an external token-refresh process may have written a
+                # new one.  Poll for up to 30s waiting for the key to
+                # change; retry once if it does.  Fail immediately if
+                # already refreshed once
                 # (prevents infinite loops).
                 self._reset_http()
                 if auth_refreshed or not self._refresh_api_key(cancel_check):
@@ -635,7 +654,7 @@ class Client:
             if resp.status_code >= 400:
                 body = resp.read().decode("utf-8", "replace")
                 message = f"API error {resp.status_code}: {body[:500]}"
-                if resp.status_code == 401:
+                if resp.status_code in config.AUTH_REFRESH_STATUS_CODES:
                     raise AuthExpiredError(message)
                 if _retryable_status(resp.status_code):
                     raise RetryableApiError(message, resp.headers.get("Retry-After"))
@@ -697,7 +716,7 @@ class Client:
         resp = self._http.post(self._url(), headers=self._headers(stream=False), json=payload)
         if resp.status_code >= 400:
             message = f"API error {resp.status_code}: {resp.text[:500]}"
-            if resp.status_code == 401:
+            if resp.status_code in config.AUTH_REFRESH_STATUS_CODES:
                 raise AuthExpiredError(message)
             if _retryable_status(resp.status_code):
                 raise RetryableApiError(message, resp.headers.get("Retry-After"))
@@ -854,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.4.9 → python_agent_harness-1.5.5.1}/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.4.9 → python_agent_harness-1.5.5.1}/python_agent_harness/config.py

@@ -1,7 +1,4 @@
-"""Configuration defaults for python-agent-harness.
-
-Mirrors the defcustom defaults of the Emacs gptel-agent-harness.
-"""
+"""Configuration defaults for python-agent-harness."""
 
 from __future__ import annotations
 
@@ -131,6 +128,14 @@ API_RETRY_MAX = 3  # max attempts per request (initial + retries)
 API_RETRY_BASE_DELAY = 1.0  # base backoff (seconds), doubled per attempt
 API_RETRY_MAX_DELAY = 30.0  # per-attempt backoff cap (seconds)
 
+# HTTP status codes that should trigger auth-refresh (key re-read from
+# config/env) instead of being treated as transient retryable errors.
+# 401 is always included (standard "Unauthorized").  Some API gateways
+# return 502 or other 5xx codes when the backend auth token has expired
+# rather than a proper 401 — add those here so the client refreshes the
+# key instead of pointlessly retrying the same expired credential.
+AUTH_REFRESH_STATUS_CODES: list[int] = [401, 502]
+
 # ---- tool execution ----------------------------------------------------------
 SUBAGENT_MAX_ROUNDS = 60
 # Tool execution mirrors gptel's `gptel--handle-tool-use': synchronous
@@ -234,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,
@@ -453,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.1/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.4.9 → python_agent_harness-1.5.5.1}/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.4.9 → python_agent_harness-1.5.5.1}/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:
@@ -156,6 +157,11 @@ class Session:
         # active clones are tracked so cancel()/close() can reach them.
         self._subagent_clients_lock = threading.Lock()
         self._active_subagent_clients: list[Client] = []
+        # guards _skill_index_cache: parallel readonly tool threads
+        # (e.g. multiple Skill calls in one round) can hit the lazy
+        # cache build simultaneously — double-checked locking prevents
+        # redundant filesystem scans and the data race on the cache tuple
+        self._skill_index_lock = threading.Lock()
         self.store = SessionPersistence(
             project_dir=project_dir,
             model=model,
@@ -178,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.
@@ -377,10 +394,18 @@ class Session:
         return hit[0] if hit else None
 
     def _skill_index(self) -> dict[str, tuple[str, str]]:
-        """Return the cached name -> (path, description) skill index."""
+        """Return the cached name -> (path, description) skill index.
+
+        Thread-safe via double-checked locking: parallel readonly tool
+        threads (e.g. multiple Skill calls in one round) can reach the
+        lazy cache build simultaneously — the lock ensures only one
+        thread scans the filesystem and writes the cache tuple.
+        """
         key = self._skill_dir
         if self._skill_index_cache is None or self._skill_index_cache[0] != key:
-            self._skill_index_cache = (key, index_skills(key))
+            with self._skill_index_lock:
+                if self._skill_index_cache is None or self._skill_index_cache[0] != key:
+                    self._skill_index_cache = (key, index_skills(key))
         return self._skill_index_cache[1]
 
     def _find_skill_dir(self) -> str | None:
@@ -695,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)
     # ------------------------------------------------------------------
@@ -739,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}"