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

langchain_agentx/provider/model_profile.py

@@ -0,0 +1,156 @@
+"""provider/model_profile.py — 模型能力参数配置对象与注册表。
+
+职责：
+    - ModelProfile：持有单个模型的能力参数（context_window / max_output_tokens / 默认采样参数等）
+    - ModelProfileRegistry：从「内置 + 外部」两层 yaml 加载，并按 model_id_prefix 做最长前缀匹配
+
+链路位置：
+    - provider/openai.py、provider/anthropic.py：读取默认采样参数与输出上限（P1 接入）
+    - loop/config/model_context_resolver.py：解析 context_window（P2 接入）
+
+当前裁剪范围：
+    - 仅负责参数加载与匹配；不负责 loop 业务判断、不负责 env/.env 加载、不做运行时热重载。
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, ClassVar
+
+logger = logging.getLogger(__name__)
+
+
+def _builtin_profiles_path() -> Path:
+    # langchain_agentx/provider/model_profile.py -> langchain_agentx/config/model_profiles.yaml
+    return Path(__file__).resolve().parents[1] / "config" / "model_profiles.yaml"
+
+
+@dataclass(frozen=True)
+class ModelProfile:
+    """单个模型的能力参数（纯数据持有，无业务逻辑）。"""
+
+    model_id_prefix: str
+    context_window: int
+    max_output_tokens: int
+    provider: str  # "claude" | "openai"
+    supports_cache: bool = False
+    default_temperature: float = 0.7
+    default_top_p: float | None = None
+
+    PROVIDERS: ClassVar[frozenset[str]] = frozenset({"claude", "openai"})
+
+    def __post_init__(self) -> None:
+        if self.provider not in self.PROVIDERS:
+            msg = f"invalid provider={self.provider!r}, must be one of {sorted(self.PROVIDERS)}"
+            raise ValueError(msg)
+        if self.context_window <= 0 or self.max_output_tokens <= 0:
+            raise ValueError("context_window/max_output_tokens must be positive")
+        if not self.model_id_prefix or not str(self.model_id_prefix).strip():
+            raise ValueError("model_id_prefix must be non-empty")
+
+
+@dataclass
+class ModelProfileRegistry:
+    """两层 yaml 加载 + model_id_prefix 最长前缀优先匹配。"""
+
+    profiles: dict[str, ModelProfile] = field(default_factory=dict)
+    defaults: ModelProfile = field(
+        default_factory=lambda: ModelProfile(
+            model_id_prefix="__default__",
+            context_window=32_000,
+            max_output_tokens=8_192,
+            provider="openai",
+            supports_cache=False,
+            default_temperature=0.7,
+            default_top_p=0.5,
+        )
+    )
+
+    @classmethod
+    def from_files(cls, *, agent_home_dir: Path | None = None) -> "ModelProfileRegistry":
+        """从内置配置与可选外部配置构造一个独立 registry。"""
+        registry = cls()
+        registry.load(agent_home_dir=agent_home_dir)
+        return registry
+
+    def load(self, *, agent_home_dir: Path | None = None) -> None:
+        """加载内置 yaml，再用外部 yaml 覆盖。"""
+        try:
+            import yaml  # type: ignore[import-not-found]
+        except Exception:
+            # P0：缺依赖时回退 defaults；P1/P2 的接线会依赖此处输出可观测 warning
+            logger.warning("pyyaml 未安装，跳过 model_profiles.yaml 加载，使用 defaults 兜底")
+            return
+
+        builtin_path = _builtin_profiles_path()
+        builtin_profiles, builtin_defaults = self._parse_yaml(yaml, builtin_path)
+
+        external_profiles: dict[str, ModelProfile] = {}
+        external_defaults: ModelProfile | None = None
+        if agent_home_dir is not None:
+            ext_path = agent_home_dir / "provider" / "model_profiles.yaml"
+            if ext_path.exists():
+                external_profiles, external_defaults = self._parse_yaml(yaml, ext_path)
+                logger.debug("已加载外部模型配置: %s (%d 条)", ext_path, len(external_profiles))
+
+        merged = {**builtin_profiles, **external_profiles}
+        self.defaults = external_defaults or builtin_defaults or self.defaults
+        self.profiles = merged
+
+    def get(self, model_id: str) -> ModelProfile:
+        """按 model_id_prefix 做最长前缀优先匹配；未命中返回 defaults。"""
+        if not model_id:
+            return self.defaults
+        matched: ModelProfile | None = None
+        for p in self.profiles.values():
+            if model_id.startswith(p.model_id_prefix):
+                if matched is None or len(p.model_id_prefix) > len(matched.model_id_prefix):
+                    matched = p
+        return matched or self.defaults
+
+    def _parse_yaml(
+        self, yaml_mod: Any, path: Path
+    ) -> tuple[dict[str, ModelProfile], ModelProfile | None]:
+        try:
+            raw = yaml_mod.safe_load(path.read_text(encoding="utf-8")) or {}
+        except Exception as e:
+            logger.warning("model_profiles.yaml 解析失败 %s: %s", path, e)
+            return {}, None
+
+        defaults_profile: ModelProfile | None = None
+        if isinstance(raw, dict) and raw.get("defaults"):
+            defaults_profile = self._parse_profile({"model_id_prefix": "__default__", **raw["defaults"]})
+
+        result: dict[str, ModelProfile] = {}
+        for item in (raw.get("profiles") or []) if isinstance(raw, dict) else []:
+            if not isinstance(item, dict):
+                continue
+            try:
+                p = self._parse_profile(item)
+            except Exception as e:
+                logger.warning("跳过无效 profile 条目 %s: %s", item, e)
+                continue
+            result[p.model_id_prefix] = p
+
+        return result, defaults_profile
+
+    @staticmethod
+    def _parse_profile(item: dict[str, Any]) -> ModelProfile:
+        return ModelProfile(
+            model_id_prefix=str(item["model_id_prefix"]),
+            context_window=int(item["context_window"]),
+            max_output_tokens=int(item["max_output_tokens"]),
+            provider=str(item.get("provider", "openai")),
+            supports_cache=bool(item.get("supports_cache", False)),
+            default_temperature=float(item.get("default_temperature", 0.7)),
+            default_top_p=item.get("default_top_p", None),
+        )
+
+
+__all__ = [
+    "ModelProfile",
+    "ModelProfileRegistry",
+]
+

langchain_agentx/provider/openai.py

@@ -0,0 +1,89 @@
+"""provider/openai.py — OpenAI 兼容 ChatModel 工厂（可复用组合件）。
+
+职责：
+    - 从环境变量读取 OpenAI 兼容服务配置（key/base_url/model）。
+    - 组装并返回 CompatibleChatOpenAI。
+
+约束：
+    - 不加载 .env；由调用方（例如 examples）负责把 .env 注入到环境变量。
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from langchain_core.language_models.chat_models import BaseChatModel
+
+from .compatible_chat_openai import CompatibleChatOpenAI
+from .env import get_env_first
+from .model_profile import ModelProfileRegistry
+
+
+def _sanitize_proxy_env_for_openai_compat() -> None:
+    """部分 http 客户端不接受 socks:// 代理，移除异常 all_proxy。"""
+    for key in ("all_proxy", "ALL_PROXY"):
+        value = os.environ.get(key)
+        if not value:
+            continue
+        if value.strip().lower().startswith("socks://"):
+            os.environ.pop(key, None)
+
+
+def get_chat_openai(
+    *,
+    model: str | None = None,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    temperature: float | None = None,
+    max_tokens: int | None = None,
+    top_p: float | None = None,
+    streaming: bool = True,
+    model_profile_registry: ModelProfileRegistry | None = None,
+    **kwargs: Any,
+) -> BaseChatModel:
+    _sanitize_proxy_env_for_openai_compat()
+
+    resolved_api_key = api_key or get_env_first(
+        "LANGCHAIN_AGENTX_OPENAI_API_KEY",
+        "OPENAI_API_KEY",
+    )
+    resolved_base_url = base_url or get_env_first(
+        "LANGCHAIN_AGENTX_OPENAI_BASE_URL",
+        "OPENAI_BASE_URL",
+    )
+    resolved_model = model or get_env_first("LANGCHAIN_AGENTX_MODEL") or "gpt-4o-mini"
+    profile = (
+        model_profile_registry.get(resolved_model)
+        if model_profile_registry is not None
+        else ModelProfileRegistry().defaults
+    )
+
+    if not resolved_api_key or not resolved_base_url:
+        raise RuntimeError(
+            "缺少 OpenAI 兼容端点配置：请设置 OPENAI_API_KEY（或 LANGCHAIN_AGENTX_OPENAI_API_KEY）"
+            " 以及 OPENAI_BASE_URL（或 LANGCHAIN_AGENTX_OPENAI_BASE_URL）。"
+            " 默认模型名可通过 LANGCHAIN_AGENTX_MODEL 或 model 参数指定。"
+        )
+
+    resolved_temperature = profile.default_temperature if temperature is None else float(temperature)
+    resolved_max_tokens = profile.max_output_tokens if max_tokens is None else int(max_tokens)
+    resolved_top_p = profile.default_top_p if top_p is None else float(top_p)
+
+    init_kwargs: dict[str, Any] = {
+        "model": resolved_model,
+        "api_key": resolved_api_key,
+        "base_url": resolved_base_url.rstrip("/"),
+        "temperature": resolved_temperature,
+        "max_tokens": resolved_max_tokens,
+        "streaming": streaming,
+        **kwargs,
+    }
+    if resolved_top_p is not None:
+        init_kwargs["top_p"] = resolved_top_p
+
+    return CompatibleChatOpenAI(**init_kwargs)
+
+
+__all__ = ["get_chat_openai"]
+

langchain_agentx/session/__init__.py

@@ -0,0 +1,17 @@
+"""Session 容器导出。"""
+
+from .agent_session import AgentSession
+from .conversation_recovery import load_session_messages
+from .conversation_factory import create_conversation_session
+from .conversation_session import ConversationSession
+from .factory import create_agent_session
+from .protocol import LoopContainer
+
+__all__ = [
+    "AgentSession",
+    "ConversationSession",
+    "LoopContainer",
+    "create_agent_session",
+    "create_conversation_session",
+    "load_session_messages",
+]

langchain_agentx/session/agent_session.py

@@ -0,0 +1,320 @@
+"""
+session/agent_session.py — 进程级 Session 生命周期容器。
+
+职责：
+    负责触发进程级 SESSION_START/SESSION_END，封装多次 loop invoke，并维护跨 loop 状态。
+
+链路位置：
+    作为 Agent Loop 外层容器供 CLI/应用复用，对应 A01/A03 约定的 LoopContainer 协议。
+
+当前裁剪范围：
+    当前实现覆盖最小生命周期与 active_files 累积；memory manager 通过注入方式可选接入。
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import time
+from uuid import uuid4
+from typing import Any, AsyncIterator, Callable
+
+from langchain_core.messages import HumanMessage
+from langgraph.graph.state import CompiledStateGraph
+
+from ..command import CommandContext, CommandDispatcher, CommandRegistry
+from ..command.builtin import (
+    make_clear_command,
+    make_compact_command,
+    make_memory_command,
+    make_reload_plugins_command,
+)
+from ..loop.context.compaction_service import default_loop_context_compaction
+from ..loop.context.message_utils import total_estimated_tokens_for_messages
+from ..loop.hook.types import HookContext, HookEvent
+from ..memory.memdir.agent_memory import drain_pending_agent_memory_extraction
+from ..memory.memdir.extractor import drain_pending_extraction
+from ..plugin.loader import PluginLoader
+from ..plugin.registries import AgentRegistry, CommandRegistry as PluginCommandRegistry, SkillRegistry
+from ..plugin.types import PluginLoadResult
+from ..loop.subagent.transcript import SubagentTranscriptStore
+from ..workspace.config import AgentWorkspaceConfig
+
+logger = logging.getLogger(__name__)
+
+
+class AgentSession:
+    """进程级 session 容器。"""
+
+    def __init__(
+        self,
+        graph: CompiledStateGraph | None,
+        session_id: str,
+        workspace_cfg: AgentWorkspaceConfig,
+        hook_engine: Any,
+        *,
+        graph_factory: Callable[..., CompiledStateGraph] | None = None,
+        plugin_loader: PluginLoader | None = None,
+        transcript_writer: SubagentTranscriptStore | None = None,
+        container_type: str = "interactive",
+        enable_trace: bool = True,
+    ) -> None:
+        self._graph = graph
+        self._graph_factory = graph_factory
+        self._session_id = session_id
+        self._workspace_cfg = workspace_cfg
+        self._hook_engine = hook_engine
+        self._active_files: list[str] = []
+        self._messages: list[Any] = []
+        self._container_type = container_type
+        self._enable_trace = enable_trace
+        self._transcript_writer = transcript_writer
+        self._last_transcript_uuid: str | None = None
+        self._session_memory_manager: Any | None = None
+        self._skill_registry = SkillRegistry()
+        self._command_registry = PluginCommandRegistry()
+        self._agent_registry = AgentRegistry()
+        self._runtime_command_registry = CommandRegistry()
+        self._register_builtin_commands()
+        self._dispatcher = CommandDispatcher(
+            self._runtime_command_registry,
+            plugin_command_registry=self._command_registry,
+        )
+        self._plugin_loader: PluginLoader | None
+        if not workspace_cfg.plugins_enabled:
+            self._plugin_loader = None
+        else:
+            self._plugin_loader = plugin_loader or PluginLoader(
+                workspace_config=workspace_cfg,
+                hook_engine=hook_engine,
+                skill_registry=self._skill_registry,
+                command_registry=self._command_registry,
+                agent_registry=self._agent_registry,
+            )
+
+    async def __aenter__(self) -> "AgentSession":
+        if self._graph is None:
+            self._graph = self._build_graph()
+        if self._plugin_loader is not None:
+            load_result = await self._plugin_loader.load_all(container_type="interactive")
+            load_result.log_errors(logger)
+        await self._execute_hook(HookEvent.SESSION_START)
+        return self
+
+    async def __aexit__(self, *_) -> None:
+        if self._session_memory_manager is not None:
+            await self._session_memory_manager.drain(timeout=30.0)
+        await drain_pending_extraction(timeout_ms=60_000)
+        await drain_pending_agent_memory_extraction(timeout_ms=60_000)
+        await self._execute_hook(HookEvent.SESSION_END)
+        if self._plugin_loader is not None:
+            await self._plugin_loader.unload_all()
+
+    async def run_loop(self, user_input: str) -> dict[str, Any]:
+        if self._graph is None:
+            raise RuntimeError("AgentSession graph is not initialized")
+        appended_message = HumanMessage(content=user_input)
+        self._messages.append(appended_message)
+        baseline_count = len(self._messages)
+        try:
+            result = await self._graph.ainvoke(
+                {
+                    "messages": list(self._messages),
+                    "_session_id": self._session_id,
+                }
+            )
+        except Exception:
+            # 回滚本轮 append，避免异常路径重复累积 user 消息。
+            if self._messages and self._messages[-1] is appended_message:
+                self._messages.pop()
+            raise
+        if isinstance(result, dict) and isinstance(result.get("messages"), list):
+            new_messages = list(result["messages"])
+            self._messages = new_messages
+            self._append_transcript_message(appended_message)
+            for message in new_messages[baseline_count:]:
+                self._append_transcript_message(message)
+        self._active_files.extend(self._extract_accessed_files(result))
+        return dict(result)
+
+    async def stream_loop_events(
+        self,
+        user_input: str,
+        *,
+        config: dict[str, Any] | None = None,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """
+        流式执行一轮 loop，复用 AgentSession 的消息上下文。
+
+        说明：
+            该方法用于需要 astream_events 的场景（如 SSE），执行完成后会尝试
+            从 on_chain_end(LangGraph) 事件回填消息列表，保持与 run_loop 一致的上下文累积语义。
+        """
+        if self._graph is None:
+            raise RuntimeError("AgentSession graph is not initialized")
+        appended_message = HumanMessage(content=user_input)
+        self._messages.append(appended_message)
+        baseline_count = len(self._messages)
+        output_messages: list[Any] | None = None
+        try:
+            async for event in self._graph.astream_events(
+                {
+                    "messages": list(self._messages),
+                    "_session_id": self._session_id,
+                },
+                config=config,
+                version="v2",
+            ):
+                if event.get("event") == "on_chain_end" and event.get("name") == "LangGraph":
+                    data = event.get("data", {}) or {}
+                    output = data.get("output")
+                    if isinstance(output, dict) and isinstance(output.get("messages"), list):
+                        output_messages = list(output["messages"])
+                yield event
+        except Exception:
+            if self._messages and self._messages[-1] is appended_message:
+                self._messages.pop()
+            raise
+        if output_messages is not None:
+            self._messages = output_messages
+            self._append_transcript_message(appended_message)
+            for message in output_messages[baseline_count:]:
+                self._append_transcript_message(message)
+
+    @property
+    def active_files(self) -> list[str]:
+        return list(self._active_files)
+
+    @property
+    def dispatcher(self) -> CommandDispatcher:
+        return self._dispatcher
+
+    def clear_context(self) -> None:
+        self._messages.clear()
+
+    async def compact_context(self) -> tuple[int, int]:
+        before_tokens = total_estimated_tokens_for_messages(self._messages, num_chars_per_token=4)
+        patch = default_loop_context_compaction().run({"messages": self._messages})
+        if isinstance(patch.get("messages"), list):
+            self._messages = list(patch["messages"])
+        after_tokens = total_estimated_tokens_for_messages(self._messages, num_chars_per_token=4)
+        if self._transcript_writer is not None:
+            self._append_compact_boundary(before_tokens=before_tokens, after_tokens=after_tokens)
+        return before_tokens, after_tokens
+
+    async def reload_plugins(self) -> PluginLoadResult:
+        if self._plugin_loader is None:
+            return PluginLoadResult(enabled=[], errors=[])
+        result = await self._plugin_loader.reload(container_type=self._container_type)
+        result.log_errors(logger)
+        return result
+
+    def get_memory_summary(self, sub_cmd: str = "show") -> str:
+        memory_path = self._workspace_cfg.session_memory_path(self._session_id)
+        if sub_cmd == "clear":
+            if memory_path.exists():
+                memory_path.unlink()
+            return "记忆已清除"
+        if not memory_path.exists():
+            return "（暂无记忆摘要）"
+        content = memory_path.read_text(encoding="utf-8").strip()
+        return content or "（暂无记忆摘要）"
+
+    def _build_context(self) -> CommandContext:
+        return CommandContext(
+            session_id=self._session_id,
+            session=self,
+            workspace_cfg=self._workspace_cfg,
+            hook_engine=self._hook_engine,
+            plugin_loader=self._plugin_loader,
+            extra={"container_type": self._container_type},
+        )
+
+    async def dispatch_command(self, user_input: str):
+        return await self._dispatcher.dispatch(user_input, self._build_context())
+
+    def list_commands(self) -> list[dict[str, object]]:
+        return self._runtime_command_registry.list_for_help()
+
+    async def _execute_hook(self, event: HookEvent) -> None:
+        ctx = HookContext(event=event, state={}, session_id=self._session_id)
+        # HookEngine 当前主接口是 execute；若未来扩展 execute_async，优先兼容新接口。
+        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
+            # 一旦存在 execute_async，就不再回落执行 execute，避免双执行歧义。
+            return
+        execute = getattr(self._hook_engine, "execute", None)
+        if not callable(execute):
+            return
+        out = execute(ctx)
+        if inspect.isawaitable(out):
+            await out
+
+    @staticmethod
+    def _extract_accessed_files(result: Any) -> list[str]:
+        if not isinstance(result, dict):
+            return []
+        files = result.get("_accessed_files")
+        if not isinstance(files, list):
+            return []
+        return [item for item in files if isinstance(item, str)]
+
+    def _build_graph(self) -> CompiledStateGraph:
+        if self._graph_factory is None:
+            raise RuntimeError("AgentSession requires either graph or graph_factory")
+        getter = lambda: list(self._active_files)
+        return self._graph_factory(
+            active_files_getter=getter,
+            container_type=self._container_type,
+            enable_trace=self._enable_trace,
+        )
+
+    def _append_transcript_message(self, message: Any) -> None:
+        if self._transcript_writer is None:
+            return
+        record = self._serialize_message_for_transcript(message)
+        self._append_transcript_record(record)
+
+    def _append_compact_boundary(self, *, before_tokens: int, after_tokens: int) -> None:
+        record = {
+            "type": "compact_boundary",
+            "summary": f"compacted context {before_tokens}->{after_tokens}",
+        }
+        self._append_transcript_record(record)
+
+    def _append_transcript_record(self, payload: dict[str, Any]) -> None:
+        if self._transcript_writer is None:
+            return
+        uuid = str(uuid4())
+        record = {
+            **payload,
+            "uuid": uuid,
+            "logical_parent_uuid": self._last_transcript_uuid,
+            "ts": time.time(),
+        }
+        self._last_transcript_uuid = uuid
+        self._transcript_writer.append_message(self._session_id, record)
+
+    @staticmethod
+    def _serialize_message_for_transcript(message: Any) -> dict[str, Any]:
+        role = getattr(message, "type", type(message).__name__.lower())
+        content = getattr(message, "content", "")
+        if isinstance(content, list):
+            normalized_content: Any = [str(item) for item in content]
+        elif isinstance(content, str):
+            normalized_content = content
+        else:
+            normalized_content = str(content)
+        return {"type": str(role), "role": str(role), "content": normalized_content}
+
+    def _register_builtin_commands(self) -> None:
+        self._runtime_command_registry.register(make_clear_command())
+        self._runtime_command_registry.register(make_compact_command())
+        self._runtime_command_registry.register(make_memory_command())
+        self._runtime_command_registry.register(make_reload_plugins_command())
+
+
+__all__ = ["AgentSession"]

langchain_agentx/session/conversation_factory.py

@@ -0,0 +1,87 @@
+"""
+session/conversation_factory.py — ConversationSession 入口工厂。
+
+职责：
+    统一组装 ConversationSession 所需 graph_factory、workspace 配置与 hook_engine。
+
+链路位置：
+    作为 Web/IM 对话场景创建 ConversationSession 的便捷入口。
+
+当前裁剪范围：
+    仅覆盖基础参数透传，不包含 HTTP 框架集成。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from langchain_core.messages import BaseMessage
+from langchain_core.language_models.chat_models import BaseChatModel
+
+from ..loop.graph.factory import create_loop_agent
+from ..loop.hook import HookEngine, HooksConfigSnapshot, HookRegistry, WorkspaceTrustChecker
+from ..workspace import resolve_agent_workspace_config
+from .conversation_session import ConversationSession
+
+
+def create_conversation_session(
+    model: str | BaseChatModel,
+    *,
+    conversation_id: str | None = None,
+    workspace_root: str | Path | None = None,
+    agent_home: str = ".langchain_agentx",
+    hooks: HookRegistry | None = None,
+    hook_engine: Any | None = None,
+    initial_messages: list[BaseMessage] | None = None,
+    permission_resolver: Any | None = None,
+    **loop_kwargs: Any,
+) -> ConversationSession:
+    """创建 ConversationSession。conversation_id 未传时自动生成。"""
+    resolved_id = conversation_id or f"conv-{uuid4().hex}"
+    workspace_cfg = resolve_agent_workspace_config(
+        workspace_root=workspace_root or Path.cwd(),
+        agent_home=agent_home,
+    )
+    if hook_engine is None:
+        snapshot = hooks.build_snapshot() if hooks is not None else HooksConfigSnapshot()
+        hook_engine = HookEngine(
+            snapshot,
+            trust_checker=WorkspaceTrustChecker(
+                headless=False,
+                workspace_trust_accepted=workspace_cfg.workspace_trust_accepted,
+            ),
+        )
+
+    resolved_permission_resolver = permission_resolver
+    if resolved_permission_resolver is None and "permission_resolver" in loop_kwargs:
+        resolved_permission_resolver = loop_kwargs.pop("permission_resolver")
+
+    def _graph_factory(
+        session_id: str,
+        container_type: str = "conversation",
+        **_ignored: Any,
+    ) -> Any:
+        return create_loop_agent(
+            model,
+            session_id=session_id,
+            workspace_root=workspace_cfg.workspace_root,
+            agent_home=workspace_cfg.agent_home,
+            workspace_trust_accepted=workspace_cfg.workspace_trust_accepted,
+            hooks=hooks,
+            permission_resolver=resolved_permission_resolver,
+            container_type=container_type,
+            **loop_kwargs,
+        )
+
+    return ConversationSession(
+        graph_factory=_graph_factory,
+        conversation_id=resolved_id,
+        workspace_cfg=workspace_cfg,
+        hook_engine=hook_engine,
+        initial_messages=list(initial_messages or []),
+    )
+
+
+__all__ = ["create_conversation_session"]