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

langchain_agentx/task_runtime/integrations/tool_use_summary_provider.py

@@ -0,0 +1,254 @@
+"""
+task_runtime/integrations/tool_use_summary_provider.py — Tool Use Summary 聚合 provider
+
+职责：
+    在 task 侧聚合工具调用结果，并异步生成 queued-command summary：
+    1. record_tool_result：采集单次工具结果
+    2. flush_scope_summary：按 scope 生成一次摘要命令
+    3. build_batch / ack / nack：复用通用 queued-command provider
+
+边界：
+    - 不依赖 loop 结构；只产出 queued-command
+    - “异步”语义由 record 与 flush 解耦实现（可在不同阶段触发）
+"""
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass, field
+import time
+from uuid import uuid4
+
+from langchain_core.messages import ToolMessage
+
+from ..core.types import QueuePriority, TaskScope
+from .loop_adapter import LoopInjectionBatch
+from .queued_command_provider import InMemoryQueuedCommandProvider, QueuedCommandEnvelope
+
+
+@dataclass(frozen=True)
+class ToolUseRecord:
+    tool_name: str
+    status: str  # success | error
+    latency_ms: int | None = None
+    tool_use_id: str | None = None
+    output_preview: str | None = None
+    created_at: float = field(default_factory=time.time)
+
+
+class ToolUseSummaryProvider:
+    """聚合工具调用记录，输出 summary queued-command。"""
+
+    def __init__(
+        self,
+        backend: InMemoryQueuedCommandProvider | None = None,
+        *,
+        max_queue_size: int | None = None,
+        ttl_sec: float | None = None,
+        error_ratio_now_threshold: float = 0.5,
+        avg_latency_now_threshold_ms: int = 2000,
+    ) -> None:
+        self._backend = backend or InMemoryQueuedCommandProvider(
+            max_queue_size=max_queue_size,
+            ttl_sec=ttl_sec,
+        )
+        self._buffers: dict[str | None, list[ToolUseRecord]] = {}
+        self._seen_tool_call_ids: dict[str | None, set[str]] = {}
+        self._error_ratio_now_threshold = error_ratio_now_threshold
+        self._avg_latency_now_threshold_ms = avg_latency_now_threshold_ms
+
+    def record_tool_result(
+        self,
+        *,
+        scope: TaskScope,
+        tool_name: str,
+        status: str,
+        latency_ms: int | None = None,
+        tool_use_id: str | None = None,
+        output_preview: str | None = None,
+    ) -> None:
+        normalized_status = "success" if status not in {"error", "failed"} else "error"
+        self._buffers.setdefault(scope.agent_id, []).append(
+            ToolUseRecord(
+                tool_name=tool_name,
+                status=normalized_status,
+                latency_ms=latency_ms,
+                tool_use_id=tool_use_id,
+                output_preview=output_preview,
+            )
+        )
+
+    def flush_scope_summary(
+        self,
+        *,
+        scope: TaskScope,
+        priority: QueuePriority | None = None,
+    ) -> int:
+        records = self._buffers.get(scope.agent_id, [])
+        if not records:
+            return 0
+        summary_text, payload = _build_summary(records)
+        chosen_priority = priority or self._select_priority(payload)
+        dedup_key = (
+            f"tool_summary:{scope.agent_id}:{payload['total_calls']}:"
+            f"{payload['error_calls']}:{chosen_priority.value}"
+        )
+        command_id = f"tool_summary_{uuid4().hex[:10]}"
+        self._backend.enqueue(
+            QueuedCommandEnvelope(
+                command_id=command_id,
+                source="tool_use_summary",
+                summary=summary_text,
+                scope=scope,
+                priority=chosen_priority,
+                payload=payload,
+                dedup_key=dedup_key,
+            )
+        )
+        self._buffers[scope.agent_id] = []
+        return 1
+
+    def ingest_from_opencode_events(
+        self,
+        *,
+        scope: TaskScope,
+        events: list[dict],
+    ) -> int:
+        """从 LangChain AgentX 风格事件列表采集工具调用结果。"""
+        count = 0
+        for event in events:
+            event_type = str(event.get("event_type") or event.get("type") or "")
+            data = event.get("data") or {}
+            tool_name = str(data.get("tool_name") or "")
+            if not tool_name:
+                continue
+            if event_type in {"tool-result", "TOOL_RESULT"}:
+                self.record_tool_result(
+                    scope=scope,
+                    tool_name=tool_name,
+                    status="success",
+                    output_preview=str(data.get("output") or "")[:120],
+                )
+                count += 1
+            elif event_type in {"tool-error", "TOOL_ERROR"}:
+                self.record_tool_result(
+                    scope=scope,
+                    tool_name=tool_name,
+                    status="error",
+                    output_preview=str(data.get("error") or "")[:120],
+                )
+                count += 1
+        return count
+
+    def ingest_from_messages(
+        self,
+        *,
+        scope: TaskScope,
+        messages: list,
+    ) -> int:
+        """从 loop state.messages 自动提取 ToolMessage 结果。"""
+        count = 0
+        seen = self._seen_tool_call_ids.setdefault(scope.agent_id, set())
+        for msg in messages:
+            if not isinstance(msg, ToolMessage):
+                continue
+            tool_call_id = getattr(msg, "tool_call_id", None)
+            if not tool_call_id:
+                continue
+            tool_call_id = str(tool_call_id)
+            if tool_call_id in seen:
+                continue
+            seen.add(tool_call_id)
+            tool_name = _extract_tool_name(msg)
+            status = _extract_tool_status(msg)
+            content = msg.content
+            preview = content if isinstance(content, str) else str(content)
+            self.record_tool_result(
+                scope=scope,
+                tool_name=tool_name,
+                status=status,
+                output_preview=preview[:120],
+                tool_use_id=tool_call_id,
+            )
+            count += 1
+        return count
+
+    def build_batch(
+        self,
+        scope: TaskScope,
+        max_priority: QueuePriority = QueuePriority.NEXT,
+        *,
+        limit: int = 8,
+    ) -> LoopInjectionBatch:
+        return self._backend.build_batch(scope, max_priority=max_priority, limit=limit)
+
+    def ack_batch(self, batch: LoopInjectionBatch) -> None:
+        self._backend.ack_batch(batch)
+
+    def nack_batch(self, batch: LoopInjectionBatch, *, requeue: bool = True) -> None:
+        self._backend.nack_batch(batch, requeue=requeue)
+
+    def has_pending(
+        self, scope: TaskScope, max_priority: QueuePriority = QueuePriority.NEXT
+    ) -> bool:
+        return self._backend.has_pending(scope, max_priority=max_priority)
+
+    def _select_priority(self, payload: dict) -> QueuePriority:
+        total = int(payload.get("total_calls") or 0)
+        errors = int(payload.get("error_calls") or 0)
+        avg_latency_ms = payload.get("avg_latency_ms")
+        if total > 0 and (errors / total) >= self._error_ratio_now_threshold:
+            return QueuePriority.NOW
+        if isinstance(avg_latency_ms, int) and avg_latency_ms >= self._avg_latency_now_threshold_ms:
+            return QueuePriority.NOW
+        if errors > 0:
+            return QueuePriority.NEXT
+        return QueuePriority.LATER
+
+
+def _build_summary(records: list[ToolUseRecord]) -> tuple[str, dict]:
+    total_calls = len(records)
+    error_calls = sum(1 for item in records if item.status == "error")
+    success_calls = total_calls - error_calls
+    tool_counter = Counter(item.tool_name for item in records)
+    tool_stat = [{"tool_name": k, "count": v} for k, v in tool_counter.items()]
+    latency_values = [item.latency_ms for item in records if item.latency_ms is not None]
+    avg_latency_ms = int(sum(latency_values) / len(latency_values)) if latency_values else None
+    summary = (
+        f"tool summary: total={total_calls}, success={success_calls}, "
+        f"error={error_calls}, tools={dict(tool_counter)}"
+    )
+    return summary, {
+        "total_calls": total_calls,
+        "success_calls": success_calls,
+        "error_calls": error_calls,
+        "tools": tool_stat,
+        "avg_latency_ms": avg_latency_ms,
+    }
+
+
+def _extract_tool_name(msg: ToolMessage) -> str:
+    extra = getattr(msg, "additional_kwargs", {}) or {}
+    metadata = getattr(msg, "metadata", {}) or {}
+    name = (
+        getattr(msg, "tool_name", None)
+        or getattr(msg, "name", None)
+        or extra.get("tool_name")
+        or extra.get("name")
+        or metadata.get("tool_name")
+        or metadata.get("name")
+    )
+    return str(name) if name else "unknown_tool"
+
+
+def _extract_tool_status(msg: ToolMessage) -> str:
+    extra = getattr(msg, "additional_kwargs", {}) or {}
+    metadata = getattr(msg, "metadata", {}) or {}
+    if extra.get("error") or metadata.get("error"):
+        return "error"
+    if str(metadata.get("status") or "").lower() == "error":
+        return "error"
+    content = msg.content
+    if isinstance(content, str) and content.lower().startswith("error"):
+        return "error"
+    return "success"
+

langchain_agentx/task_runtime/orchestrator/__init__.py

@@ -0,0 +1,5 @@
+"""Task lifecycle orchestration."""
+
+from .runtime import DefaultTaskRuntime
+
+__all__ = ["DefaultTaskRuntime"]

langchain_agentx/task_runtime/orchestrator/runtime.py

@@ -0,0 +1,386 @@
+"""
+task_runtime/orchestrator/runtime.py — Task Runtime 默认编排实现
+
+职责：
+    聚合 TaskStore 与 TaskCommandQueue，提供统一任务生命周期编排：
+    1. spawn：创建并注册运行中任务
+    2. cancel：将任务转换为终止态（§10.2 抢占 → STOPPED）
+    3. mark_terminal：落终态并发布 task-notification
+    4. drain/ack：按 scope 与 priority 读取和确认通知
+    5. 可选：wait_for_terminal / TaskOutputSink / 租约 heartbeat（§10.2–§10.4）
+
+与 CC 对齐点：
+    - 终态通知按 (task_id, status) 做幂等去重
+    - 通知优先级采用 now > next > later
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from threading import RLock
+from typing import Optional, TYPE_CHECKING
+import time
+import logging
+
+from ..core.ids import (
+    new_notification_command_id,
+    new_reserved_batch_id,
+    new_run_id,
+    new_task_id,
+)
+from ..core.interfaces import TaskCommandQueue, TaskExecutor, TaskRuntime, TaskStore
+from ..core.notification_priority import notification_priority_for_terminal_status
+from ...observability.logging import ObservabilityLoggerAdapter, build_log_context
+
+if TYPE_CHECKING:
+    from ..output.sink import TaskOutputSink
+from ..core.types import (
+    QueuePriority,
+    ReservedNotificationBatch,
+    TaskExecutionResult,
+    TaskNotificationEnvelope,
+    TaskRecord,
+    TaskRuntimeEvent,
+    TaskRuntimeEventType,
+    TaskScope,
+    TaskSpec,
+    TaskStatus,
+    TaskType,
+)
+
+_TERMINAL_STATUSES = {TaskStatus.COMPLETED, TaskStatus.FAILED, TaskStatus.STOPPED}
+logger = logging.getLogger(__name__)
+
+
+class DefaultTaskRuntime(TaskRuntime):
+    def __init__(
+        self,
+        store: TaskStore,
+        queue: TaskCommandQueue,
+        *,
+        output_sink: Optional["TaskOutputSink"] = None,
+        lease_ttl_sec: Optional[float] = 300.0,
+    ) -> None:
+        self._store = store
+        self._queue = queue
+        self._output_sink = output_sink
+        self._lease_ttl_sec = lease_ttl_sec
+        self._lock = RLock()
+        self._reserved_batches: dict[str, ReservedNotificationBatch] = {}
+        self._executors: dict[TaskType, TaskExecutor] = {}
+        self._events: list[TaskRuntimeEvent] = []
+
+    def _emit_event(
+        self,
+        event_type: TaskRuntimeEventType,
+        record: TaskRecord,
+        summary: str,
+        *,
+        status: TaskStatus | None = None,
+        terminal_reason: str | None = None,
+    ) -> None:
+        with self._lock:
+            self._events.append(
+                TaskRuntimeEvent(
+                    event_type=event_type,
+                    task_id=record.task_id,
+                    task_type=record.task_type,
+                    status=status or record.status,
+                    summary=summary,
+                    scope=record.scope,
+                    terminal_reason=terminal_reason,
+                )
+            )
+
+    def spawn(self, spec: TaskSpec) -> str:
+        task_id = new_task_id()
+        meta = spec.metadata or {}
+        ext = meta.get("external_ref")
+        external_ref = ext if isinstance(ext, str) else None
+        record = TaskRecord(
+            task_id=task_id,
+            task_type=spec.task_type,
+            status=TaskStatus.PENDING,
+            description=spec.description,
+            scope=spec.scope,
+            input=spec.input,
+            metadata=spec.metadata,
+            run_id=new_run_id(),
+            external_ref=external_ref,
+        )
+        self._store.create(record)
+        ObservabilityLoggerAdapter(
+            logger,
+            build_log_context(
+                run_id=record.run_id,
+                session_id=record.scope.agent_id,
+                task_id=task_id,
+            ).as_extra(),
+        ).info("task spawned type=%s", record.task_type.value)
+        return task_id
+
+    def register_executor(
+        self, task_type: TaskType, executor: TaskExecutor, *, overwrite: bool = False
+    ) -> None:
+        if (task_type in self._executors) and not overwrite:
+            raise ValueError(f"Executor already registered for task type: {task_type.value}")
+        self._executors[task_type] = executor
+
+    def run_task(self, task_id: str) -> bool:
+        record = self._store.get(task_id)
+        if record is None:
+            return False
+        task_log = ObservabilityLoggerAdapter(
+            logger,
+            build_log_context(
+                run_id=record.run_id,
+                session_id=record.scope.agent_id,
+                task_id=record.task_id,
+            ).as_extra(),
+        )
+        executor = self._executors.get(record.task_type)
+        if executor is None:
+            raise ValueError(f"No executor registered for task type: {record.task_type.value}")
+
+        now = time.time()
+        run_patch: dict = {
+            "status": TaskStatus.RUNNING,
+            "updated_at": now,
+        }
+        if self._lease_ttl_sec is not None:
+            run_patch["lease_until_ts"] = now + float(self._lease_ttl_sec)
+            run_patch["last_heartbeat_ts"] = now
+        self._store.update(task_id, run_patch)
+        running_record = self._store.get(task_id)
+        if running_record is None:
+            return False
+        self._emit_event(TaskRuntimeEventType.STARTED, running_record, "Task execution started")
+        task_log.info("task execution started")
+        try:
+            result: TaskExecutionResult = executor.execute(running_record)
+        except Exception as exc:
+            task_log.error("task execution failed: %s", exc)
+            return self.mark_terminal(
+                task_id,
+                TaskStatus.FAILED,
+                f"Executor failed: {exc}",
+            )
+
+        if result.status not in _TERMINAL_STATUSES:
+            raise ValueError(f"Executor must return terminal status, got {result.status}")
+        return self.mark_terminal(
+            task_id,
+            result.status,
+            result.summary,
+            output_file=result.output_file,
+            tool_use_id=result.tool_use_id,
+            usage=result.usage,
+        )
+
+    def cancel(self, task_id: str, reason: Optional[str] = None) -> None:
+        summary = reason or "Task cancelled"
+        self.mark_terminal(
+            task_id,
+            TaskStatus.STOPPED,
+            summary,
+            terminal_reason="cancelled",
+        )
+
+    def publish_progress(self, task_id: str, summary: str) -> bool:
+        record = self._store.get(task_id)
+        if record is None:
+            return False
+        self._emit_event(TaskRuntimeEventType.PROGRESS, record, summary)
+        return True
+
+    def drain_events(self) -> list[TaskRuntimeEvent]:
+        with self._lock:
+            events = list(self._events)
+            self._events.clear()
+        return events
+
+    def wait_for_terminal(
+        self,
+        task_id: str,
+        *,
+        timeout_sec: Optional[float] = None,
+        poll_interval_sec: float = 0.02,
+    ) -> Optional[TaskStatus]:
+        deadline = None if timeout_sec is None else time.monotonic() + float(timeout_sec)
+        poll_interval_sec = max(poll_interval_sec, 0.001)
+        while True:
+            record = self._store.get(task_id)
+            if record is None:
+                return None
+            if record.status in _TERMINAL_STATUSES:
+                return record.status
+            if deadline is not None and time.monotonic() >= deadline:
+                return None
+            time.sleep(poll_interval_sec)
+
+    def append_task_output(self, task_id: str, chunk: str) -> bool:
+        if self._output_sink is None:
+            return False
+        self._output_sink.append(task_id, chunk)
+        return True
+
+    def read_task_output(self, task_id: str, offset: int = 0) -> tuple[str, int]:
+        if self._output_sink is None:
+            return "", 0
+        return self._output_sink.read_from(task_id, offset)
+
+    def heartbeat(
+        self,
+        task_id: str,
+        *,
+        worker_id: Optional[str] = None,
+        extend_sec: Optional[float] = None,
+    ) -> bool:
+        record = self._store.get(task_id)
+        if record is None or record.status != TaskStatus.RUNNING:
+            return False
+        now = time.time()
+        base = self._lease_ttl_sec if self._lease_ttl_sec is not None else 300.0
+        ext = float(extend_sec) if extend_sec is not None else float(base)
+        patch: dict = {
+            "last_heartbeat_ts": now,
+            "lease_until_ts": now + ext,
+            "updated_at": now,
+        }
+        if worker_id is not None:
+            patch["worker_id"] = worker_id
+        self._store.update(task_id, patch)
+        return True
+
+    def reclaim_stale_running_tasks(self, *, now_ts: Optional[float] = None) -> list[str]:
+        now = time.time() if now_ts is None else float(now_ts)
+        reclaimed: list[str] = []
+        for record in self._store.list():
+            if record.status != TaskStatus.RUNNING:
+                continue
+            if record.lease_until_ts is None:
+                continue
+            if record.lease_until_ts >= now:
+                continue
+            tid = record.task_id
+            if self.mark_terminal(
+                tid,
+                TaskStatus.FAILED,
+                "Lease expired (worker heartbeat lost or process crash)",
+                terminal_reason="lease_expired",
+            ):
+                reclaimed.append(tid)
+        return reclaimed
+
+    def mark_terminal(
+        self,
+        task_id: str,
+        status: TaskStatus,
+        summary: str,
+        *,
+        output_file: Optional[str] = None,
+        tool_use_id: Optional[str] = None,
+        usage: Optional[dict[str, int]] = None,
+        requires_action: bool = False,
+        terminal_reason: Optional[str] = None,
+    ) -> bool:
+        if status not in _TERMINAL_STATUSES:
+            raise ValueError(f"status must be terminal, got {status}")
+        record = self._store.get(task_id)
+        if record is None:
+            return False
+        if status in record.terminal_emitted_statuses:
+            return False
+
+        now = time.time()
+        next_emitted = set(record.terminal_emitted_statuses)
+        next_emitted.add(status)
+        updated = replace(
+            record,
+            status=status,
+            output_file=output_file or record.output_file,
+            terminal_emitted_statuses=next_emitted,
+            updated_at=now,
+        )
+        self._store.update(task_id, updated.__dict__)
+
+        self._queue.enqueue(
+            TaskNotificationEnvelope(
+                command_id=new_notification_command_id(),
+                task_id=task_id,
+                task_type=updated.task_type,
+                status=status,
+                summary=summary,
+                scope=updated.scope,
+                priority=notification_priority_for_terminal_status(status),
+                output_file=updated.output_file,
+                tool_use_id=tool_use_id,
+                usage=usage,
+                requires_action=requires_action,
+                terminal_reason=terminal_reason,
+            )
+        )
+        self._emit_event(
+            TaskRuntimeEventType.TERMINAL,
+            updated,
+            summary,
+            status=status,
+            terminal_reason=terminal_reason,
+        )
+        ObservabilityLoggerAdapter(
+            logger,
+            build_log_context(
+                run_id=updated.run_id,
+                session_id=updated.scope.agent_id,
+                task_id=updated.task_id,
+            ).as_extra(),
+        ).info("task terminal status=%s summary=%s", status.value, summary)
+        return True
+
+    def drain_notifications(
+        self, scope: TaskScope, max_priority: QueuePriority
+    ) -> list[TaskNotificationEnvelope]:
+        return self._queue.peek_for_scope(scope, max_priority)
+
+    def ack_notifications(self, command_ids: list[str]) -> None:
+        self._queue.remove(command_ids)
+
+    def reserve_notifications(
+        self,
+        scope: TaskScope,
+        max_priority: QueuePriority,
+        *,
+        limit: int = 8,
+    ) -> Optional[ReservedNotificationBatch]:
+        if limit <= 0:
+            return None
+        items = self._queue.peek_for_scope(scope, max_priority)[:limit]
+        if not items:
+            return None
+        self._queue.remove([item.command_id for item in items])
+        batch = ReservedNotificationBatch(
+            batch_id=new_reserved_batch_id(),
+            scope=scope,
+            items=items,
+        )
+        with self._lock:
+            self._reserved_batches[batch.batch_id] = batch
+        return batch
+
+    def ack_reserved(self, batch_id: str) -> None:
+        with self._lock:
+            self._reserved_batches.pop(batch_id, None)
+
+    def nack_reserved(self, batch_id: str, *, requeue: bool = True) -> None:
+        with self._lock:
+            batch = self._reserved_batches.pop(batch_id, None)
+        if batch is None:
+            return
+        if requeue:
+            for item in batch.items:
+                self._queue.enqueue(item)
+
+    def has_pending_notifications(
+        self, scope: TaskScope, max_priority: QueuePriority
+    ) -> bool:
+        return bool(self._queue.peek_for_scope(scope, max_priority))

langchain_agentx/task_runtime/output/__init__.py

@@ -0,0 +1,5 @@
+"""Task output buffering (§10.4)."""
+
+from .sink import InMemoryTaskOutputSink, TaskOutputSink
+
+__all__ = ["InMemoryTaskOutputSink", "TaskOutputSink"]