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

langchain_agentx/task_runtime/tasks/local_bash/executor.py

@@ -0,0 +1,95 @@
+"""
+tasks/local_bash/executor.py — LOCAL_BASH 执行器
+
+职责：
+    解析输入、``subprocess.run`` 执行、返回 ``TaskExecutionResult``。
+
+与 CC 对比：
+    CC ``LocalShellTask`` 含输出文件、stall watchdog、kill 等；本仓库最小实现仅覆盖
+    「一次 shell 执行 → 终态摘要」，长驻/monitor 等分期扩展。
+"""
+
+from __future__ import annotations
+
+import subprocess
+from typing import TYPE_CHECKING, Optional
+
+from ...core.interfaces import TaskExecutor
+from ...core.types import TaskExecutionResult, TaskStatus
+
+from .spec import LocalBashTaskInput
+
+if TYPE_CHECKING:
+    from ...output.sink import TaskOutputSink
+
+
+class LocalBashExecutor(TaskExecutor):
+    """本地 shell 执行器：输入经 ``LocalBashTaskInput.from_mapping`` 校验。"""
+
+    def __init__(
+        self,
+        *,
+        default_timeout_sec: int = 30,
+        output_sink: Optional["TaskOutputSink"] = None,
+    ) -> None:
+        self._default_timeout_sec = default_timeout_sec
+        self._output_sink = output_sink
+
+    def execute(self, record) -> TaskExecutionResult:
+        try:
+            parsed = LocalBashTaskInput.from_mapping(dict(record.input or {}))
+        except ValueError as e:
+            return TaskExecutionResult(
+                status=TaskStatus.FAILED,
+                summary=str(e),
+            )
+
+        timeout_sec = (
+            parsed.timeout_sec
+            if parsed.timeout_sec is not None
+            else self._default_timeout_sec
+        )
+
+        try:
+            # shell=True：不适用 TextSubprocessRunner（其拒绝 shell）；显式 UTF-8 与 CC/遥测对齐。
+            completed = subprocess.run(
+                parsed.command,
+                shell=True,
+                cwd=parsed.cwd,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                capture_output=True,
+                timeout=timeout_sec,
+                check=False,
+            )
+        except subprocess.TimeoutExpired:
+            return TaskExecutionResult(
+                status=TaskStatus.FAILED,
+                summary=f"Command timed out after {timeout_sec}s",
+            )
+
+        out_blob = (completed.stdout or "") + (
+            "\n" if (completed.stdout and completed.stderr) else ""
+        ) + (completed.stderr or "")
+        if self._output_sink is not None and out_blob:
+            self._output_sink.append(record.task_id, out_blob)
+
+        if completed.returncode == 0:
+            stdout = (completed.stdout or "").strip()
+            summary = stdout[:300] if stdout else "Command completed"
+            return TaskExecutionResult(
+                status=TaskStatus.COMPLETED,
+                summary=summary,
+            )
+
+        stderr = (completed.stderr or "").strip()
+        summary = (
+            stderr[:300]
+            if stderr
+            else f"Command failed with exit code {completed.returncode}"
+        )
+        return TaskExecutionResult(
+            status=TaskStatus.FAILED,
+            summary=summary,
+        )

langchain_agentx/task_runtime/tasks/local_bash/notification.py

@@ -0,0 +1,22 @@
+"""
+tasks/local_bash/notification.py — 终态摘要格式（OOP）
+
+职责：
+    封装与 CC UI/通知折叠相关的摘要前缀与格式化，便于单测锚定。
+
+与 CC 对比：
+    ``LocalShellTask.tsx`` 中 ``BACKGROUND_BASH_SUMMARY_PREFIX``、
+    ``enqueueShellNotification`` 对 completed/failed/killed 的展示逻辑；
+    此处仅保留可移植的最小前缀与拼接规则。
+"""
+
+
+class LocalBashNotificationFormatter:
+    """CC: ``BACKGROUND_BASH_SUMMARY_PREFIX = 'Background command '``"""
+
+    BACKGROUND_BASH_SUMMARY_PREFIX = "Background command "
+
+    @classmethod
+    def format_terminal(cls, *, description: str, status: str) -> str:
+        desc = (description or "").strip() or "(no description)"
+        return f"{cls.BACKGROUND_BASH_SUMMARY_PREFIX}\"{desc}\" [{status}]"

langchain_agentx/task_runtime/tasks/local_bash/semantics.py

@@ -0,0 +1,13 @@
+"""tasks/local_bash/semantics.py — ``TaskSemanticContract`` 绑定。"""
+
+from __future__ import annotations
+
+from ...core.types import TaskStatus, TaskType
+from ..base.contracts import TaskSemanticContract
+
+
+LOCAL_BASH_SEMANTIC = TaskSemanticContract(
+    task_type=TaskType.LOCAL_BASH,
+    terminal_statuses=(TaskStatus.COMPLETED, TaskStatus.FAILED, TaskStatus.STOPPED),
+    summary_prefix="local_bash",
+)

langchain_agentx/task_runtime/tasks/local_bash/spec.py

@@ -0,0 +1,55 @@
+"""
+tasks/local_bash/spec.py — LOCAL_BASH 输入契约（OOP）
+
+职责：
+    将未信任的 ``dict`` 解析为冻结的输入值对象；校验失败抛 ``ValueError``，
+    由 ``TaskExecutor.execute`` 转为 ``TaskExecutionResult(FAILED)``。
+
+与 CC 对比：
+    CC 侧 ``LocalShellSpawnInput`` / guards（``BashTaskKind``）在 TS 中结构化；
+    本仓库用 ``LocalBashTaskInput.from_mapping`` 做等价入口，避免业务层散落魔法 key。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class LocalBashTaskInput:
+    """进程内 shell 任务输入（对齐 CC LocalShellTask 最小字段）。"""
+
+    command: str
+    cwd: str | None = None
+    timeout_sec: int | None = None
+    kind: str | None = None
+
+    @classmethod
+    def from_mapping(cls, raw: Mapping[str, Any]) -> LocalBashTaskInput:
+        command = str(raw.get("command") or "").strip()
+        if not command:
+            raise ValueError("LOCAL_BASH requires non-empty 'command'")
+        cwd_raw = raw.get("cwd")
+        cwd = str(cwd_raw).strip() if cwd_raw not in (None, "") else None
+        timeout_raw = raw.get("timeout_sec")
+        if timeout_raw is None:
+            timeout_sec = None
+        else:
+            timeout_sec = int(timeout_raw)
+            if timeout_sec <= 0:
+                raise ValueError("timeout_sec must be positive when set")
+        kind_raw = raw.get("kind")
+        kind = str(kind_raw).strip().lower() if kind_raw is not None else None
+        return cls(command=command, cwd=cwd, timeout_sec=timeout_sec, kind=kind)
+
+    def to_executor_mapping(self) -> dict[str, Any]:
+        """供 ``TaskSpec.input`` 序列化；仅包含执行器消费的键。"""
+        out: dict[str, Any] = {"command": self.command}
+        if self.cwd is not None:
+            out["cwd"] = self.cwd
+        if self.timeout_sec is not None:
+            out["timeout_sec"] = self.timeout_sec
+        if self.kind is not None:
+            out["kind"] = self.kind
+        return out

langchain_agentx/task_runtime/tasks/remote_agent/__init__.py

@@ -0,0 +1,19 @@
+"""REMOTE_AGENT 语义包（CC ``RemoteAgentTask``）。"""
+
+from .backend import (
+    ImmediateRemoteAgentBackend,
+    RecordingRemoteAgentBackend,
+    RemoteAgentSessionBackend,
+)
+from .executor import RemoteAgentExecutor
+from .semantics import REMOTE_AGENT_SEMANTIC
+from .spec import RemoteAgentTaskInput
+
+__all__ = [
+    "ImmediateRemoteAgentBackend",
+    "RecordingRemoteAgentBackend",
+    "RemoteAgentExecutor",
+    "RemoteAgentSessionBackend",
+    "REMOTE_AGENT_SEMANTIC",
+    "RemoteAgentTaskInput",
+]

langchain_agentx/task_runtime/tasks/remote_agent/backend.py

@@ -0,0 +1,76 @@
+"""
+tasks/remote_agent/backend.py — 远程会话命令后端（CC poll/send 语义）
+
+职责：
+    将 ``session_id + command`` 的执行与 executor 解耦，便于接入 **HTTP / teleport**
+    等实现；默认 ``ImmediateRemoteAgentBackend`` 无 I/O，用于 CI 与单测。
+
+与 CC 对比：
+    CC ``RemoteAgentTask`` 轮询 ``pollRemoteSessionEvents`` 并下发 command；
+    此处用 ``run_command`` 抽象一次「投递命令 → 终态结果」，真轮询可在实现内循环。
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from ...core.types import TaskExecutionResult, TaskStatus
+from .notification import RemoteAgentNotificationFormatter
+
+
+@runtime_checkable
+class RemoteAgentSessionBackend(Protocol):
+    def run_command(
+        self,
+        *,
+        session_id: str,
+        command: str,
+        remote_task_type: str,
+    ) -> TaskExecutionResult:
+        ...
+
+
+class ImmediateRemoteAgentBackend:
+    """无网络：命令立即视为成功，摘要与 CC 展示串对齐。"""
+
+    def run_command(
+        self,
+        *,
+        session_id: str,
+        command: str,
+        remote_task_type: str,
+    ) -> TaskExecutionResult:
+        summary = RemoteAgentNotificationFormatter.format_command_completion(
+            session_id=session_id,
+            command=command,
+            remote_task_type=remote_task_type,
+        )
+        return TaskExecutionResult(status=TaskStatus.COMPLETED, summary=summary)
+
+
+class RecordingRemoteAgentBackend:
+    """包装另一后端并记录调用，便于测试与调试。"""
+
+    def __init__(self, inner: RemoteAgentSessionBackend | None = None) -> None:
+        self._inner = inner or ImmediateRemoteAgentBackend()
+        self.calls: list[dict[str, str]] = []
+
+    def run_command(
+        self,
+        *,
+        session_id: str,
+        command: str,
+        remote_task_type: str,
+    ) -> TaskExecutionResult:
+        self.calls.append(
+            {
+                "session_id": session_id,
+                "command": command,
+                "remote_task_type": remote_task_type,
+            }
+        )
+        return self._inner.run_command(
+            session_id=session_id,
+            command=command,
+            remote_task_type=remote_task_type,
+        )

langchain_agentx/task_runtime/tasks/remote_agent/executor.py

@@ -0,0 +1,37 @@
+"""
+tasks/remote_agent/executor.py — REMOTE_AGENT 执行器
+
+职责：
+    校验输入后委托 ``RemoteAgentSessionBackend.run_command``；默认
+    ``ImmediateRemoteAgentBackend`` 无网络。生产接入 HTTP/teleport 时替换 backend。
+
+与 CC 对比：
+    CC ``pollRemoteSessionEvents`` + 命令下发；此处将一轮「投递命令 → 结果」收口到
+    backend，轮询可在 ``HttpRemoteAgentBackend`` 等实现内完成。
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ...core.interfaces import TaskExecutor
+from ...core.types import TaskExecutionResult, TaskStatus
+
+from .backend import ImmediateRemoteAgentBackend, RemoteAgentSessionBackend
+from .spec import RemoteAgentTaskInput
+
+
+class RemoteAgentExecutor(TaskExecutor):
+    def __init__(self, backend: Optional[RemoteAgentSessionBackend] = None) -> None:
+        self._backend: RemoteAgentSessionBackend = backend or ImmediateRemoteAgentBackend()
+
+    def execute(self, record) -> TaskExecutionResult:
+        try:
+            parsed = RemoteAgentTaskInput.from_mapping(dict(record.input or {}))
+        except ValueError as e:
+            return TaskExecutionResult(status=TaskStatus.FAILED, summary=str(e))
+        return self._backend.run_command(
+            session_id=parsed.session_id,
+            command=parsed.command,
+            remote_task_type=parsed.remote_task_type,
+        )

langchain_agentx/task_runtime/tasks/remote_agent/notification.py

@@ -0,0 +1,22 @@
+"""
+tasks/remote_agent/notification.py — 终态摘要（OOP）
+
+与 CC 对比：
+    CC 在 poll 完成时生成可展示的 notification 文本；本类仅提供占位格式化。
+"""
+
+
+class RemoteAgentNotificationFormatter:
+    @classmethod
+    def format_command_completion(
+        cls,
+        *,
+        session_id: str,
+        command: str,
+        remote_task_type: str,
+    ) -> str:
+        excerpt = command[:160]
+        return (
+            f"Remote agent command completed: session={session_id} "
+            f"type={remote_task_type} cmd={excerpt!r}"
+        )

langchain_agentx/task_runtime/tasks/remote_agent/semantics.py

@@ -0,0 +1,13 @@
+"""tasks/remote_agent/semantics.py — 语义契约绑定。"""
+
+from __future__ import annotations
+
+from ...core.types import TaskStatus, TaskType
+from ..base.contracts import TaskSemanticContract
+
+
+REMOTE_AGENT_SEMANTIC = TaskSemanticContract(
+    task_type=TaskType.REMOTE_AGENT,
+    terminal_statuses=(TaskStatus.COMPLETED, TaskStatus.FAILED, TaskStatus.STOPPED),
+    summary_prefix="remote_agent",
+)

langchain_agentx/task_runtime/tasks/remote_agent/spec.py

@@ -0,0 +1,34 @@
+"""
+tasks/remote_agent/spec.py — REMOTE_AGENT 输入契约（OOP）
+
+职责：
+    描述远程会话类任务的最小输入；.teleport / poll 等网络行为不在 spec 内实现。
+
+与 CC 对比：
+    ``RemoteAgentTask.tsx`` 中 ``sessionId``、``command``、``remoteTaskType``、
+    ``RemoteAgentTaskState``；本仓库用 ``RemoteAgentTaskInput.from_mapping`` 对齐命名，
+    真轮询与元数据持久化在 executor 分期接入。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class RemoteAgentTaskInput:
+    session_id: str
+    command: str
+    remote_task_type: str = "remote-agent"
+
+    @classmethod
+    def from_mapping(cls, raw: Mapping[str, Any]) -> RemoteAgentTaskInput:
+        sid = str(raw.get("session_id") or raw.get("sessionId") or "").strip()
+        cmd = str(raw.get("command") or "").strip()
+        if not sid:
+            raise ValueError("REMOTE_AGENT requires 'session_id'")
+        if not cmd:
+            raise ValueError("REMOTE_AGENT requires non-empty 'command'")
+        rtt = str(raw.get("remote_task_type") or raw.get("remoteTaskType") or "remote-agent").strip()
+        return cls(session_id=sid, command=cmd, remote_task_type=rtt or "remote-agent")

langchain_agentx/task_runtime/tasks/trace_cleanup/__init__.py

@@ -0,0 +1,19 @@
+"""
+trace_cleanup — Trace 数据清理后台任务（OB-D10 Phase 1）
+
+职责：
+    导出 TraceCleanupTask；import 本包时注册 ``trace.cleanup`` 到 BackgroundAiTaskRegistry。
+
+链路位置：
+    由 ``langchain_agentx.task_runtime.tasks.ai_analysis`` 包加载时一并 import，保证 registry 侧载。
+
+当前裁剪范围：
+    不含 create_agent / loop 挂载（Phase 4）；不含 ``cleanup_by_size``（OB-D10 Phase 5）。
+"""
+
+from __future__ import annotations
+
+from .executor import TraceCleanupTask
+from .scheduler import TraceCleanupScheduler
+
+__all__ = ["TraceCleanupTask", "TraceCleanupScheduler"]

langchain_agentx/task_runtime/tasks/trace_cleanup/bootstrap.py

@@ -0,0 +1,95 @@
+"""
+trace_cleanup/bootstrap.py — create_loop_agent 侧清理调度启动
+
+职责：
+    在图已 ``compile`` 后，若存在运行中 asyncio 循环，则 ``create_task(TraceCleanupScheduler.start())``。
+
+链路位置：
+    可由应用在 **async 上下文** 内显式调用；是否从 ``create_loop_agent`` 挂载由产品决定（当前 factory 未接线）。
+
+当前裁剪范围：
+    不解析 YAML；参数由 ``create_loop_agent`` 关键字传入；无 event loop 时仅打日志不抛错。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class _NoopCompiledGraph:
+    """TraceCleanupTask 不调用 invoke，仅占位满足 BaseWorkflow 契约。"""
+
+    async def ainvoke(self, *args: Any, **kwargs: Any) -> dict[str, Any]:
+        return {"messages": []}
+
+
+def _noop_graph_factory(**kwargs: Any) -> _NoopCompiledGraph:
+    return _NoopCompiledGraph()
+
+
+def try_start_trace_cleanup_after_compile(
+    builder: Any,
+    *,
+    poll_interval: float,
+    failed_days: int,
+    normal_days: int,
+    enable_file_lock: bool,
+    marker_cooldown_seconds: float | None,
+    cleanup_diagnostic_reports: bool,
+) -> None:
+    """在 **当前线程** 存在运行中 event loop 时启动 ``TraceCleanupScheduler``，否则打 warning。"""
+    wiring = getattr(builder, "_hook_graph_wiring", None)
+    if wiring is None:
+        logger.warning("trace cleanup: LoopGraphBuilder 缺少 _hook_graph_wiring，跳过启动")
+        return
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        logger.warning(
+            "enable_trace_cleanup=True 但当前线程无运行中的 asyncio 事件循环，未启动 "
+            "TraceCleanupScheduler；请在 async 内创建 agent 或自行 ``asyncio.create_task(scheduler.start())``"
+        )
+        return
+
+    import langchain_agentx.task_runtime.tasks.ai_analysis  # noqa: F401 — registry 侧载
+
+    from langchain_agentx.observability.evaluation.store import EvaluationStore
+    from langchain_agentx.observability.trace.sqlite_store import SqliteTraceStore
+    from langchain_agentx.task_runtime.tasks.ai_analysis.registry import registry
+
+    from .scheduler import TraceCleanupScheduler
+
+    trace_store = SqliteTraceStore.from_env()
+    eval_store = EvaluationStore.from_env()
+    cleanup_config: dict[str, Any] = {
+        "failed_days": int(failed_days),
+        "normal_days": int(normal_days),
+        "cleanup_diagnostic_reports": bool(cleanup_diagnostic_reports),
+    }
+    scheduler = TraceCleanupScheduler(
+        trace_store=trace_store,
+        evaluation_store=eval_store,
+        registry=registry,
+        poll_interval=float(poll_interval),
+        cleanup_config=cleanup_config,
+        enable_file_lock=bool(enable_file_lock),
+        marker_cooldown_seconds=marker_cooldown_seconds,
+        task_factory_kwargs={
+            "graph_factory": _noop_graph_factory,
+            "hook_engine": wiring.hook_engine,
+        },
+    )
+    loop.create_task(scheduler.start())
+    logger.info(
+        "TraceCleanupScheduler 已提交到事件循环 poll_interval=%s failed_days=%s normal_days=%s",
+        poll_interval,
+        failed_days,
+        normal_days,
+    )
+
+
+__all__ = ["try_start_trace_cleanup_after_compile", "_noop_graph_factory"]

langchain_agentx/task_runtime/tasks/trace_cleanup/executor.py

@@ -0,0 +1,66 @@
+"""
+trace_cleanup/executor.py — TraceCleanupTask
+
+职责：
+    单次执行 trace session 分层保留清理（调用 SqliteTraceStore.cleanup_sessions_by_retention）。
+
+链路位置：
+    由 TraceCleanupScheduler（Phase 2）或测试/脚本通过 registry.get("trace.cleanup") 构造并 run()。
+
+当前裁剪范围：
+    ``cleanup_diagnostic_reports=False`` 时不删诊断报告（§4.1 Q1=A 默认）；不实现 cleanup_by_size（Q3 延后）。
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from langchain_agentx.observability.evaluation.store import EvaluationStore
+from langchain_agentx.observability.trace.sqlite_store import SqliteTraceStore
+
+from ..ai_analysis.base import BackgroundAiTask
+from ..ai_analysis.registry import registry
+
+logger = logging.getLogger(__name__)
+
+
+class TraceCleanupTask(BackgroundAiTask):
+    """清理过期 trace session（retention 策略由参数传入）。"""
+
+    def __init__(
+        self,
+        trace_store: SqliteTraceStore,
+        evaluation_store: EvaluationStore,
+        **workflow_kwargs: Any,
+    ) -> None:
+        super().__init__(**workflow_kwargs)
+        self._trace_store = trace_store
+        self._evaluation_store = evaluation_store
+
+    async def _execute(
+        self,
+        *,
+        failed_days: int = 180,
+        normal_days: int = 30,
+        cleanup_diagnostic_reports: bool = False,
+        **_: Any,
+    ) -> dict[str, int]:
+        deleted_sessions = self._trace_store.cleanup_sessions_by_retention(
+            failed_days=int(failed_days),
+            normal_days=int(normal_days),
+        )
+        deleted_reports = 0
+        if cleanup_diagnostic_reports:
+            deleted_reports = self._evaluation_store.cleanup_old_reports(days=int(failed_days))
+        out: dict[str, int] = {
+            "deleted_sessions": int(deleted_sessions),
+            "deleted_reports": int(deleted_reports),
+        }
+        logger.info("TraceCleanupTask 完成: %s", out)
+        return out
+
+
+registry.register("trace.cleanup", TraceCleanupTask)
+
+__all__ = ["TraceCleanupTask"]