python-agent-harness 1.5.5.7__tar.gz → 1.5.5.9__tar.gz

{python_agent_harness-1.5.5.7/python_agent_harness.egg-info → python_agent_harness-1.5.5.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-agent-harness
-Version: 1.5.5.7
+Version: 1.5.5.9
 Summary: A lightweight, hackable mini-OpenCode written in Python.
 Author-email: Huming Chen <chenhuming@gmail.com>
 License-Expression: MIT
@@ -105,6 +105,7 @@ Edit `~/.config/python-agent-harness/config.json` and set your `base_url`, `api_
 
 - **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.
+- **Image & text attachments** — attach an image or a text file with `@path` in your message (e.g. `@screenshot.png`, `@README.md`): images (PNG/JPEG/GIF/WebP, up to 20 MB, magic-byte validated) become multimodal `image_url` parts, text files are inlined as text. Only images and text files are supported as input. Path supports web-url for image as well.
 - **Coding tools** — `Agent`, `TodoWrite`, `Glob`, `Grep`, `Read`, `Insert`, `Edit` (including unified diffs), `Write`, `Mkdir`, `Bash`, `Skill`, `Question`, `LSP`, and `PlanExit`. Synchronous tools execute sequentially, but a round made up entirely of read-only tools (`Read`, `Glob`, `Grep`, `Skill`, `LSP`) 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`.
@@ -145,7 +146,8 @@ All LLM settings live in a single JSON configuration file. Environment variables
     "api_key": "sk-...",
     "model": "gpt-5-mini",
     "reasoning_effort": null,
-    "stream": true
+    "stream": true,
+    "supports_image_input": false
   },
   "models": {
     "_comment": "Named LLM profiles for /model switching. Partial settings; unset keys inherit the main llm.",
@@ -171,7 +173,8 @@ All LLM settings live in a single JSON configuration file. Environment variables
     "max_tokens": null,
     "timeout": null,
     "reasoning_effort": null,
-    "stream": null
+    "stream": null,
+    "supports_image_input": null
   },
   "default_agent": null,
   "paths": {
@@ -210,7 +213,7 @@ All LLM settings live in a single JSON configuration file. Environment variables
 
 ### Configuration options
 
-- **`llm`** — main LLM configuration. Optional keys include `temperature`, `max_tokens`, `timeout`, `reasoning_effort`, and `stream`. Values such as `reasoning_effort` are passed to the API as-is when set. `run --no-stream` overrides `stream`.
+- **`llm`** — main LLM configuration. Optional keys include `temperature`, `max_tokens`, `timeout`, `reasoning_effort`, `stream`, and `supports_image_input`. Values such as `reasoning_effort` are passed to the API as-is when set. `run --no-stream` overrides `stream`. `supports_image_input` (default `false`) controls whether `@path` image attachments are sent to the model or stripped with a warning.
 - **`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.
@@ -225,10 +228,58 @@ All LLM settings live in a single JSON configuration file. Environment variables
 ## Usage
 
 ```sh
-python-agent-harness run [project-dir]
+python-agent-harness run [--project DIR]
 ```
 
-Launches the interactive TUI agent. If `project-dir` is omitted, the current directory is used.
+Launches the interactive TUI agent. If `--project` is omitted, the current directory is used.
+
+### Headless mode
+
+```sh
+python-agent-harness headless [prompt] [--project DIR] [--restore [SPEC]] [--model NAME]
+```
+
+Runs a single prompt without the TUI — for CI, scripting, and piping.
+The assistant's answer is written to stdout once the run completes;
+tool/status events go to stderr, so the answer stream stays clean.
+Interactive prompts are auto-answered (`confirm` → yes, `ask` →
+"Unanswered"), so a run never blocks.
+
+- The prompt is a positional argument; when omitted it is read from stdin:
+
+  ```sh
+  python-agent-harness headless "fix the failing test"
+  echo "fix the failing test" | python-agent-harness headless
+  ```
+
+- `--restore` continues a saved session (the conversation auto-saves after
+  each response). Bare `--restore` uses the most recent session; a SPEC may
+  be a file path or a title substring:
+
+  ```sh
+  python-agent-harness headless "now add tests" --restore
+  python-agent-harness headless "next step" --restore parser-refactor
+  ```
+
+- `--model NAME` selects the model: a profile from the `models` config
+  section (same as the TUI's `/model`), or a raw model name on the
+  configured endpoint when no such profile exists. An explicit `--model`
+  wins over the model restored by `--restore`.
+
+- `--json` emits the run as JSON lines on stdout instead of plain text —
+  one `{"type": ...}` object per line: `start` (echoes the prompt and
+  submit warnings), `delta` (streamed text chunks), `notify` (tool and
+  status events, with `kind`/`data`), `log`, and a final `result` (the
+  filtered answer plus any `errors`). Diagnostics (restore/model notes,
+  a plain-text echo of error events) still go to stderr, so one pipe
+  carries the structured stream. Exit codes are unchanged.
+
+  ```sh
+  python-agent-harness headless "fix it" --json | jq -c 'select(.type=="result")'
+  ```
+
+- Exit code is 0 on success, 1 when the prompt was empty (only failed
+  `@file` references), the run raised an agent error, or the restore failed.
 
 ### Slash commands
 
@@ -282,30 +333,6 @@ You are a personal assistant. You do NOT modify files or run shell commands.
 | **Tools** | Can restrict (`allow_planexit=False`) | All tools, minus the agent's `exclude_tools` |
 | **Ctrl-C** | Restores to default prompt | Stays on the custom agent |
 
-## Project layout
-
-```text
-python_agent_harness/
-├── agent.py           # Agent FSM core: states, transitions, supervision
-├── tool_runner.py     # Tool-call execution/delivery + history salvage
-├── context_manager.py # Context-ratio tracking + compaction
-├── client.py          # OpenAI-compatible streaming client (httpx)
-├── models.py          # Message / ToolCall / ToolSpec data classes
-├── token_estimator.py # CJK-aware token estimation + calibration
-├── planmode.py        # Plan/build modes + plan-file lifecycle
-├── prompts.py         # Prompt loading + system-prompt assembly
-├── persistence.py     # Session persistence + titles
-├── session.py         # Session wiring hub + MCP lifecycle
-├── subagent.py        # Sub-agent runner + error containment
-├── commands.py        # Init/review/custom command definitions
-├── cli.py             # CLI entry points
-├── tui/               # Rich + prompt_toolkit TUI (package)
-├── diffrender.py      # Unified diff generation + Rich rendering
-├── lsp/               # Built-in LSP client
-├── mcp/               # Optional MCP client
-└── tools/             # Tool implementations + registry
-```
-
 ## Development
 
 Requires Python ≥ 3.11. CI runs against Python 3.11, 3.12, and 3.13 on Linux, MacOS and Windows.

{python_agent_harness-1.5.5.7 → python_agent_harness-1.5.5.9}/README.md

@@ -71,6 +71,7 @@ Edit `~/.config/python-agent-harness/config.json` and set your `base_url`, `api_
 
 - **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.
+- **Image & text attachments** — attach an image or a text file with `@path` in your message (e.g. `@screenshot.png`, `@README.md`): images (PNG/JPEG/GIF/WebP, up to 20 MB, magic-byte validated) become multimodal `image_url` parts, text files are inlined as text. Only images and text files are supported as input. Path supports web-url for image as well.
 - **Coding tools** — `Agent`, `TodoWrite`, `Glob`, `Grep`, `Read`, `Insert`, `Edit` (including unified diffs), `Write`, `Mkdir`, `Bash`, `Skill`, `Question`, `LSP`, and `PlanExit`. Synchronous tools execute sequentially, but a round made up entirely of read-only tools (`Read`, `Glob`, `Grep`, `Skill`, `LSP`) 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`.
@@ -111,7 +112,8 @@ All LLM settings live in a single JSON configuration file. Environment variables
     "api_key": "sk-...",
     "model": "gpt-5-mini",
     "reasoning_effort": null,
-    "stream": true
+    "stream": true,
+    "supports_image_input": false
   },
   "models": {
     "_comment": "Named LLM profiles for /model switching. Partial settings; unset keys inherit the main llm.",
@@ -137,7 +139,8 @@ All LLM settings live in a single JSON configuration file. Environment variables
     "max_tokens": null,
     "timeout": null,
     "reasoning_effort": null,
-    "stream": null
+    "stream": null,
+    "supports_image_input": null
   },
   "default_agent": null,
   "paths": {
@@ -176,7 +179,7 @@ All LLM settings live in a single JSON configuration file. Environment variables
 
 ### Configuration options
 
-- **`llm`** — main LLM configuration. Optional keys include `temperature`, `max_tokens`, `timeout`, `reasoning_effort`, and `stream`. Values such as `reasoning_effort` are passed to the API as-is when set. `run --no-stream` overrides `stream`.
+- **`llm`** — main LLM configuration. Optional keys include `temperature`, `max_tokens`, `timeout`, `reasoning_effort`, `stream`, and `supports_image_input`. Values such as `reasoning_effort` are passed to the API as-is when set. `run --no-stream` overrides `stream`. `supports_image_input` (default `false`) controls whether `@path` image attachments are sent to the model or stripped with a warning.
 - **`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.
@@ -191,10 +194,58 @@ All LLM settings live in a single JSON configuration file. Environment variables
 ## Usage
 
 ```sh
-python-agent-harness run [project-dir]
+python-agent-harness run [--project DIR]
 ```
 
-Launches the interactive TUI agent. If `project-dir` is omitted, the current directory is used.
+Launches the interactive TUI agent. If `--project` is omitted, the current directory is used.
+
+### Headless mode
+
+```sh
+python-agent-harness headless [prompt] [--project DIR] [--restore [SPEC]] [--model NAME]
+```
+
+Runs a single prompt without the TUI — for CI, scripting, and piping.
+The assistant's answer is written to stdout once the run completes;
+tool/status events go to stderr, so the answer stream stays clean.
+Interactive prompts are auto-answered (`confirm` → yes, `ask` →
+"Unanswered"), so a run never blocks.
+
+- The prompt is a positional argument; when omitted it is read from stdin:
+
+  ```sh
+  python-agent-harness headless "fix the failing test"
+  echo "fix the failing test" | python-agent-harness headless
+  ```
+
+- `--restore` continues a saved session (the conversation auto-saves after
+  each response). Bare `--restore` uses the most recent session; a SPEC may
+  be a file path or a title substring:
+
+  ```sh
+  python-agent-harness headless "now add tests" --restore
+  python-agent-harness headless "next step" --restore parser-refactor
+  ```
+
+- `--model NAME` selects the model: a profile from the `models` config
+  section (same as the TUI's `/model`), or a raw model name on the
+  configured endpoint when no such profile exists. An explicit `--model`
+  wins over the model restored by `--restore`.
+
+- `--json` emits the run as JSON lines on stdout instead of plain text —
+  one `{"type": ...}` object per line: `start` (echoes the prompt and
+  submit warnings), `delta` (streamed text chunks), `notify` (tool and
+  status events, with `kind`/`data`), `log`, and a final `result` (the
+  filtered answer plus any `errors`). Diagnostics (restore/model notes,
+  a plain-text echo of error events) still go to stderr, so one pipe
+  carries the structured stream. Exit codes are unchanged.
+
+  ```sh
+  python-agent-harness headless "fix it" --json | jq -c 'select(.type=="result")'
+  ```
+
+- Exit code is 0 on success, 1 when the prompt was empty (only failed
+  `@file` references), the run raised an agent error, or the restore failed.
 
 ### Slash commands
 
@@ -248,30 +299,6 @@ You are a personal assistant. You do NOT modify files or run shell commands.
 | **Tools** | Can restrict (`allow_planexit=False`) | All tools, minus the agent's `exclude_tools` |
 | **Ctrl-C** | Restores to default prompt | Stays on the custom agent |
 
-## Project layout
-
-```text
-python_agent_harness/
-├── agent.py           # Agent FSM core: states, transitions, supervision
-├── tool_runner.py     # Tool-call execution/delivery + history salvage
-├── context_manager.py # Context-ratio tracking + compaction
-├── client.py          # OpenAI-compatible streaming client (httpx)
-├── models.py          # Message / ToolCall / ToolSpec data classes
-├── token_estimator.py # CJK-aware token estimation + calibration
-├── planmode.py        # Plan/build modes + plan-file lifecycle
-├── prompts.py         # Prompt loading + system-prompt assembly
-├── persistence.py     # Session persistence + titles
-├── session.py         # Session wiring hub + MCP lifecycle
-├── subagent.py        # Sub-agent runner + error containment
-├── commands.py        # Init/review/custom command definitions
-├── cli.py             # CLI entry points
-├── tui/               # Rich + prompt_toolkit TUI (package)
-├── diffrender.py      # Unified diff generation + Rich rendering
-├── lsp/               # Built-in LSP client
-├── mcp/               # Optional MCP client
-└── tools/             # Tool implementations + registry
-```
-
 ## Development
 
 Requires Python ≥ 3.11. CI runs against Python 3.11, 3.12, and 3.13 on Linux, MacOS and Windows.

{python_agent_harness-1.5.5.7 → python_agent_harness-1.5.5.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-agent-harness"
-version = "1.5.5.7"
+version = "1.5.5.9"
 description = "A lightweight, hackable mini-OpenCode written in Python."
 authors = [
     {name = "Huming Chen", email = "chenhuming@gmail.com"}
@@ -57,7 +57,7 @@ dev = [
 ]
 
 [project.scripts]
-python-agent-harness = "python_agent_harness.cli:main"
+python-agent-harness = "python_agent_harness.entry.cli:main"
 
 [tool.setuptools.packages.find]
 include = ["python_agent_harness*"]
@@ -90,10 +90,14 @@ source = ["python_agent_harness"]
 branch = true
 # The console/TUI entry points aren't exercised by unittest; omit the ones
 # that would otherwise drag the number down without adding signal.
-omit = ["python_agent_harness/__main__.py"]
+omit = [
+    "python_agent_harness/__main__.py",
+]
 
 [tool.coverage.report]
 show_missing = true
-# Current line + branch coverage is ~98%. Gate at 90 to leave headroom for
-# small changes while still catching real regressions. Raise as coverage grows.
-fail_under = 90
+# Linux/macOS gate: 95%.  Windows CI enforces 94% with tools/bash.py
+# omitted instead (see .github/workflows/ci.yml): that module is the
+# posix PTY/spawn backend whose body cannot execute on Windows, where
+# tools/bash_win.py runs in its place.
+fail_under = 95

{python_agent_harness-1.5.5.7 → python_agent_harness-1.5.5.9}/python_agent_harness/__init__.py

@@ -1,13 +1,14 @@
 """python-agent-harness: a Python port of the gptel-agent-harness."""
 
-from .client import Client, LLMClient
+from .core.models import AgentMode, ImagePart, Message, TextPart, ToolCall, ToolSpec
+from .entry.cli import main  # noqa: F401  (public lib surface: main entry point)
+from .llm.client import Client, LLMClient
 from .lsp.config import LSPConfig, LSPServerConfig
 from .mcp.config import MCPConfig, MCPServerConfig
 from .mcp.manager import MCPManager
-from .models import AgentMode, Message, ToolCall, ToolSpec
-from .session import Session
+from .session.session import Session
 
-__version__ = "1.5.5.7"
+__version__ = "1.5.5.9"
 
 __all__ = [
     "Client",
@@ -20,6 +21,8 @@ __all__ = [
     "MCPManager",
     "MCPServerConfig",
     "Message",
+    "TextPart",
+    "ImagePart",
     "ToolCall",
     "ToolSpec",
     "__version__",

{python_agent_harness-1.5.5.7 → python_agent_harness-1.5.5.9}/python_agent_harness/__main__.py

@@ -1,5 +1,5 @@
 import sys
 
-from .cli import main
+from .entry.cli import main
 
 sys.exit(main())

python_agent_harness-1.5.5.9/python_agent_harness/core/__init__.py

@@ -0,0 +1 @@
+"""Core engine: agent loop, tool dispatch, models, and context utilities."""

{python_agent_harness-1.5.5.7/python_agent_harness → python_agent_harness-1.5.5.9/python_agent_harness/core}/agent.py

@@ -37,8 +37,9 @@ from __future__ import annotations
 
 from typing import Any, Protocol
 
-from . import config
-from .client import LLMClient
+from ..llm.client import LLMClient
+from ..session import config
+from ..tools.base import PendingToolResult
 from .context_manager import ContextManager
 from .models import Message, ToolCall
 from .token_estimator import context_window_for, estimate_payload_tokens
@@ -47,7 +48,6 @@ from .tool_runner import (
     ToolRunner,
     sanitize_tool_result,  # noqa: F401  (tests import it from .agent)
 )
-from .tools.base import PendingToolResult
 
 
 class _SupervisorSession(Protocol):
@@ -229,7 +229,7 @@ class AgentLoop:
         """Update the session's context ratio (see ContextManager)."""
         # the estimator functions are resolved here — in the agent
         # module namespace — so tests patching
-        # python_agent_harness.agent.estimate_payload_tokens keep
+        # python_agent_harness.core.token_estimator.estimate_payload_tokens keep
         # intercepting the call site
         self._context_manager.update_context_ratio(estimate_payload_tokens, context_window_for)
 
@@ -463,12 +463,14 @@ class AgentLoop:
                 max_tokens = session.max_tokens
                 reasoning_effort = session.reasoning_effort
                 stream = session.stream
+                supports_image_input = session.supports_image_input
             else:
                 client = self._client or session.subagent_client
                 temperature = session.subagent_temperature
                 max_tokens = session.subagent_max_tokens
                 reasoning_effort = session.subagent_reasoning_effort
                 stream = session.subagent_stream
+                supports_image_input = session.subagent_supports_image_input
             assistant, usage = client.chat(
                 self.messages,
                 tools=tools if session.tools_enabled else None,
@@ -477,6 +479,7 @@ class AgentLoop:
                 max_tokens=max_tokens,
                 reasoning_effort=reasoning_effort,
                 stream=stream,
+                supports_image_input=supports_image_input,
                 # sub-agents must not stream into the parent's live
                 # stream row — their text is private until returned
                 on_delta=(safe_delta if self.top_level else None),

{python_agent_harness-1.5.5.7/python_agent_harness → python_agent_harness-1.5.5.9/python_agent_harness/core}/context_manager.py

@@ -10,8 +10,8 @@ from __future__ import annotations
 
 from typing import Any
 
-from . import config
-from .prompts import compact_summary, compacted_messages, user_prompt_texts
+from ..prompts import compact_summary, compacted_messages, user_prompt_texts
+from ..session import config
 
 
 class ContextManager:
@@ -20,7 +20,7 @@ class ContextManager:
     ``update_context_ratio`` receives the two token-estimator functions
     from the loop's delegate so the call site keeps resolving them
     through the ``agent`` module namespace (tests patch
-    ``python_agent_harness.agent.estimate_payload_tokens``).  The
+    ``python_agent_harness.core.token_estimator.estimate_payload_tokens``).  The
     context window comes from the session's client (config-file aware,
     resolved per access); ``context_window_for`` is only the fallback
     for clients without the property.

{python_agent_harness-1.5.5.7/python_agent_harness → python_agent_harness-1.5.5.9/python_agent_harness/core}/models.py

@@ -2,10 +2,11 @@
 
 from __future__ import annotations
 
+import base64
 import enum
 import json
 from dataclasses import dataclass, field
-from typing import Any
+from typing import Any, Union
 
 
 class AgentMode(enum.Enum):
@@ -13,6 +14,60 @@ class AgentMode(enum.Enum):
     PLAN = "plan"
 
 
+@dataclass
+class TextPart:
+    """A plain-text content part in a multimodal message."""
+
+    text: str
+
+    def to_api(self) -> dict[str, Any]:
+        return {"type": "text", "text": self.text}
+
+
+@dataclass
+class ImagePart:
+    """A provider-neutral image attachment in a multimodal message.
+
+    The image source is either ``data`` (raw image bytes, with
+    ``media_type`` as the MIME type, e.g. ``"image/png"``) or ``url``
+    (an http(s) URL the provider fetches).  At least one of the two must
+    be set; when both are, ``url`` wins.  The conversion to a provider-specific format (e.g.
+    OpenAI's ``image_url`` with a data URL or a plain URL) happens in
+    ``to_api()``, which is only called at the API serialization boundary
+    (``Message.to_api()`` → ``Client._payload``), never in the agent core.
+
+    ``path`` (when set) is the filesystem path the image was attached
+    from.  It is metadata only — never sent to the API — and lets
+    session persistence record where the image came from so a restored
+    session can re-attach it.  Images that did not originate from a
+    path (drag-drop, URLs) leave it None.
+    """
+
+    data: bytes | None = None
+    media_type: str = "image/png"
+    path: str | None = None
+    url: str | None = None
+
+    @classmethod
+    def from_url(cls, url: str) -> ImagePart:
+        return cls(url=url)
+
+    def to_api(self) -> dict[str, Any]:
+        if self.url:
+            return {"type": "image_url", "image_url": {"url": self.url}}
+        if self.data is None:
+            raise ValueError("ImagePart requires either data or url")
+        b64 = base64.b64encode(self.data).decode("ascii")
+        return {
+            "type": "image_url",
+            "image_url": {"url": f"data:{self.media_type};base64,{b64}"},
+        }
+
+
+# Type alias for the individual parts a Message.content list may contain.
+ContentPart = Union[TextPart, ImagePart, str, "dict[str, Any]"]
+
+
 @dataclass
 class ToolCall:
     """A tool invocation requested by the model."""
@@ -30,14 +85,15 @@ class Message:
     """One conversation message in OpenAI-compatible format.
 
     ``role`` is one of system/user/assistant/tool.
-    ``content`` may be a str or a list of parts (multimodal).
+    ``content`` may be a str, a list of parts (multimodal:
+    ``TextPart``, ``ImagePart``, plain strings, or dicts), or None.
     ``tool_calls`` carries requested tool invocations on assistant messages.
     ``tool_call_id`` links a tool message to its assistant tool call.
     ``reasoning`` holds reasoning content if the backend reports it.
     """
 
     role: str
-    content: str | list[Any] | None = None
+    content: str | list[ContentPart] | None = None
     tool_calls: list[ToolCall] | None = None
     tool_call_id: str | None = None
     reasoning: str | None = None
@@ -79,6 +135,11 @@ class Message:
         confuse the model, so it is stripped here at the API boundary.
         The stored ``content`` is left untouched (the TUI collapses the
         reasoning for display via its own helper).
+
+        For multimodal content (a list of parts), each part is
+        serialized to its provider-specific dict representation via
+        ``to_api()`` when the part is a ``TextPart`` or ``ImagePart``;
+        strings and dicts pass through unchanged.
         """
         content = self.content
         if self.reasoning and isinstance(content, str):
@@ -87,8 +148,17 @@ class Message:
             stripped = content.lstrip()
             if stripped.startswith(self.reasoning):
                 return stripped[len(self.reasoning) :].lstrip("\n")
+        if isinstance(content, list):
+            return [self._part_to_api(p) for p in content]
         return content
 
+    @staticmethod
+    def _part_to_api(part: ContentPart) -> Any:
+        """Serialize one content part to its provider-specific dict."""
+        if isinstance(part, (TextPart, ImagePart)):
+            return part.to_api()
+        return part
+
     def text(self) -> str:
         """Plain text of the message; empty when no text parts exist."""
         if isinstance(self.content, str):
@@ -98,6 +168,8 @@ class Message:
             for p in self.content:
                 if isinstance(p, str):
                     parts.append(p)
+                elif isinstance(p, TextPart):
+                    parts.append(p.text)
                 elif isinstance(p, dict):
                     if isinstance(p.get("text"), str):
                         parts.append(p["text"])

{python_agent_harness-1.5.5.7/python_agent_harness → python_agent_harness-1.5.5.9/python_agent_harness/core}/planmode.py

@@ -21,7 +21,7 @@ import string
 import tempfile
 from pathlib import Path
 
-from . import config
+from ..session import config
 from .models import AgentMode
 
 

{python_agent_harness-1.5.5.7/python_agent_harness → python_agent_harness-1.5.5.9/python_agent_harness/core}/subagent.py

@@ -7,11 +7,11 @@ mode, sub-agents receive the read-only reminder.
 
 from __future__ import annotations
 
-from . import config
+from ..llm.client import LLMClient
+from ..prompts import load_agent_prompt
+from ..session import config
 from .agent import run_agent_loop
-from .client import LLMClient
 from .models import Message
-from .prompts import load_agent_prompt
 
 
 def _subagent_system_prompt(session: object) -> str | None:
@@ -20,12 +20,22 @@ def _subagent_system_prompt(session: object) -> str | None:
     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.
+    no sub-agent prompt configured, the default bundled one is used
+    (with tool instructions from the session's registry, filtered by
+    the sub-agent excluded tools).
     """
     own = getattr(session, "subagent_system_prompt", None)
     if own:
         return own
-    return load_agent_prompt(config.DEFAULT_SUBAGENT_PROMPT_FILE)
+    registry = getattr(session, "registry", None)
+    tool_instructions = registry.tool_instructions() if registry else None
+    skill_dir = getattr(session, "_skill_dir", None)
+    return load_agent_prompt(
+        config.DEFAULT_SUBAGENT_PROMPT_FILE,
+        skill_dir=skill_dir,
+        tool_instructions=tool_instructions,
+        excluded_tools=config.SUBAGENT_EXCLUDED_TOOLS,
+    )
 
 
 def run_subagent(

{python_agent_harness-1.5.5.7/python_agent_harness → python_agent_harness-1.5.5.9/python_agent_harness/core}/token_estimator.py

@@ -11,7 +11,7 @@ import json
 import os
 import re
 
-from . import config
+from ..session import config
 
 
 def is_cjk_char(c: str) -> bool:
@@ -31,6 +31,16 @@ def is_cjk_char(c: str) -> bool:
 _CJK_RE = re.compile(r"[\u3000-\u9fff\uf900-\ufaff\uff00-\uffef\U00020000-\U0002fa1f]")
 
 
+# Flat per-image token estimate.  Vision models bill images by tile /
+# detail level, not by the size of the base64 data URL, so counting the
+# encoded bytes as text would over-count by orders of magnitude.  A flat
+# heuristic keeps images visible to context-ratio tracking and, crucially,
+# stops the base64 blob from poisoning the token calibrator on turns that
+# contain an image.  ~1200 tokens is a reasonable mid-range approximation
+# for a single "high detail" image across common providers.
+IMAGE_TOKEN_ESTIMATE = 1200
+
+
 def estimate_tokens(text: str) -> int:
     """Estimate tokens in TEXT: Latin ~4 chars/token, CJK ~2 chars/token."""
     if not text:
@@ -132,4 +142,26 @@ def payload_text(system: object, messages: list[dict], tools: list[dict]) -> str
 
 
 def estimate_payload_tokens(system: object, messages: list[dict], tools: list[dict]) -> int:
-    return estimate_tokens(payload_text(system, messages, tools))
+    text_tokens = estimate_tokens(payload_text(system, messages, tools))
+    return text_tokens + count_image_tokens(messages)
+
+
+def count_image_tokens(messages: list[dict]) -> int:
+    """Estimate the token cost of image parts across MESSAGES.
+
+    Each image content part (``{"type": "image_url", ...}``) is charged
+    a flat ``IMAGE_TOKEN_ESTIMATE``.  ``payload_text`` deliberately skips
+    the base64 data URL (its length is not proportional to the model's
+    real image token cost), so this is the sole place images enter the
+    estimate — keeping them visible to context-ratio tracking without
+    letting the encoded blob distort the calibrator.
+    """
+    total = 0
+    for msg in messages:
+        content = msg.get("content")
+        if not isinstance(content, list):
+            continue
+        for p in content:
+            if isinstance(p, dict) and p.get("type") == "image_url":
+                total += IMAGE_TOKEN_ESTIMATE
+    return total

{python_agent_harness-1.5.5.7/python_agent_harness → python_agent_harness-1.5.5.9/python_agent_harness/core}/tool_runner.py

@@ -22,9 +22,9 @@ import time
 from concurrent.futures import ThreadPoolExecutor
 from typing import Any
 
-from . import config
+from ..session import config
+from ..tools.base import PendingToolResult
 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)."