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

langchain_agentx/session/conversation_recovery.py

@@ -0,0 +1,156 @@
+"""
+session/conversation_recovery.py — 会话恢复入口编排。
+
+职责：
+    从 transcript store 读取并清洗消息，重建为可用于 resume 的 BaseMessage 链。
+
+链路位置：
+    为 AgentSession/ConversationSession 提供恢复前置能力。
+
+当前裁剪范围：
+    覆盖 compact 边界定位、unresolved tool_use 过滤、空白 assistant 过滤。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, SystemMessage, ToolMessage
+
+from ..loop.subagent.transcript import SubagentTranscriptStore
+
+
+@dataclass
+class CompactBoundaryLocator:
+    """定位最后一个 compact_boundary 之后的恢复起点。"""
+
+    def find_resume_start(self, records: list[dict[str, Any]]) -> int:
+        last_boundary = -1
+        for idx, record in enumerate(records):
+            if record.get("type") == "compact_boundary":
+                last_boundary = idx
+        if last_boundary < 0:
+            return 0
+        return last_boundary + 1
+
+
+@dataclass
+class RecoveryMessageFilter:
+    """恢复前消息过滤器。"""
+
+    def filter_records(self, records: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        resolved_tool_ids = self._collect_resolved_tool_ids(records)
+        kept: list[dict[str, Any]] = []
+        valid_ai_tool_ids: set[str] = set()
+        for record in records:
+            record_type = str(record.get("type", ""))
+            if record_type == "compact_boundary":
+                continue
+            if self._is_blank_assistant(record):
+                continue
+            if self._is_unresolved_tool_use(record, resolved_tool_ids):
+                continue
+            if record_type in {"ai", "assistant"}:
+                for tool_call_id in self._extract_tool_call_ids(record):
+                    valid_ai_tool_ids.add(tool_call_id)
+            if record_type in {"tool", "tool_result"}:
+                call_id = str(record.get("tool_call_id", ""))
+                if call_id and call_id not in valid_ai_tool_ids:
+                    continue
+            kept.append(record)
+        return kept
+
+    def _collect_resolved_tool_ids(self, records: list[dict[str, Any]]) -> set[str]:
+        resolved: set[str] = set()
+        for record in records:
+            record_type = str(record.get("type", ""))
+            if record_type not in {"tool", "tool_result"}:
+                continue
+            call_id = str(record.get("tool_call_id", ""))
+            if call_id:
+                resolved.add(call_id)
+        return resolved
+
+    def _is_unresolved_tool_use(self, record: dict[str, Any], resolved_ids: set[str]) -> bool:
+        record_type = str(record.get("type", ""))
+        if record_type not in {"ai", "assistant"}:
+            return False
+        tool_call_ids = self._extract_tool_call_ids(record)
+        if not tool_call_ids:
+            return False
+        return any(tool_call_id not in resolved_ids for tool_call_id in tool_call_ids)
+
+    @staticmethod
+    def _extract_tool_call_ids(record: dict[str, Any]) -> list[str]:
+        tool_calls = record.get("tool_calls")
+        if not isinstance(tool_calls, list):
+            return []
+        ids: list[str] = []
+        for call in tool_calls:
+            if not isinstance(call, dict):
+                continue
+            call_id = call.get("id")
+            if isinstance(call_id, str) and call_id:
+                ids.append(call_id)
+        return ids
+
+    @staticmethod
+    def _is_blank_assistant(record: dict[str, Any]) -> bool:
+        record_type = str(record.get("type", ""))
+        if record_type not in {"ai", "assistant"}:
+            return False
+        content = record.get("content")
+        if isinstance(content, str):
+            return content.strip() == ""
+        return False
+
+
+@dataclass
+class SessionRecoveryLoader:
+    """恢复加载器：读取 -> 定位 -> 过滤 -> 反序列化。"""
+
+    boundary_locator: CompactBoundaryLocator = field(default_factory=CompactBoundaryLocator)
+    message_filter: RecoveryMessageFilter = field(default_factory=RecoveryMessageFilter)
+
+    def load_session_messages(
+        self,
+        transcript_store: SubagentTranscriptStore,
+        session_id: str,
+    ) -> list[BaseMessage]:
+        raw = transcript_store.read_transcript(session_id)
+        start_index = self.boundary_locator.find_resume_start(raw)
+        tail = raw[start_index:]
+        filtered = self.message_filter.filter_records(tail)
+        return [self._deserialize_record(record) for record in filtered]
+
+    def _deserialize_record(self, record: dict[str, Any]) -> BaseMessage:
+        record_type = str(record.get("type") or record.get("role") or "")
+        content = record.get("content", "")
+        normalized_content = content if isinstance(content, str) else str(content)
+        if record_type in {"human", "user"}:
+            return HumanMessage(content=normalized_content)
+        if record_type in {"system"}:
+            return SystemMessage(content=normalized_content)
+        if record_type in {"tool", "tool_result"}:
+            tool_call_id = str(record.get("tool_call_id", "recovered-tool-call"))
+            name = str(record.get("name", "tool"))
+            return ToolMessage(content=normalized_content, tool_call_id=tool_call_id, name=name)
+        return AIMessage(content=normalized_content)
+
+
+def load_session_messages(
+    transcript_store: SubagentTranscriptStore,
+    session_id: str,
+) -> list[BaseMessage]:
+    """便捷函数：使用默认 loader 恢复消息。"""
+    return SessionRecoveryLoader().load_session_messages(transcript_store, session_id)
+
+
+__all__ = [
+    "CompactBoundaryLocator",
+    "RecoveryMessageFilter",
+    "SessionRecoveryLoader",
+    "load_session_messages",
+]
+

langchain_agentx/session/conversation_session.py

@@ -0,0 +1,198 @@
+"""
+session/conversation_session.py — 对话窗口级 Session 容器。
+
+职责：
+    管理单个对话窗口生命周期（session_start/end），每次请求新建 graph。
+
+链路位置：
+    作为 Web/IM 对话场景的外层容器，与 AgentSession 并列。
+
+当前裁剪范围：
+    覆盖最小生命周期与 run_turn 入口；memory manager 可选注入。
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from typing import Any, 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 ..workspace.config import AgentWorkspaceConfig
+
+logger = logging.getLogger(__name__)
+
+
+class ConversationSession:
+    """对话窗口级 session 容器。graph 每次请求新建，不复用。"""
+
+    def __init__(
+        self,
+        graph_factory: Callable[..., CompiledStateGraph],
+        conversation_id: str,
+        workspace_cfg: AgentWorkspaceConfig,
+        hook_engine: Any,
+        plugin_loader: PluginLoader | None = None,
+        initial_messages: list[Any] | None = None,
+    ) -> None:
+        self._graph_factory = graph_factory
+        self._conversation_id = conversation_id
+        self._workspace_cfg = workspace_cfg
+        self._hook_engine = hook_engine
+        self._messages: list[Any] = list(initial_messages or [])
+        self._container_type = "conversation"
+        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) -> "ConversationSession":
+        if self._plugin_loader is not None:
+            load_result = await self._plugin_loader.load_all(container_type="conversation")
+            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_turn(self, user_input: str) -> dict[str, Any]:
+        """每次用户请求调用一次，graph 每次新建。"""
+        appended_message = HumanMessage(content=user_input)
+        self._messages.append(appended_message)
+        graph = self._graph_factory(
+            session_id=self._conversation_id,
+            container_type="conversation",
+        )
+        try:
+            result = await graph.ainvoke(
+                {
+                    "messages": list(self._messages),
+                    "_session_id": self._conversation_id,
+                }
+            )
+        except Exception:
+            # 回滚本轮 append，避免异常路径消息重复累积。
+            if self._messages and self._messages[-1] is appended_message:
+                self._messages.pop()
+            raise
+        if isinstance(result, dict) and isinstance(result.get("messages"), list):
+            self._messages = list(result["messages"])
+        return dict(result) if isinstance(result, dict) else {"result": result}
+
+    @property
+    def conversation_id(self) -> str:
+        return self._conversation_id
+
+    @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)
+        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._conversation_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._conversation_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._conversation_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", None)
+        if not callable(execute):
+            return
+        out = execute(ctx)
+        if inspect.isawaitable(out):
+            await out
+
+    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__ = ["ConversationSession"]

langchain_agentx/session/factory.py

@@ -0,0 +1,143 @@
+"""
+session/factory.py — AgentSession 入口工厂。
+
+职责：
+    统一组装 AgentSession 所需的 graph_factory、workspace 配置与 session 级 hook_engine。
+
+链路位置：
+    作为上层应用（CLI/示例）创建 AgentSession 的便捷入口，底层仍复用 create_loop_agent。
+
+当前裁剪范围：
+    仅覆盖 session 级基础参数透传，不包含应用层交互循环。
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import replace
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+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 ..loop.subagent.transcript import SubagentTranscriptStore
+from ..workspace import resolve_agent_workspace_config
+from .agent_session import AgentSession
+
+
+def create_agent_session(
+    model: str | BaseChatModel,
+    *,
+    session_id: str | None = None,
+    workspace_root: str | Path | None = None,
+    agent_home: str = ".langchain_agentx",
+    hooks: HookRegistry | None = None,
+    hook_engine: Any | None = None,
+    workspace_trust_prompter: Any | None = None,
+    transcript_writer: SubagentTranscriptStore | None = None,
+    container_type: str = "interactive",
+    enable_trace: bool = True,
+    **loop_kwargs: Any,
+) -> AgentSession:
+    """创建默认走 graph_factory 注入路径的 AgentSession。"""
+    resolved_session_id = session_id or f"session-{uuid4().hex}"
+    workspace_cfg = resolve_agent_workspace_config(
+        workspace_root=workspace_root or Path.cwd(),
+        agent_home=agent_home,
+    )
+    workspace_trust_accepted = _resolve_workspace_trust_accepted(
+        workspace_cfg=workspace_cfg,
+        workspace_trust_prompter=workspace_trust_prompter,
+    )
+    workspace_cfg = replace(
+        workspace_cfg,
+        workspace_trust_accepted=workspace_trust_accepted,
+    )
+    if hook_engine is None:
+        snapshot = hooks.build_snapshot() if hooks is not None else HooksConfigSnapshot()
+        hook_engine = HookEngine(
+            snapshot,
+            trust_checker=WorkspaceTrustChecker(
+                headless=_is_headless_container(container_type),
+                workspace_trust_accepted=workspace_cfg.workspace_trust_accepted,
+            ),
+        )
+
+    def _graph_factory(
+        active_files_getter: Any = None,
+        container_type: str = container_type,
+        **_ignored: Any,
+    ):
+        return create_loop_agent(
+            model,
+            session_id=resolved_session_id,
+            workspace_root=workspace_cfg.workspace_root,
+            agent_home=workspace_cfg.agent_home,
+            workspace_trust_accepted=workspace_cfg.workspace_trust_accepted,
+            hooks=hooks,
+            active_files_getter=active_files_getter,
+            container_type=container_type,
+            enable_trace=enable_trace,
+            **loop_kwargs,
+        )
+
+    return AgentSession(
+        graph=None,
+        graph_factory=_graph_factory,
+        session_id=resolved_session_id,
+        workspace_cfg=workspace_cfg,
+        hook_engine=hook_engine,
+        transcript_writer=transcript_writer,
+        container_type=container_type,
+        enable_trace=enable_trace,
+    )
+
+
+__all__ = ["create_agent_session"]
+
+
+def _resolve_workspace_trust_accepted(
+    *,
+    workspace_cfg,
+    workspace_trust_prompter: Any | None,
+) -> bool:
+    persisted = _read_workspace_trust_flag(workspace_cfg)
+    if persisted:
+        return True
+    if workspace_cfg.workspace_trust_accepted:
+        return True
+    if workspace_trust_prompter is None:
+        return False
+    accepted = bool(workspace_trust_prompter(workspace_cfg))
+    if accepted:
+        _write_workspace_trust_flag(workspace_cfg, accepted=True)
+    return accepted
+
+
+def _workspace_config_json_path(workspace_cfg) -> Path:
+    return workspace_cfg.workspace_config_path
+
+
+def _read_workspace_trust_flag(workspace_cfg) -> bool:
+    path = _workspace_config_json_path(workspace_cfg)
+    if not path.exists():
+        return False
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return False
+    return bool(data.get("workspace_trust_accepted"))
+
+
+def _write_workspace_trust_flag(workspace_cfg, *, accepted: bool) -> None:
+    path = _workspace_config_json_path(workspace_cfg)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {"workspace_trust_accepted": bool(accepted)}
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def _is_headless_container(container_type: str) -> bool:
+    return container_type in {"background", "batch", "worker", "sdk"}

langchain_agentx/session/protocol.py

@@ -0,0 +1,25 @@
+"""
+session/protocol.py — LoopContainer 协议定义。
+
+职责：
+    约束外层生命周期容器的最小异步上下文接口（on_start/on_end）。
+
+链路位置：
+    由 AgentSession 与后续 Workflow 基类共同实现，用于统一生命周期语义。
+
+当前裁剪范围：
+    仅定义 Protocol，不包含任何容器实现逻辑。
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, Self, runtime_checkable
+
+
+@runtime_checkable
+class LoopContainer(Protocol):
+    async def __aenter__(self) -> Self: ...
+    async def __aexit__(self, *_) -> None: ...
+
+
+__all__ = ["LoopContainer"]

langchain_agentx/task_runtime/__init__.py

@@ -0,0 +1,113 @@
+"""Task runtime package.
+
+Shared task scheduling primitives for loop and tools.
+"""
+
+from .core.interfaces import TaskExecutor
+from .orchestrator.runtime import DefaultTaskRuntime
+from .queue.in_memory import InMemoryTaskCommandQueue
+from .store.in_memory import InMemoryTaskStore
+from .store.sqlite_store import SqliteTaskStore
+from .tasks import (
+    CUSTOM_SEMANTIC,
+    CustomTaskExecutor,
+    DREAM_TASK_SEMANTIC,
+    DefaultLocalAgentRunner,
+    DreamTaskExecutor,
+    IN_PROCESS_TEAMMATE_SEMANTIC,
+    ImmediateRemoteAgentBackend,
+    InProcessTeammateExecutor,
+    LOCAL_AGENT_SEMANTIC,
+    LOCAL_BASH_SEMANTIC,
+    LocalAgentExecutor,
+    LocalAgentRunner,
+    LocalBashExecutor,
+    RecordingRemoteAgentBackend,
+    REMOTE_AGENT_SEMANTIC,
+    RemoteAgentExecutor,
+    RemoteAgentSessionBackend,
+)
+from .integrations import (
+    InMemoryQueuedCommandProvider,
+    MemoryPrefetchProvider,
+    QueuedCommandEnvelope,
+    QueuedCommandProvider,
+    SqliteQueuedCommandProvider,
+    SkillPrefetchProvider,
+    ToolUseSummaryProvider,
+    ProviderFactoryConfig,
+    ProviderBundle,
+    build_provider_bundle,
+    decode_provider_batch_id,
+    encode_provider_batch_id,
+)
+from .core.types import (
+    QueuePriority,
+    ReservedNotificationBatch,
+    TaskExecutionResult,
+    TaskNotificationEnvelope,
+    TaskRecord,
+    TaskRuntimeEvent,
+    TaskRuntimeEventType,
+    TaskScope,
+    TaskSpec,
+    TaskStatus,
+    TaskType,
+)
+from .output import InMemoryTaskOutputSink, TaskOutputSink
+from .policy import (
+    DEFAULT_WITHHOLD_TASK_EVENT_POLICY,
+    WithholdTaskEventPolicy,
+)
+
+__all__ = [
+    "QueuedCommandProvider",
+    "encode_provider_batch_id",
+    "decode_provider_batch_id",
+    "DefaultTaskRuntime",
+    "InMemoryTaskStore",
+    "SqliteTaskStore",
+    "InMemoryTaskCommandQueue",
+    "TaskExecutor",
+    "LocalBashExecutor",
+    "LOCAL_BASH_SEMANTIC",
+    "DefaultLocalAgentRunner",
+    "LocalAgentExecutor",
+    "LocalAgentRunner",
+    "LOCAL_AGENT_SEMANTIC",
+    "InProcessTeammateExecutor",
+    "IN_PROCESS_TEAMMATE_SEMANTIC",
+    "ImmediateRemoteAgentBackend",
+    "RecordingRemoteAgentBackend",
+    "RemoteAgentExecutor",
+    "RemoteAgentSessionBackend",
+    "REMOTE_AGENT_SEMANTIC",
+    "CustomTaskExecutor",
+    "CUSTOM_SEMANTIC",
+    "DreamTaskExecutor",
+    "DREAM_TASK_SEMANTIC",
+    "TaskType",
+    "TaskStatus",
+    "QueuePriority",
+    "TaskScope",
+    "TaskSpec",
+    "TaskRecord",
+    "TaskNotificationEnvelope",
+    "ReservedNotificationBatch",
+    "TaskExecutionResult",
+    "TaskRuntimeEvent",
+    "TaskRuntimeEventType",
+    "InMemoryQueuedCommandProvider",
+    "QueuedCommandEnvelope",
+    "SqliteQueuedCommandProvider",
+    "MemoryPrefetchProvider",
+    "SkillPrefetchProvider",
+    "ToolUseSummaryProvider",
+    "ProviderFactoryConfig",
+    "ProviderBundle",
+    "build_provider_bundle",
+    "InMemoryTaskOutputSink",
+    "TaskOutputSink",
+    "WithholdTaskEventPolicy",
+    "DEFAULT_WITHHOLD_TASK_EVENT_POLICY",
+]

langchain_agentx/task_runtime/core/__init__.py

@@ -0,0 +1,51 @@
+"""Core domain types and protocols for task_runtime."""
+
+from .ids import (
+    new_notification_command_id,
+    new_reserved_batch_id,
+    new_run_id,
+    new_task_id,
+)
+from .interfaces import (
+    TaskCommandQueue,
+    TaskExecutor,
+    TaskRuntime,
+    TaskStore,
+)
+from .notification_priority import notification_priority_for_terminal_status
+from .types import (
+    QueuePriority,
+    ReservedNotificationBatch,
+    TaskExecutionResult,
+    TaskNotificationEnvelope,
+    TaskRecord,
+    TaskRuntimeEvent,
+    TaskRuntimeEventType,
+    TaskScope,
+    TaskSpec,
+    TaskStatus,
+    TaskType,
+)
+
+__all__ = [
+    "new_notification_command_id",
+    "new_reserved_batch_id",
+    "new_run_id",
+    "new_task_id",
+    "notification_priority_for_terminal_status",
+    "QueuePriority",
+    "ReservedNotificationBatch",
+    "TaskCommandQueue",
+    "TaskExecutionResult",
+    "TaskExecutor",
+    "TaskNotificationEnvelope",
+    "TaskRecord",
+    "TaskRuntime",
+    "TaskRuntimeEvent",
+    "TaskRuntimeEventType",
+    "TaskScope",
+    "TaskSpec",
+    "TaskStatus",
+    "TaskStore",
+    "TaskType",
+]