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

langchain_agentx/task_runtime/core/ids.py

@@ -0,0 +1,33 @@
+"""
+task_runtime/core/ids.py — 任务与通知条目 ID 生成（R2 共享逻辑）
+
+职责：
+    从 orchestrator 中抽出无状态的 ID 生成，避免编排层与领域类型混杂，
+    便于单测与将来替换为 ULID/Snowflake 等策略。
+
+边界：
+    仅本包使用；不保证跨进程全局唯一（与 CC 本地 task id 策略一致）。
+"""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+
+def new_task_id() -> str:
+    return f"task_{uuid4().hex[:10]}"
+
+
+def new_notification_command_id() -> str:
+    """``TaskNotificationEnvelope.command_id`` 用短 ID。"""
+    return f"cmd_{uuid4().hex[:10]}"
+
+
+def new_run_id() -> str:
+    """§10.3 持久化任务 run 标识。"""
+    return f"run_{uuid4().hex[:12]}"
+
+
+def new_reserved_batch_id() -> str:
+    """``ReservedNotificationBatch.batch_id``。"""
+    return f"batch_{uuid4().hex[:10]}"

langchain_agentx/task_runtime/core/interfaces.py

@@ -0,0 +1,115 @@
+"""
+task_runtime/core/interfaces.py — Task Runtime 抽象接口层（Protocol）
+
+职责：
+    作为任务模块的稳定边界，定义可替换的抽象接口：
+    1. TaskStore：任务记录存取与更新
+    2. TaskCommandQueue：任务通知排队、按 scope/priority 读取、确认移除
+    3. TaskRuntime：任务生命周期编排与通知消费协议
+
+设计意图：
+    - 让 loop 改造与 task 模块开发可并行推进
+    - 让 in-memory / 持久化 / 分布式实现可以无缝替换
+
+与 Agent Loop 的接线：
+    - 图节点消费的「多来源队列」协议见 ``task_runtime.integrations.loop_integration.QueuedCommandProvider``
+    - ``TaskRuntime`` 经 ``LoopTaskInjectionAdapter`` 适配为该协议
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Optional, Protocol
+
+from .types import (
+    QueuePriority,
+    ReservedNotificationBatch,
+    TaskExecutionResult,
+    TaskRuntimeEvent,
+    TaskNotificationEnvelope,
+    TaskRecord,
+    TaskScope,
+    TaskSpec,
+    TaskStatus,
+    TaskType,
+)
+
+
+class TaskStore(Protocol):
+    def create(self, record: TaskRecord) -> None: ...
+    def get(self, task_id: str) -> Optional[TaskRecord]: ...
+    def update(self, task_id: str, patch: dict) -> Optional[TaskRecord]: ...
+    def list(self) -> Iterable[TaskRecord]: ...
+    def delete(self, task_id: str) -> None: ...
+    def evict_expired(self, *, now_ts: float, ttl_sec: float) -> int: ...
+    def evict_over_capacity(self, *, max_records: int) -> int: ...
+
+
+class TaskCommandQueue(Protocol):
+    def enqueue(self, env: TaskNotificationEnvelope) -> None: ...
+    def peek_for_scope(
+        self, scope: TaskScope, max_priority: QueuePriority
+    ) -> list[TaskNotificationEnvelope]: ...
+    def remove(self, command_ids: list[str]) -> None: ...
+
+
+class TaskRuntime(Protocol):
+    def spawn(self, spec: TaskSpec) -> str: ...
+    def cancel(self, task_id: str, reason: Optional[str] = None) -> None: ...
+    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: ...
+    def drain_notifications(
+        self, scope: TaskScope, max_priority: QueuePriority
+    ) -> list[TaskNotificationEnvelope]: ...
+    def ack_notifications(self, command_ids: list[str]) -> None: ...
+    def reserve_notifications(
+        self,
+        scope: TaskScope,
+        max_priority: QueuePriority,
+        *,
+        limit: int = 8,
+    ) -> Optional[ReservedNotificationBatch]: ...
+    def ack_reserved(self, batch_id: str) -> None: ...
+    def nack_reserved(self, batch_id: str, *, requeue: bool = True) -> None: ...
+    def has_pending_notifications(
+        self, scope: TaskScope, max_priority: QueuePriority
+    ) -> bool: ...
+    def register_executor(
+        self, task_type: TaskType, executor: "TaskExecutor", *, overwrite: bool = False
+    ) -> None: ...
+    def run_task(self, task_id: str) -> bool: ...
+    def publish_progress(self, task_id: str, summary: str) -> bool: ...
+    def drain_events(self) -> list[TaskRuntimeEvent]: ...
+    # §10.2 前台等待（协议层轮询，不阻塞 LangGraph 主线程）
+    def wait_for_terminal(
+        self,
+        task_id: str,
+        *,
+        timeout_sec: Optional[float] = None,
+        poll_interval_sec: float = 0.02,
+    ) -> Optional[TaskStatus]: ...
+    # §10.4 持续输出（可选 sink）
+    def append_task_output(self, task_id: str, chunk: str) -> bool: ...
+    def read_task_output(self, task_id: str, offset: int = 0) -> tuple[str, int]: ...
+    # §10.3 租约与心跳
+    def heartbeat(
+        self,
+        task_id: str,
+        *,
+        worker_id: Optional[str] = None,
+        extend_sec: Optional[float] = None,
+    ) -> bool: ...
+    def reclaim_stale_running_tasks(self, *, now_ts: Optional[float] = None) -> list[str]: ...
+
+
+class TaskExecutor(Protocol):
+    def execute(self, record: TaskRecord) -> TaskExecutionResult: ...

langchain_agentx/task_runtime/core/notification_priority.py

@@ -0,0 +1,19 @@
+"""
+task_runtime/core/notification_priority.py — 终态 → 队列优先级映射（R2）
+
+职责：
+    将 ``TaskStatus`` 映射到 ``QueuePriority``，供编排层在 ``mark_terminal`` 时
+    入队通知；与 orchestrator 中历史 ``_priority_for_status`` 行为一致。
+"""
+
+from __future__ import annotations
+
+from .types import QueuePriority, TaskStatus
+
+
+def notification_priority_for_terminal_status(status: TaskStatus) -> QueuePriority:
+    if status == TaskStatus.FAILED:
+        return QueuePriority.NOW
+    if status == TaskStatus.COMPLETED:
+        return QueuePriority.NEXT
+    return QueuePriority.LATER

langchain_agentx/task_runtime/core/types.py

@@ -0,0 +1,136 @@
+"""
+task_runtime/core/types.py — Task Runtime 领域类型定义
+
+职责：
+    定义任务调度领域的统一类型，作为 loop / tools / integrations 共享契约：
+    1. 任务基础语义（TaskType / TaskStatus）
+    2. 队列调度语义（QueuePriority）
+    3. 作用域语义（TaskScope，用于 agent_id 隔离）
+    4. 输入与持久化记录语义（TaskSpec / TaskRecord）
+    5. 通知协议语义（TaskNotificationEnvelope）
+
+边界约束：
+    - 本文件不依赖 LangGraph、ToolNode 或具体工具实现
+    - 保持“纯领域类型”，便于并行开发与后续接入
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+import time
+
+
+class TaskType(str, Enum):
+    LOCAL_AGENT = "local_agent"
+    LOCAL_BASH = "local_bash"
+    DREAM_TASK = "dream_task"
+    REMOTE_AGENT = "remote_agent"
+    IN_PROCESS_TEAMMATE = "in_process_teammate"
+    CUSTOM = "custom"
+
+
+class TaskStatus(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    STOPPED = "stopped"
+
+
+class QueuePriority(str, Enum):
+    NOW = "now"
+    NEXT = "next"
+    LATER = "later"
+
+
+class TaskRuntimeEventType(str, Enum):
+    STARTED = "started"
+    PROGRESS = "progress"
+    TERMINAL = "terminal"
+
+
+@dataclass(frozen=True)
+class TaskScope:
+    """Task scope for queue drain isolation.
+
+    agent_id=None means main-thread scope.
+    """
+
+    agent_id: Optional[str] = None
+
+
+@dataclass
+class TaskSpec:
+    task_type: TaskType
+    description: str
+    input: dict[str, Any]
+    scope: TaskScope
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class TaskRecord:
+    task_id: str
+    task_type: TaskType
+    status: TaskStatus
+    description: str
+    scope: TaskScope
+    input: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+    output_file: Optional[str] = None
+    terminal_emitted_statuses: set[TaskStatus] = field(default_factory=set)
+    notification_consumed: bool = False
+    # §10.3 运行中恢复：spawn/run 写入，heartbeat 续租，reclaim 回收
+    run_id: Optional[str] = None
+    external_ref: Optional[str] = None
+    lease_until_ts: Optional[float] = None
+    last_heartbeat_ts: Optional[float] = None
+    worker_id: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class TaskNotificationEnvelope:
+    command_id: str
+    task_id: str
+    task_type: TaskType
+    status: TaskStatus
+    summary: str
+    scope: TaskScope
+    priority: QueuePriority = QueuePriority.LATER
+    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
+
+
+@dataclass(frozen=True)
+class ReservedNotificationBatch:
+    batch_id: str
+    scope: TaskScope
+    items: list[TaskNotificationEnvelope]
+
+
+@dataclass(frozen=True)
+class TaskExecutionResult:
+    status: TaskStatus
+    summary: str
+    output_file: Optional[str] = None
+    tool_use_id: Optional[str] = None
+    usage: Optional[dict[str, int]] = None
+
+
+@dataclass(frozen=True)
+class TaskRuntimeEvent:
+    event_type: TaskRuntimeEventType
+    task_id: str
+    task_type: TaskType
+    status: TaskStatus
+    summary: str
+    scope: TaskScope
+    terminal_reason: Optional[str] = None
+    created_at: float = field(default_factory=time.time)

langchain_agentx/task_runtime/integrations/__init__.py

@@ -0,0 +1,33 @@
+from .loop_adapter import LoopInjectionBatch, LoopTaskInjectionAdapter
+from .loop_integration import (
+    QueuedCommandProvider,
+    decode_provider_batch_id,
+    encode_provider_batch_id,
+)
+from .queued_command_provider import (
+    InMemoryQueuedCommandProvider,
+    QueuedCommandEnvelope,
+)
+from .prefetch_providers import MemoryPrefetchProvider
+from ..skill_prefetch import SkillPrefetchProvider
+from .tool_use_summary_provider import ToolUseSummaryProvider
+from .sqlite_queued_command_provider import SqliteQueuedCommandProvider
+from .provider_factory import ProviderBundle, ProviderFactoryConfig, build_provider_bundle
+
+__all__ = [
+    "LoopInjectionBatch",
+    "LoopTaskInjectionAdapter",
+    "QueuedCommandProvider",
+    "encode_provider_batch_id",
+    "decode_provider_batch_id",
+    "InMemoryQueuedCommandProvider",
+    "QueuedCommandEnvelope",
+    "MemoryPrefetchProvider",
+    "SkillPrefetchProvider",
+    "ToolUseSummaryProvider",
+    "SqliteQueuedCommandProvider",
+    "ProviderFactoryConfig",
+    "ProviderBundle",
+    "build_provider_bundle",
+]
+

langchain_agentx/task_runtime/integrations/loop_adapter.py

@@ -0,0 +1,91 @@
+"""
+task_runtime/integrations/loop_adapter.py — Loop 集成适配层
+
+职责：
+    TaskRuntime 与 loop 图节点之间的边界层，负责：
+    1. 从 runtime 读取可消费任务通知（按 scope / priority）
+    2. 转换为 loop 可注入的 attachment message 结构
+    3. 在 loop 消费后进行 ack，防止重复注入
+
+边界说明：
+    - 仅负责协议映射，不承担任务执行与状态机职责
+    - 便于后续在 `post_tools/attachment_injection` 节点直接接线
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from ..core.interfaces import TaskRuntime
+from ..core.types import QueuePriority, TaskNotificationEnvelope, TaskScope
+
+
+@dataclass(frozen=True)
+class LoopInjectionBatch:
+    batch_id: str
+    command_ids: list[str]
+    attachment_messages: list[dict]
+
+
+def _to_attachment_message(env: TaskNotificationEnvelope) -> dict:
+    text = f"[task_notification] task_id={env.task_id} status={env.status.value} summary={env.summary}"
+    return {
+        "role": "user",
+        "content": [{"type": "text", "text": text}],
+        "metadata": {
+            "task_notification": {
+                "command_id": env.command_id,
+                "task_id": env.task_id,
+                "status": env.status.value,
+                "priority": env.priority.value,
+                "output_file": env.output_file,
+                "terminal_reason": env.terminal_reason,
+            }
+        },
+    }
+
+
+class LoopTaskInjectionAdapter:
+    """Convert queued task notifications into loop-consumable messages."""
+
+    def __init__(self, runtime: TaskRuntime) -> None:
+        self._runtime = runtime
+
+    def build_batch(
+        self,
+        scope: TaskScope,
+        max_priority: QueuePriority = QueuePriority.NEXT,
+        *,
+        limit: int = 8,
+    ) -> LoopInjectionBatch:
+        reserved = self._runtime.reserve_notifications(
+            scope=scope,
+            max_priority=max_priority,
+            limit=limit,
+        )
+        if not reserved:
+            return LoopInjectionBatch(batch_id="", command_ids=[], attachment_messages=[])
+        return LoopInjectionBatch(
+            batch_id=reserved.batch_id,
+            command_ids=[item.command_id for item in reserved.items],
+            attachment_messages=[_to_attachment_message(item) for item in reserved.items],
+        )
+
+    def ack_batch(self, batch: LoopInjectionBatch) -> None:
+        if batch.batch_id:
+            self._runtime.ack_reserved(batch.batch_id)
+
+    def nack_batch(self, batch: LoopInjectionBatch, *, requeue: bool = True) -> None:
+        if batch.batch_id:
+            self._runtime.nack_reserved(batch.batch_id, requeue=requeue)
+
+    def has_pending(
+        self, scope: TaskScope, max_priority: QueuePriority = QueuePriority.NEXT
+    ) -> bool:
+        return self._runtime.has_pending_notifications(scope, max_priority)
+
+    def ingest_from_messages(self, *, scope: TaskScope, messages: list[Any]) -> int:
+        """TaskRuntime 无 messages 桥接；占位以满足 `QueuedCommandProvider` 契约。"""
+        return 0
+

langchain_agentx/task_runtime/integrations/loop_integration.py

@@ -0,0 +1,61 @@
+"""
+task_runtime/integrations/loop_integration.py — Agent Loop 与 task_runtime 的契约面
+
+职责：
+    1. **QueuedCommandProvider**：`create_loop_agent` 中 `task_event_commit_ack` /
+       `task_event_reserve` 节点消费的统一协议（与 `LoopTaskInjectionAdapter` 同形）。
+    2. **批次 id 编解码**：多 provider 链下 `pending_task_batch_id` 使用 `p{index}:{batch_id}`，
+       与 loop 图实现一致，供单测与外部工具复用。
+
+边界：
+    - 不包含 LangGraph 节点实现（见 `loop/graph/factory.py`）
+    - `TaskRuntime` 本体协议见 `task_runtime.core.interfaces.TaskRuntime`
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from ..core.types import QueuePriority, TaskScope
+from .loop_adapter import LoopInjectionBatch
+
+
+class QueuedCommandProvider(Protocol):
+    """供 Agent Loop `task_event_*` 链调用的 queued-command 来源（task / prefetch / summary 等）。"""
+
+    def build_batch(
+        self,
+        scope: TaskScope,
+        max_priority: QueuePriority = QueuePriority.NEXT,
+        *,
+        limit: int = 8,
+    ) -> LoopInjectionBatch: ...
+
+    def ack_batch(self, batch: LoopInjectionBatch) -> None: ...
+
+    def nack_batch(self, batch: LoopInjectionBatch, *, requeue: bool = True) -> None: ...
+
+    def has_pending(
+        self, scope: TaskScope, max_priority: QueuePriority = QueuePriority.NEXT
+    ) -> bool: ...
+
+    def ingest_from_messages(self, *, scope: TaskScope, messages: list[Any]) -> int:
+        """reserve 前由 loop 调用；将当前轮 `messages` 桥接到队列（无则返回 0）。"""
+
+
+def encode_provider_batch_id(provider_index: int, batch_id: str) -> str:
+    """与 `create_loop_agent` 中 `pending_task_batch_id` 编码一致。"""
+    return f"p{provider_index}:{batch_id}"
+
+
+def decode_provider_batch_id(encoded: str) -> tuple[int, str] | None:
+    """解码 `encode_provider_batch_id`；非法输入返回 None。"""
+    if not isinstance(encoded, str) or ":" not in encoded:
+        return None
+    prefix, raw_batch_id = encoded.split(":", 1)
+    if not prefix.startswith("p"):
+        return None
+    try:
+        return int(prefix[1:]), raw_batch_id
+    except ValueError:
+        return None

langchain_agentx/task_runtime/integrations/prefetch_providers.py

@@ -0,0 +1,108 @@
+"""
+task_runtime/integrations/prefetch_providers.py — 预取类 queued-command provider
+
+职责：
+    基于通用 InMemoryQueuedCommandProvider 封装 memory 预取来源：
+    1. MemoryPrefetchProvider：注入 memory 预取结果
+
+边界：
+    - 仅负责“把外部结果转为 queued command”
+    - 不承担 loop 路由与 task 生命周期管理
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ..core.types import QueuePriority, TaskScope
+from .loop_adapter import LoopInjectionBatch
+from .queued_command_provider import InMemoryQueuedCommandProvider, QueuedCommandEnvelope
+
+
+class MemoryPrefetchProvider:
+    """将 memory 预取结果转换为 queued commands。"""
+
+    def __init__(
+        self,
+        backend: InMemoryQueuedCommandProvider | None = None,
+        *,
+        max_queue_size: int | None = None,
+        ttl_sec: float | None = None,
+    ) -> None:
+        self._backend = backend or InMemoryQueuedCommandProvider(
+            max_queue_size=max_queue_size,
+            ttl_sec=ttl_sec,
+        )
+
+    def ingest_memory_items(
+        self,
+        *,
+        scope: TaskScope,
+        items: list[dict[str, Any]],
+        priority: QueuePriority = QueuePriority.NEXT,
+    ) -> int:
+        count = 0
+        for item in items:
+            memory_id = str(item.get("memory_id") or f"mem_{count}")
+            summary = str(item.get("summary") or "").strip() or "memory prefetch result"
+            self._backend.enqueue(
+                QueuedCommandEnvelope(
+                    command_id=f"mem_{memory_id}",
+                    source="memory_prefetch",
+                    summary=summary,
+                    scope=scope,
+                    priority=priority,
+                    payload=item,
+                    dedup_key=f"memory:{memory_id}",
+                )
+            )
+            count += 1
+        return count
+
+    def ingest_from_context_messages(
+        self,
+        *,
+        scope: TaskScope,
+        messages: list,
+        priority: QueuePriority = QueuePriority.NEXT,
+        limit: int = 8,
+    ) -> int:
+        """从 loop/context 消息中提取可预取记忆（real-source bridge）。"""
+        items: list[dict[str, Any]] = []
+        for msg in messages[-limit:]:
+            content = getattr(msg, "content", None)
+            if isinstance(content, str) and content.strip():
+                items.append(
+                    {
+                        "memory_id": f"msg_{len(items)}",
+                        "summary": content.strip()[:120],
+                        "source": "context_message",
+                    }
+                )
+        return self.ingest_memory_items(scope=scope, items=items, priority=priority)
+
+    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 ingest_from_messages(
+        self, *, scope: TaskScope, messages: list
+    ) -> int:
+        return self.ingest_from_context_messages(scope=scope, messages=messages)
+
+