langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/utils/temp_paths.py

@@ -0,0 +1,77 @@
+"""utils/temp_paths.py — 跨平台系统临时目录路径（测试与示例用）。
+
+职责：
+    提供「与 OS 一致的可写临时区」下的 `Path` / `str`，避免在单测与演示中写死 POSIX ``/tmp``，
+    以便在 Windows（通常为 ``%TEMP%``）与 Linux/macOS 上同一套断言与逻辑路径。
+    核心逻辑在 SystemTempLocations；模块级函数为薄封装。
+
+链路位置：
+    单测、examples 中仅需「绝对路径字符串」且不便注入 ``tmp_path`` 时使用。
+
+当前裁剪范围：
+    不负责创建目录或清理文件；调用方按需 ``mkdir`` / 使用 ``tmp_path``。
+    生产业务路径仍应来自 ``AgentWorkspaceConfig`` 等配置层，而非本模块。
+
+工程化约定（与 Claude Code 等 Node 工程对齐思路）：
+    - **命名空间**：首段路径分量使用项目前缀（如 ``langchain_agentx_tool_runtime_test/...``），等价于
+      CC 中 ``join(tmpdir(), 'claude', ...)`` 在系统临时目录下再分一层，减少与其它软件冲突。
+    - **环境变量**：``tempfile.gettempdir()`` 会尊重常见宿主配置（如 Unix ``TMPDIR``、Windows ``TEMP``/``TMP``），
+      不在此模块重复实现；CI 若需固定沙箱目录，应通过设置上述环境变量而非改库代码。
+    - **非安全边界**：本模块**不做** CC ``memdir/paths`` 类对 UNC、盘符根、过短路径的拒绝策略；若路径来自
+      不可信输入，须在策略层校验，勿仅依赖本工具返回的路径。
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+
+class SystemTempLocations:
+    """封装 ``tempfile.gettempdir()`` 下的品牌子路径拼接。"""
+
+    def system_temp_dir(self) -> Path:
+        """返回当前进程可见的系统临时目录（``tempfile.gettempdir()``）。"""
+        return Path(tempfile.gettempdir())
+
+    def under_system_temp(self, *relative_parts: str) -> Path:
+        """``system_temp_dir()`` 下拼接相对路径（至少一段，避免误用根）。"""
+        if not relative_parts:
+            raise ValueError("under_system_temp requires at least one path component")
+        return self.system_temp_dir().joinpath(*relative_parts)
+
+    def under_system_temp_str(self, *relative_parts: str) -> str:
+        """与 :meth:`under_system_temp` 相同，返回 ``str``（便于存入 session_store 等）。"""
+        return str(self.under_system_temp(*relative_parts))
+
+
+_default_locations = SystemTempLocations()
+
+
+def default_system_temp_locations() -> SystemTempLocations:
+    """返回进程内共享的默认实例。"""
+    return _default_locations
+
+
+def system_temp_dir() -> Path:
+    """返回当前进程可见的系统临时目录（``tempfile.gettempdir()``）。"""
+    return _default_locations.system_temp_dir()
+
+
+def under_system_temp(*relative_parts: str) -> Path:
+    """``system_temp_dir()`` 下拼接相对路径（至少一段，避免误用根）。"""
+    return _default_locations.under_system_temp(*relative_parts)
+
+
+def under_system_temp_str(*relative_parts: str) -> str:
+    """与 :func:`under_system_temp` 相同，返回 ``str``（便于存入 session_store 等）。"""
+    return _default_locations.under_system_temp_str(*relative_parts)
+
+
+__all__ = [
+    "SystemTempLocations",
+    "default_system_temp_locations",
+    "system_temp_dir",
+    "under_system_temp",
+    "under_system_temp_str",
+]

langchain_agentx/utils/unc_path.py

@@ -0,0 +1,25 @@
+"""
+utils/unc_path.py — UNC / 双斜线网径前缀检测
+
+职责：为 Grep/Glob（及未来 Read 等）的 validate_input 提供与 CC 一致的 stat 前短路判断，
+      避免对 UNC 路径做本地 stat 触发不必要的远程/凭据面（CC GrepTool/GlobTool validateInput）。
+
+CC 对照：src/tools/GrepTool/GrepTool.ts、src/tools/GlobTool/GlobTool.ts（absolutePath.startsWith('\\\\') || startsWith('//')）。
+
+当前裁剪：仅前缀判定；不解析 \\\\?\\UNC\\ 等扩展设备语法（与 CC 当前检查范围一致）。
+"""
+
+from __future__ import annotations
+
+
+def is_unc_path_skip_local_stat(path: str) -> bool:
+    """
+    若路径在展开后仍表现为 UNC / SMB 风格根前缀，则不在本地做 exists/stat 校验。
+
+    - 反斜杠 UNC：`\\\\server\\share\\...`
+    - 正斜杠根：`//server/share/...`（含部分 POSIX 下 ``//`` 绝对路径形态）
+    """
+    s = path.strip()
+    if not s:
+        return False
+    return s.startswith("\\\\") or s.startswith("//")

langchain_agentx/utils/win_reserved_paths.py

@@ -0,0 +1,51 @@
+"""
+utils/win_reserved_paths.py — Windows 保留设备名路径检测
+
+职责：判断路径中是否出现 Windows 保留名（CON/PRN/AUX/NUL/COM1-9/LPT1-9），
+      供 Read 等工具在本地 I/O 前拒绝误读设备（与 Unix /dev 阻断互补）。
+
+CC 对照：FileReadTool 仍以 Unix 设备表为主；本工程在 win32 上补一层路径段检测。
+
+当前裁剪：仅按 Windows 规则拆分路径段并检查各段 stem（与 COM1.txt 等扩展名规则一致）；
+          非 win32 恒为 False。拆分固定使用 PureWindowsPath，避免在 Linux CI 上 Path 仍为
+          PosixPath 时反斜杠路径被误解析（单段 + stem 误判）。
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import PureWindowsPath
+
+_WIN_RESERVED_STEMS: frozenset[str] = frozenset(
+    {"CON", "PRN", "AUX", "NUL", *(f"COM{i}" for i in range(1, 10)), *(f"LPT{i}" for i in range(1, 10))}
+)
+
+
+def path_uses_windows_reserved_name(path: str) -> bool:
+    """
+    若当前平台为 Windows，且路径任一段（按 Windows 路径规则拆分）的 stem 为保留设备名，则返回 True。
+
+    例如 ``C:\\temp\\NUL``、``C:\\share\\COM1.dat``、末段为 ``CON`` 的路径。
+    """
+    if sys.platform != "win32":
+        return False
+    if not path or not path.strip():
+        return False
+    try:
+        parts = PureWindowsPath(path).parts
+    except (ValueError, OSError):
+        return False
+    for part in parts:
+        seg = part.rstrip("/\\")
+        if not seg:
+            continue
+        # 盘符段如 ``C:`` 无 stem 意义
+        if len(seg) == 2 and seg[1] == ":":
+            continue
+        stem = PureWindowsPath(seg).stem.upper()
+        if stem in _WIN_RESERVED_STEMS:
+            return True
+    return False
+
+
+__all__ = ["path_uses_windows_reserved_name"]

langchain_agentx/workflow/__init__.py

@@ -0,0 +1,7 @@
+"""Workflow 容器导出。"""
+
+from .base import BaseWorkflow
+from .batch import BatchWorkflow
+from .dag import DagWorkflow
+
+__all__ = ["BaseWorkflow", "DagWorkflow", "BatchWorkflow"]

langchain_agentx/workflow/base.py

@@ -0,0 +1,97 @@
+"""
+workflow/base.py — Workflow 编排基类。
+
+职责：
+    封装任务级容器生命周期（start/invoke/end）、并发控制与单次 agent invoke 入口。
+
+链路位置：
+    作为场景化 Workflow 的父类，复用 Agent Loop 并对齐 LoopContainer 生命周期协议。
+
+当前裁剪范围：
+    仅提供 BaseWorkflow 最小契约；Dag/Batch 骨架在独立文件占位。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Literal
+from uuid import uuid4
+
+from ..loop.hook.types import HookContext, HookEvent
+from ..memory.memdir.agent_memory import drain_pending_agent_memory_extraction
+
+
+class BaseWorkflow(ABC):
+    """场景编排基类。"""
+
+    container_type: str = "workflow_task"
+
+    def __init__(
+        self,
+        graph_factory: Callable[..., Any],
+        hook_engine: Any,
+        max_concurrency: int = 4,
+        error_policy: Literal["fail_fast", "best_effort"] = "best_effort",
+    ) -> None:
+        self._graph_factory = graph_factory
+        self._hook_engine = hook_engine
+        self._semaphore = asyncio.Semaphore(max_concurrency)
+        self._error_policy = error_policy
+        self._workflow_id = uuid4().hex[:8]
+
+    async def __aenter__(self) -> "BaseWorkflow":
+        await self._on_workflow_start()
+        return self
+
+    async def __aexit__(self, *_) -> None:
+        await self._on_workflow_end()
+
+    async def run(self, **kwargs: Any) -> Any:
+        async with self:
+            return await self._execute(**kwargs)
+
+    @abstractmethod
+    async def _execute(self, **kwargs: Any) -> Any:
+        """子类实现具体编排逻辑。"""
+
+    async def _invoke_agent(
+        self,
+        messages: list[Any],
+        task_key: str,
+        parent_session_id: str | None = None,
+    ) -> dict[str, Any]:
+        session_id = f"{self._workflow_id}-{task_key}"
+        async with self._semaphore:
+            graph = self._graph_factory(
+                session_id=session_id,
+                parent_conversation_session_id=parent_session_id,
+                is_subagent=parent_session_id is not None,
+                container_type=self.container_type,
+            )
+            result = await graph.ainvoke({"messages": messages})
+            return dict(result) if isinstance(result, dict) else {"result": result}
+
+    async def _on_workflow_start(self) -> None:
+        await self._execute_hook(HookEvent.SESSION_START)
+
+    async def _on_workflow_end(self) -> None:
+        await drain_pending_agent_memory_extraction(timeout_ms=60_000)
+        await self._execute_hook(HookEvent.SESSION_END)
+
+    async def _execute_hook(self, event: HookEvent) -> None:
+        ctx = HookContext(event=event, state={}, session_id=self._workflow_id)
+        execute_async = getattr(self._hook_engine, "execute_async", None)
+        if callable(execute_async):
+            async_out = execute_async(ctx)
+            if inspect.isawaitable(async_out):
+                await async_out
+                return
+        execute = getattr(self._hook_engine, "execute")
+        out = execute(ctx)
+        if inspect.isawaitable(out):
+            await out
+
+
+__all__ = ["BaseWorkflow"]

langchain_agentx/workflow/batch.py

@@ -0,0 +1,55 @@
+"""
+workflow/batch.py — Batch 编排骨架。
+
+职责：
+    为同构批处理任务提供标准执行模板（items -> process x N -> merge），
+    子类实现 _process_item() 和 merge_results() 即可。
+
+链路位置：
+    继承 BaseWorkflow，为批处理型业务 Workflow 提供标准入口。
+
+当前裁剪范围：
+    并发由 BaseWorkflow._semaphore 控制；错误策略由 error_policy 决定。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from abc import abstractmethod
+from typing import Any
+
+from .base import BaseWorkflow
+
+
+class BatchWorkflow(BaseWorkflow):
+    """批处理编排骨架。"""
+
+    async def process_all(self, items: list[Any]) -> Any:
+        """
+        并发处理所有 items，结果交给 merge_results() 聚合。
+
+        best_effort：单个 item 失败记为 None，其余继续。
+        fail_fast：任意 item 失败立即抛异常。
+        """
+        tasks = [self._process_item(item, idx) for idx, item in enumerate(items)]
+        if self._error_policy == "fail_fast":
+            results = await asyncio.gather(*tasks)
+        else:
+            raw_results = await asyncio.gather(*tasks, return_exceptions=True)
+            results = [None if isinstance(item, BaseException) else item for item in raw_results]
+        return self.merge_results(results)
+
+    @abstractmethod
+    async def _process_item(self, item: Any, index: int) -> Any:
+        """子类实现单个 item 的处理逻辑。"""
+
+    @abstractmethod
+    def merge_results(self, results: list[Any]) -> Any:
+        """子类实现多个 item 结果的聚合逻辑。"""
+
+    @abstractmethod
+    async def _execute(self, **kwargs: Any) -> Any:
+        """子类实现入口，通常直接调用 process_all(items)。"""
+
+
+__all__ = ["BatchWorkflow"]

langchain_agentx/workflow/dag.py

@@ -0,0 +1,54 @@
+"""
+workflow/dag.py — DAG 编排骨架。
+
+职责：
+    为有向无环图编排场景提供步骤辅助入口（_run_step），
+    子类通过普通 Python 代码声明步骤依赖与并发关系。
+
+链路位置：
+    继承 BaseWorkflow，为具体业务 Workflow（如 WikiWorkflow）提供结构化骨架。
+
+当前裁剪范围：
+    不做自动 DAG 拓扑调度，步骤顺序与并发由子类 _execute() 控制。
+"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import Any
+
+from .base import BaseWorkflow
+
+
+class DagWorkflow(BaseWorkflow):
+    """
+    DAG 编排骨架。
+
+    子类通过 _run_step() 与 Python 控制流表达依赖与并发。
+    """
+
+    async def _run_step(
+        self,
+        step_name: str,
+        messages: list[Any],
+        *,
+        parent_session_id: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        执行单个 DAG 步骤。
+
+        step_name 作为 task_key，最终生成 session_id = f"{workflow_id}-{step_name}"，
+        trace 可按步骤名检索执行链路。
+        """
+        return await self._invoke_agent(
+            messages=messages,
+            task_key=step_name,
+            parent_session_id=parent_session_id,
+        )
+
+    @abstractmethod
+    async def _execute(self, **kwargs: Any) -> Any:
+        """子类实现具体步骤编排逻辑。"""
+
+
+__all__ = ["DagWorkflow"]

langchain_agentx/workspace/__init__.py

@@ -0,0 +1,13 @@
+from .config import AgentWorkspaceConfig
+from .path_key_normalizer import PathKeyNormalizer, normalize_path_key
+from .resolver import AgentWorkspaceResolver, resolve_agent_workspace_config
+from .validators import AgentWorkspacePathValidator
+
+__all__ = [
+    "AgentWorkspaceConfig",
+    "AgentWorkspaceResolver",
+    "AgentWorkspacePathValidator",
+    "PathKeyNormalizer",
+    "normalize_path_key",
+    "resolve_agent_workspace_config",
+]

langchain_agentx/workspace/config.py

@@ -0,0 +1,140 @@
+"""
+workspace/config.py — AgentWorkspace 路径配置模型
+
+职责：
+    提供 `workspace_root + agent_home` 的派生目录视图（skills/worktrees/tasks/data/db），
+    作为跨模块目录语义的数据模型。
+
+在整体链路中的位置：
+    AgentWorkspaceResolver.resolve()
+      -> AgentWorkspaceConfig
+      -> 各入口按属性读取目标路径。
+
+当前裁剪范围：
+    仅路径派生，不做校验与副作用创建。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import re
+
+from .path_key_normalizer import normalize_path_key
+
+
+def _sanitize_agent_type(agent_type: str) -> str:
+    """安全化 agent_type，避免路径注入；键串先 NFC 与 session_id 同策略。"""
+    normalized = normalize_path_key(str(agent_type or "").strip())
+    normalized = normalized.replace(":", "-")
+    normalized = re.sub(r"[/\\]", "-", normalized)
+    normalized = normalized.replace("..", "-")
+    normalized = normalized.replace("\x00", "")
+    normalized = normalized.strip("-").strip()
+    if not normalized:
+        raise ValueError(f"agent_type {agent_type!r} sanitizes to empty string")
+    return normalized
+
+
+def _normalize_memory_scope(scope: str) -> str:
+    """单路径段 scope（project/user/local 等）做 NFC，并拒绝路径分隔与穿越片段。"""
+    s = normalize_path_key(str(scope or "").strip())
+    if not s:
+        raise ValueError("scope cannot be empty")
+    if re.search(r"[/\\]", s) or ".." in s:
+        raise ValueError(f"invalid scope for agent_memory_dir: {scope!r}")
+    return s
+
+
+@dataclass(frozen=True)
+class AgentWorkspaceConfig:
+    workspace_root: Path
+    agent_home: str = ".langchain_agentx"
+    plugins_enabled: bool = True
+    workspace_trust_accepted: bool = False
+
+    @property
+    def agent_home_dir(self) -> Path:
+        return (self.workspace_root / self.agent_home).resolve()
+
+    @property
+    def skills_dir(self) -> Path:
+        return self.agent_home_dir / "skills"
+
+    @property
+    def worktrees_dir(self) -> Path:
+        return self.agent_home_dir / "worktrees"
+
+    @property
+    def tasks_dir(self) -> Path:
+        return self.agent_home_dir / "tasks"
+
+    @property
+    def data_dir(self) -> Path:
+        return self.agent_home_dir / "data"
+
+    @property
+    def db_dir(self) -> Path:
+        return self.data_dir / "db"
+
+    @property
+    def traces_db_path(self) -> Path:
+        return self.db_dir / "traces.db"
+
+    @property
+    def task_runtime_db_path(self) -> Path:
+        return self.db_dir / "task_runtime.db"
+
+    @property
+    def evaluation_db_path(self) -> Path:
+        return self.db_dir / "evaluation.db"
+
+    @property
+    def memory_dir(self) -> Path:
+        return self.agent_home_dir / "memory"
+
+    @property
+    def memory_entrypoint(self) -> Path:
+        return self.memory_dir / "MEMORY.md"
+
+    @property
+    def sessions_dir(self) -> Path:
+        return self.agent_home_dir / "sessions"
+
+    @property
+    def transcripts_dir(self) -> Path:
+        return self.agent_home_dir / "transcripts"
+
+    @property
+    def workspace_config_path(self) -> Path:
+        return self.agent_home_dir / "workspace_config.json"
+
+    @property
+    def plugins_dir(self) -> Path:
+        return self.agent_home_dir / "plugins"
+
+    @property
+    def plugin_config_path(self) -> Path:
+        return self.agent_home_dir / "plugin_config.json"
+
+    @property
+    def plugin_cache_dir(self) -> Path:
+        return self.agent_home_dir / "plugin_cache"
+
+    def session_memory_path(self, session_id: str) -> Path:
+        sid = normalize_path_key(str(session_id).strip())
+        if not sid:
+            raise ValueError("session_id cannot be empty")
+        return self.sessions_dir / f"{sid}.md"
+
+    @property
+    def session_memory_config_dir(self) -> Path:
+        return self.agent_home_dir / "session-memory" / "config"
+
+    def agent_memory_dir(self, agent_type: str, scope: str = "project") -> Path:
+        sanitized = _sanitize_agent_type(agent_type)
+        sc = _normalize_memory_scope(scope)
+        return self.memory_dir / "agents" / sanitized / sc
+
+    def agent_memory_entrypoint(self, agent_type: str, scope: str = "project") -> Path:
+        return self.agent_memory_dir(agent_type, scope) / "MEMORY.md"

langchain_agentx/workspace/path_key_normalizer.py

@@ -0,0 +1,30 @@
+"""
+workspace/path_key_normalizer.py — 路径字符串键 NFC 稳定化
+
+职责：对作为持久化键 / 文件名片段的路径相关字符串做 Unicode NFC，与 CC `normalize('NFC')` 同向。
+在整体链路中的位置：AgentWorkspaceConfig 派生会话文件路径等边界；不在 expand_path 默认链上调用。
+当前裁剪范围：仅 NFC；不 resolve、不替代 workspace 越界校验（见 validators）。调用方：``session_memory_path``、``_sanitize_agent_type``、``_normalize_memory_scope``（``agent_memory_dir``）。
+"""
+
+from __future__ import annotations
+
+import unicodedata
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class PathKeyNormalizer:
+    """无状态键稳定化；多线程只读安全。"""
+
+    form: str = "NFC"
+
+    def normalize(self, path: str) -> str:
+        return unicodedata.normalize(self.form, path)
+
+
+_DEFAULT_NORMALIZER = PathKeyNormalizer()
+
+
+def normalize_path_key(path: str) -> str:
+    """模块级薄封装：会话 id、未来其它「键串」边界的默认 NFC。"""
+    return _DEFAULT_NORMALIZER.normalize(path)

langchain_agentx/workspace/resolver.py

@@ -0,0 +1,74 @@
+"""
+workspace/resolver.py — AgentWorkspace 配置解析协作者
+
+职责：
+    按统一优先级解析 workspace_root 与 agent_home，并产出
+    AgentWorkspaceConfig，作为全局目录语义单一来源。
+
+在整体链路中的位置：
+    各入口（tool_runtime / task_runtime / loop / observability）
+      -> resolve_agent_workspace_config()
+      -> AgentWorkspaceResolver.resolve()
+
+当前裁剪范围：
+    解析与校验；不直接做业务目录写入。
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .config import AgentWorkspaceConfig
+from .validators import AgentWorkspacePathValidator
+
+DEFAULT_AGENT_HOME = ".langchain_agentx"
+ENV_AGENT_HOME = "LANGCHAIN_AGENTX_AGENT_HOME"
+ENV_WORKSPACE_ROOT = "LANGCHAIN_AGENTX_WORKSPACE_ROOT"
+
+
+class AgentWorkspaceResolver:
+    """Agent workspace 配置解析器。"""
+
+    def __init__(
+        self,
+        *,
+        default_agent_home: str = DEFAULT_AGENT_HOME,
+        env_agent_home: str = ENV_AGENT_HOME,
+        env_workspace_root: str = ENV_WORKSPACE_ROOT,
+        path_validator: AgentWorkspacePathValidator | None = None,
+    ) -> None:
+        self._default_agent_home = default_agent_home
+        self._env_agent_home = env_agent_home
+        self._env_workspace_root = env_workspace_root
+        self._path_validator = path_validator or AgentWorkspacePathValidator()
+
+    def resolve(
+        self,
+        *,
+        workspace_root: str | Path | None = None,
+        agent_home: str | None = None,
+    ) -> AgentWorkspaceConfig:
+        root_raw = workspace_root or os.getenv(self._env_workspace_root) or os.getcwd()
+        root = Path(root_raw).expanduser().resolve()
+        home_raw = (
+            agent_home
+            if agent_home is not None
+            else os.getenv(self._env_agent_home, self._default_agent_home)
+        )
+        home = self._path_validator.validate_agent_home(home_raw)
+        cfg = AgentWorkspaceConfig(workspace_root=root, agent_home=home)
+        self._path_validator.ensure_within_workspace(cfg.workspace_root, cfg.agent_home_dir)
+        return cfg
+
+
+_DEFAULT_RESOLVER = AgentWorkspaceResolver()
+
+
+def resolve_agent_workspace_config(
+    *,
+    workspace_root: str | Path | None = None,
+    agent_home: str | None = None,
+) -> AgentWorkspaceConfig:
+    """兼容入口：调用默认 AgentWorkspaceResolver。"""
+    return _DEFAULT_RESOLVER.resolve(workspace_root=workspace_root, agent_home=agent_home)

langchain_agentx/workspace/validators.py

@@ -0,0 +1,41 @@
+"""
+workspace/validators.py — AgentWorkspace 路径校验协作者
+
+职责：
+    统一封装 workspace 目录相关校验规则（agent_home 合法性、越界检查），
+    作为 resolver 的纯校验依赖，避免调用方散落 if/else 逻辑。
+
+在整体链路中的位置：
+    AgentWorkspaceResolver.resolve()
+      -> AgentWorkspacePathValidator.validate_agent_home()
+      -> AgentWorkspacePathValidator.ensure_within_workspace()
+
+当前裁剪范围：
+    仅覆盖路径规范与越界校验；不承载目录创建与业务策略。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class AgentWorkspacePathValidator:
+    """Agent workspace 路径规则校验器。"""
+
+    def validate_agent_home(self, agent_home: str) -> str:
+        text = (agent_home or "").strip()
+        if not text:
+            raise ValueError("agent_home cannot be empty")
+        path = Path(text)
+        if path.is_absolute():
+            raise ValueError("agent_home must be a relative path")
+        if ".." in path.parts:
+            raise ValueError("agent_home cannot contain '..'")
+        return text
+
+    def ensure_within_workspace(self, workspace_root: Path, candidate: Path) -> Path:
+        base = workspace_root.resolve()
+        resolved = candidate.resolve()
+        if not str(resolved).startswith(str(base)):
+            raise ValueError("Resolved path escapes workspace_root")
+        return resolved