codex-agent-framework 0.1.28__tar.gz → 0.1.30__tar.gz

{codex_agent_framework-0.1.28 → codex_agent_framework-0.1.30}/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project will be documented in this file.
 
 This project loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses semantic versioning where practical.
 
+## [0.1.29] - 2026-05-15
+### Changed
+- Split the Textual TUI implementation into focused modules for app wiring, transcript rendering, status display, styling, log windowing, and render state.
+- Replace ad hoc TUI app calls and duplicate display tracking with a typed bridge and centralized deduplication state.
+- Move terminal resize handling into the Textual app so transcript, input sizing, layout cache, and status refresh stay coordinated.
+
+### Fixed
+- Invalidate selectable log layout metrics cleanly on terminal resize to keep wrapped transcript rendering accurate.
+- Keep TUI turn rendering state scoped to the active turn without leaking tool or slash-command display markers.
+
+### Tests
+- Update TUI/chat regression coverage for the extracted bridge/state modules and resize handling; the current suite validates at 577 passed.
+
 ## [0.1.28] - 2026-05-15
 ### Added
 - Add `StreamManager` as a dedicated stream-processing manager and expose it through the package API.

codex_agent_framework-0.1.30/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: codex-agent-framework
+Version: 0.1.30
+Summary: A lightweight event-driven Codex agent runtime.
+Author: Baptiste
+License-Expression: MIT
+Keywords: agent,ai,codex,openai,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: audioop-lts; python_version >= "3.13"
+Requires-Dist: beautifulsoup4
+Requires-Dist: codex-backend-sdk>=0.3.1
+Requires-Dist: fastapi
+Requires-Dist: filetype
+Requires-Dist: modict
+Requires-Dist: mss
+Requires-Dist: numpy
+Requires-Dist: odfpy
+Requires-Dist: openai
+Requires-Dist: openpyxl
+Requires-Dist: pathspec
+Requires-Dist: pillow
+Requires-Dist: playwright
+Requires-Dist: pydub
+Requires-Dist: pypdf
+Requires-Dist: pynteract>=0.1.4
+Requires-Dist: pywinctl
+Requires-Dist: python-docx
+Requires-Dist: PyYAML
+Requires-Dist: regex
+Requires-Dist: requests
+Requires-Dist: rich
+Requires-Dist: textual
+Requires-Dist: tiktoken
+Requires-Dist: trafilatura
+Requires-Dist: uvicorn
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# codex-agent
+
+`codex-agent-framework` is a local-first Python framework for building and running tool-using AI agents.
+
+Use it as a ready-to-run terminal assistant, or import `Agent` when you want to build your own agentic workflow in Python.
+
+> Early alpha: APIs are still evolving and breaking changes are expected while the architecture settles.
+
+## Why codex-agent?
+
+codex-agent is meant to be a transparent, hackable local harness for power users and developers:
+
+- **Local-first runtime**: sessions, memory, config, plugins, logs, and work files live under your local runtime directory.
+- **Multiple entry points**: TUI, headless CLI, Python SDK, and local FastAPI server.
+- **Plugin-first design**: tools, providers, slash commands, hooks, events, prompt sections, and stream processors are extension points.
+- **Observable agent loop**: turns return structured results and emit events that UIs and integrations can stream.
+- **Built-in practical tools**: files, shell, Python, context, memory, planner, scheduler, browser/desktop automation, and subagents.
+
+## Quick start
+
+Install the package:
+
+```bash
+python -m pip install codex-agent-framework
+```
+
+For the recommended local setup, run:
+
+```bash
+codex-agent bootstrap -- -y
+```
+
+`bootstrap` installs desktop/browser/tray dependencies, installs the user services, and starts them. It is currently aimed mostly at Debian-like Linux systems. Use an X11 session for the best desktop automation support; Wayland is fine if you do not use the desktop plugin.
+
+Open the assistant:
+
+```bash
+codex-agent
+```
+
+If a local agent server is already running, the TUI connects to it. Otherwise `codex-agent` starts a temporary server for that TUI session and shuts it down when the TUI exits. New sessions are anchored to the directory where you launch `codex-agent`; see [CLI and runtime](docs/cli-and-runtime.md#session-root-and-working-directory).
+
+Inside the TUI, start with:
+
+```text
+/help
+/sessions
+/new_session
+/load_session latest
+/compact
+/config
+```
+
+Use `/compact` when a long session needs to reduce its active context. It keeps a backend summary and prunes older raw history from the active session file.
+
+## Python in 30 seconds
+
+```python
+from codex_agent import Agent
+
+agent = Agent(session="new")
+turn = agent("Summarize this repository in three practical bullet points.")
+
+print(turn.result)
+```
+
+Stream live events when building your own UI or integration:
+
+```python
+from codex_agent import Agent, ResponseContentDeltaEvent
+
+agent = Agent(session="new")
+stream = agent.stream("Explain what this project does.")
+
+for event in stream:
+    if isinstance(event, ResponseContentDeltaEvent):
+        print(event.delta, end="", flush=True)
+
+turn = stream.turn
+print("\ncompleted:", turn.completed)
+```
+
+Add a small tool:
+
+```python
+import subprocess
+from codex_agent import Agent, tool
+
+@tool
+def list_changed_files() -> list[str]:
+    """Return modified or untracked files in the current git repository."""
+    output = subprocess.check_output(["git", "status", "--short"], text=True)
+    return [line[3:] for line in output.splitlines() if line.strip()]
+
+agent = Agent(session="latest")
+agent.add_tool(list_changed_files)
+agent("What changed locally?")
+```
+
+## Main ways to use it
+
+| Mode | Entry point | Best for |
+| --- | --- | --- |
+| Interactive TUI | `codex-agent` | Daily local assistant usage. |
+| Python SDK | `Agent(...)` | Scripts, notebooks, tests, custom applications. |
+| Headless CLI | `codex-agent run ...` | Automation and shell pipelines. |
+| Persistent server | `codex-agent start server` | Long-lived local service used by UIs or scripts. |
+| Runtime plugins | `~/.codex-agent/plugins/*.py` | Local customization without forking the project. |
+
+Useful CLI commands:
+
+```bash
+codex-agent status --json
+codex-agent tools
+codex-agent sessions list
+codex-agent config get
+codex-agent run "Run a quick repository health check."
+git diff -- README.md | codex-agent run --stdin "Review this documentation diff."
+```
+
+## Built-in capability map
+
+| Area | Examples | Purpose |
+| --- | --- | --- |
+| Files/content | `read`, `view`, `write`, `edit` | Strict text reads, broad extraction, exact-string edits. |
+| Shell/Python | `bash`, `python` | Local command execution and persistent Python work. |
+| Context/status | `context_status`, `context_compact` | Inspect and manage the active context window. |
+| Memory/planner | `memory_add`, `planner_create` | Durable semantic memory and persistent named todos. |
+| Scheduler | `scheduler_schedule` | Future turns and post-restart continuation. |
+| Browser/desktop | browser and desktop tools | Persistent Chromium and Linux desktop automation. |
+| Subagents | `subagents_run` | Focused child agents such as the read-only `explorer` profile. |
+
+Select built-ins explicitly when you want a smaller agent:
+
+```python
+agent = Agent(
+    session="latest",
+    builtin_plugins=["files", "content", "bash", "python", "environment", "context"],
+)
+```
+
+`None` loads all built-ins, `[]` loads none, and an explicit list selects plugin module names.
+
+## Documentation
+
+The README is intentionally a façade and quick-start guide. Advanced usage lives in `docs/`:
+
+- [Python SDK](docs/python-sdk.md): `Agent`, turns, streaming, events, config, and interactive sessions.
+- [Plugins and extensions](docs/plugins.md): tools, providers, commands, runtime plugins, stateful plugins, hooks, events, and stream processors.
+- [CLI and runtime](docs/cli-and-runtime.md): TUI, server, headless CLI, sessions, config, runtime files, and service setup.
+- [Built-in capabilities](docs/built-in-capabilities.md): bundled plugins and common usage patterns.
+- [Safety and trust](docs/safety-and-trust.md): local trust model, runtime plugins, server binding, secrets, and risky actions.
+- [Development](docs/development.md): project layout, tests, build, and release checks.
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## Safety notes
+
+This project lets an AI assistant act on the local machine. That is useful, but risky.
+
+Recommended practices:
+
+- Avoid running the agent with elevated privileges.
+- Review tools and runtime plugins before enabling autonomous workflows.
+- Keep secrets out of prompts, logs, committed runtime files, and shared session exports.
+- Treat browser, desktop, shell, file-write, and edit operations as real user actions.
+- Keep important runtime plugins under version control.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

codex_agent_framework-0.1.30/README.md

@@ -0,0 +1,171 @@
+# codex-agent
+
+`codex-agent-framework` is a local-first Python framework for building and running tool-using AI agents.
+
+Use it as a ready-to-run terminal assistant, or import `Agent` when you want to build your own agentic workflow in Python.
+
+> Early alpha: APIs are still evolving and breaking changes are expected while the architecture settles.
+
+## Why codex-agent?
+
+codex-agent is meant to be a transparent, hackable local harness for power users and developers:
+
+- **Local-first runtime**: sessions, memory, config, plugins, logs, and work files live under your local runtime directory.
+- **Multiple entry points**: TUI, headless CLI, Python SDK, and local FastAPI server.
+- **Plugin-first design**: tools, providers, slash commands, hooks, events, prompt sections, and stream processors are extension points.
+- **Observable agent loop**: turns return structured results and emit events that UIs and integrations can stream.
+- **Built-in practical tools**: files, shell, Python, context, memory, planner, scheduler, browser/desktop automation, and subagents.
+
+## Quick start
+
+Install the package:
+
+```bash
+python -m pip install codex-agent-framework
+```
+
+For the recommended local setup, run:
+
+```bash
+codex-agent bootstrap -- -y
+```
+
+`bootstrap` installs desktop/browser/tray dependencies, installs the user services, and starts them. It is currently aimed mostly at Debian-like Linux systems. Use an X11 session for the best desktop automation support; Wayland is fine if you do not use the desktop plugin.
+
+Open the assistant:
+
+```bash
+codex-agent
+```
+
+If a local agent server is already running, the TUI connects to it. Otherwise `codex-agent` starts a temporary server for that TUI session and shuts it down when the TUI exits. New sessions are anchored to the directory where you launch `codex-agent`; see [CLI and runtime](docs/cli-and-runtime.md#session-root-and-working-directory).
+
+Inside the TUI, start with:
+
+```text
+/help
+/sessions
+/new_session
+/load_session latest
+/compact
+/config
+```
+
+Use `/compact` when a long session needs to reduce its active context. It keeps a backend summary and prunes older raw history from the active session file.
+
+## Python in 30 seconds
+
+```python
+from codex_agent import Agent
+
+agent = Agent(session="new")
+turn = agent("Summarize this repository in three practical bullet points.")
+
+print(turn.result)
+```
+
+Stream live events when building your own UI or integration:
+
+```python
+from codex_agent import Agent, ResponseContentDeltaEvent
+
+agent = Agent(session="new")
+stream = agent.stream("Explain what this project does.")
+
+for event in stream:
+    if isinstance(event, ResponseContentDeltaEvent):
+        print(event.delta, end="", flush=True)
+
+turn = stream.turn
+print("\ncompleted:", turn.completed)
+```
+
+Add a small tool:
+
+```python
+import subprocess
+from codex_agent import Agent, tool
+
+@tool
+def list_changed_files() -> list[str]:
+    """Return modified or untracked files in the current git repository."""
+    output = subprocess.check_output(["git", "status", "--short"], text=True)
+    return [line[3:] for line in output.splitlines() if line.strip()]
+
+agent = Agent(session="latest")
+agent.add_tool(list_changed_files)
+agent("What changed locally?")
+```
+
+## Main ways to use it
+
+| Mode | Entry point | Best for |
+| --- | --- | --- |
+| Interactive TUI | `codex-agent` | Daily local assistant usage. |
+| Python SDK | `Agent(...)` | Scripts, notebooks, tests, custom applications. |
+| Headless CLI | `codex-agent run ...` | Automation and shell pipelines. |
+| Persistent server | `codex-agent start server` | Long-lived local service used by UIs or scripts. |
+| Runtime plugins | `~/.codex-agent/plugins/*.py` | Local customization without forking the project. |
+
+Useful CLI commands:
+
+```bash
+codex-agent status --json
+codex-agent tools
+codex-agent sessions list
+codex-agent config get
+codex-agent run "Run a quick repository health check."
+git diff -- README.md | codex-agent run --stdin "Review this documentation diff."
+```
+
+## Built-in capability map
+
+| Area | Examples | Purpose |
+| --- | --- | --- |
+| Files/content | `read`, `view`, `write`, `edit` | Strict text reads, broad extraction, exact-string edits. |
+| Shell/Python | `bash`, `python` | Local command execution and persistent Python work. |
+| Context/status | `context_status`, `context_compact` | Inspect and manage the active context window. |
+| Memory/planner | `memory_add`, `planner_create` | Durable semantic memory and persistent named todos. |
+| Scheduler | `scheduler_schedule` | Future turns and post-restart continuation. |
+| Browser/desktop | browser and desktop tools | Persistent Chromium and Linux desktop automation. |
+| Subagents | `subagents_run` | Focused child agents such as the read-only `explorer` profile. |
+
+Select built-ins explicitly when you want a smaller agent:
+
+```python
+agent = Agent(
+    session="latest",
+    builtin_plugins=["files", "content", "bash", "python", "environment", "context"],
+)
+```
+
+`None` loads all built-ins, `[]` loads none, and an explicit list selects plugin module names.
+
+## Documentation
+
+The README is intentionally a façade and quick-start guide. Advanced usage lives in `docs/`:
+
+- [Python SDK](docs/python-sdk.md): `Agent`, turns, streaming, events, config, and interactive sessions.
+- [Plugins and extensions](docs/plugins.md): tools, providers, commands, runtime plugins, stateful plugins, hooks, events, and stream processors.
+- [CLI and runtime](docs/cli-and-runtime.md): TUI, server, headless CLI, sessions, config, runtime files, and service setup.
+- [Built-in capabilities](docs/built-in-capabilities.md): bundled plugins and common usage patterns.
+- [Safety and trust](docs/safety-and-trust.md): local trust model, runtime plugins, server binding, secrets, and risky actions.
+- [Development](docs/development.md): project layout, tests, build, and release checks.
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## Safety notes
+
+This project lets an AI assistant act on the local machine. That is useful, but risky.
+
+Recommended practices:
+
+- Avoid running the agent with elevated privileges.
+- Review tools and runtime plugins before enabling autonomous workflows.
+- Keep secrets out of prompts, logs, committed runtime files, and shared session exports.
+- Treat browser, desktop, shell, file-write, and edit operations as real user actions.
+- Keep important runtime plugins under version control.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

{codex_agent_framework-0.1.28 → codex_agent_framework-0.1.30}/codex_agent/agent.py

@@ -31,10 +31,15 @@ class Agent:
             **kwargs: Additional keyword arguments to update the agent configuration.
         """
         ensure_runtime_dir()
+        launch_cwd = os.path.abspath(os.getcwd())
+        self.process_launch_cwd = launch_cwd
+        explicit_root_dir = kwargs.pop("root_dir", None)
+        explicit_cwd = kwargs.pop("cwd", None)
         self.init_execution_environment()
         self.config_manager=ConfigManager(self)
         self.config_manager.load()
         self.config_manager.update(kwargs, save=False)
+        self.init_working_directories(root_dir=explicit_root_dir or launch_cwd, cwd=explicit_cwd)
         self.config_manager.apply_openai_capability_defaults()
         self.events=EventBus()
         self.tools_manager=ToolsManager(self)
@@ -198,6 +203,51 @@ class Agent:
             "text_content": text_content,
         }
 
+    def normalize_directory(self, path):
+        return os.path.abspath(os.path.expanduser(str(path)))
+
+    def sync_working_cwd_from_process(self, save_session=False):
+        cwd = self.normalize_directory(os.getcwd())
+        self.config.cwd = cwd
+        session = getattr(self, "session", None)
+        if session:
+            session.cwd = cwd
+            if save_session:
+                self.save_session()
+        return cwd
+
+    def set_process_cwd(self, cwd, save_session=False):
+        cwd = self.normalize_directory(cwd)
+        os.chdir(cwd)
+        return self.sync_working_cwd_from_process(save_session=save_session)
+
+    def init_working_directories(self, root_dir=None, cwd=None):
+        root_dir = self.normalize_directory(root_dir or getattr(self, "process_launch_cwd", None) or self.config.root_dir)
+        cwd = self.normalize_directory(cwd or root_dir)
+        self.config.root_dir = root_dir
+        self.set_process_cwd(cwd)
+        return self.config.cwd
+
+    def apply_session_working_directories(self):
+        if not self.session:
+            return self.config.cwd
+        root_dir = getattr(self.session, "root_dir", None) or self.config.root_dir or getattr(self, "process_launch_cwd", None)
+        cwd = getattr(self.session, "cwd", None) or root_dir
+        self.config.root_dir = self.normalize_directory(root_dir)
+        self.session.root_dir = self.config.root_dir
+        self.set_process_cwd(cwd)
+        self.session.cwd = self.config.cwd
+        return self.config.cwd
+
+    def working_cwd(self):
+        return self.sync_working_cwd_from_process(save_session=False)
+
+    def resolve_path(self, path):
+        path = os.path.expanduser(str(path))
+        if os.path.isabs(path):
+            return os.path.abspath(path)
+        return os.path.abspath(os.path.join(self.working_cwd(), path))
+
     def init_workfolder(self):
         if not os.path.isdir(self.config.workfolder):
             os.makedirs(self.config.workfolder,exist_ok=True)
@@ -217,8 +267,8 @@ class Agent:
     def load_session(self, session):
         return self.sessions_manager.load(session)
 
-    def start_new_session(self):
-        return self.sessions_manager.start_new()
+    def start_new_session(self, root_dir=None, cwd=None):
+        return self.sessions_manager.start_new(root_dir=root_dir, cwd=cwd)
 
     def delete_session(self, session):
         return self.sessions_manager.delete(session)

{codex_agent_framework-0.1.28 → codex_agent_framework-0.1.30}/codex_agent/agent_runtime.py

@@ -93,7 +93,7 @@ class AgentRuntime(ABC):
         raise NotImplementedError
 
     @abstractmethod
-    def start_new_session(self):
+    def start_new_session(self, root_dir=None, cwd=None):
         raise NotImplementedError
 
     @abstractmethod
@@ -207,8 +207,8 @@ class InProcessAgentRuntime(AgentRuntime):
     def wakeups(self, include_done=True):
         return self.agent.scheduler.list(include_done=include_done)
 
-    def start_new_session(self):
-        return self.agent.start_new_session()
+    def start_new_session(self, root_dir=None, cwd=None):
+        return self.agent.start_new_session(root_dir=root_dir, cwd=cwd)
 
     def load_session(self, session_id):
         return self.agent.load_session(session_id)
@@ -610,8 +610,9 @@ class ProcessAgentRuntime(AgentRuntime):
     def wakeups(self, include_done=True):
         return self._cached_call("wakeups", include_done=include_done)
 
-    def start_new_session(self):
-        result = self.call("start_new_session", timeout=self.command_timeout)
+    def start_new_session(self, root_dir=None, cwd=None):
+        payload = {key: value for key, value in {"root_dir": root_dir, "cwd": cwd}.items() if value is not None}
+        result = self.call("start_new_session", payload, timeout=self.command_timeout)
         self.refresh_cache()
         return result
 
@@ -760,7 +761,7 @@ def run_worker_command(agent, name, payload):
     if name == "wakeups":
         return agent.scheduler.list(include_done=payload.get("include_done", True))
     if name == "start_new_session":
-        return agent.start_new_session()
+        return agent.start_new_session(root_dir=payload.get("root_dir"), cwd=payload.get("cwd"))
     if name == "load_session":
         return agent.load_session(payload.session_id)
     if name == "delete_session":

{codex_agent_framework-0.1.28 → codex_agent_framework-0.1.30}/codex_agent/builtin_commands.py

@@ -87,9 +87,9 @@ def sessions():
 
 
 @command
-def new_session():
+def new_session(root_dir=None, cwd=None):
     agent = get_agent()
-    session = agent.start_new_session()
+    session = agent.start_new_session(root_dir=root_dir, cwd=cwd)
     return f"Created session: {session.session_id}"
 
 

{codex_agent_framework-0.1.28 → codex_agent_framework-0.1.30}/codex_agent/builtin_plugins/bash/__init__.py

@@ -28,7 +28,8 @@ Pass raw shell script text to the tool, not JSON, quotes, or a markdown code fen
         if not content:
             return "No bash command provided."
 
-        hook = self.agent.run_hook("shell.bash.before", content=content, cwd=os.getcwd())
+        cwd = self.agent.working_cwd()
+        hook = self.agent.run_hook("shell.bash.before", content=content, cwd=cwd, root_dir=self.agent.config.root_dir)
         content = hook.payload.content
         cwd = hook.payload.cwd
         response = subprocess.run(

{codex_agent_framework-0.1.28 → codex_agent_framework-0.1.30}/codex_agent/builtin_plugins/content/system.py

@@ -20,7 +20,7 @@ def show(file_or_url: str):
     """
     target = str(file_or_url)
     if not target.startswith(("http://", "https://", "file://")):
-        target = os.path.abspath(os.path.expanduser(target))
+        target = get_agent().resolve_path(target)
 
     opened = open_silently(target)
     if opened:

{codex_agent_framework-0.1.28 → codex_agent_framework-0.1.30}/codex_agent/builtin_plugins/content/vision.py

@@ -5,7 +5,7 @@ from urllib.parse import quote_plus
 from ...browser import get_browser_controller
 from ...desktop import DesktopControlError, get_desktop_controller
 from ...image import ImageMessage, persist_image_url
-from ...tool import tool
+from ...tool import get_agent, tool
 from ...utils import runtime_join
 
 
@@ -122,10 +122,18 @@ def observe_source(source):
     return f"failed: unsupported observe target: {target!r}"
 
 
+def resolve_agent_path(path):
+    try:
+        return get_agent().resolve_path(path)
+    except RuntimeError:
+        return os.path.abspath(os.path.expanduser(str(path)))
+
+
 def observe_path(item):
     path = item.get("path") or item.get("source")
     if not isinstance(path, str) or not path:
         return "failed: path target requires a non-empty 'path'."
+    path = resolve_agent_path(path)
     return validated_image(path, image_name=item.get("image_name"), original_source=path)
 
 
@@ -153,8 +161,11 @@ def observe_url(item):
 
 
 def observe_screen(item):
+    output_path = item.get("output_path")
+    if output_path:
+        output_path = resolve_agent_path(output_path)
     try:
-        path = get_desktop_controller().capture_screen(item.get("output_path"))
+        path = get_desktop_controller().capture_screen(output_path)
     except DesktopControlError as exc:
         return f"failed: local screen screenshot failed: {exc}"
     return validated_image(path, image_name=item.get("image_name", "Screenshot of screen"), original_source="screen")
@@ -162,8 +173,11 @@ def observe_screen(item):
 
 def observe_window(item):
     window_id = item.get("window_id") or item.get("id")
+    output_path = item.get("output_path")
+    if output_path:
+        output_path = resolve_agent_path(output_path)
     try:
-        path = get_desktop_controller().capture_window(window_id, item.get("output_path"))
+        path = get_desktop_controller().capture_window(window_id, output_path)
     except DesktopControlError as exc:
         return f"failed: local window screenshot failed: {exc}"
     return validated_image(path, image_name=item.get("image_name", f"Screenshot of window {window_id}"), original_source=f"window {window_id}")
@@ -180,6 +194,8 @@ def validated_image(path, image_name=None, original_source=None, url_fallback=Fa
 def screenshot_page_url(url, item=None):
     item = item or {}
     path = item.get("output_path")
+    if path:
+        path = resolve_agent_path(path)
     if not path:
         screenshots_dir = runtime_join("images", "screenshots")
         os.makedirs(screenshots_dir, exist_ok=True)