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

langchain_agentx/task_runtime/output/sink.py

@@ -0,0 +1,64 @@
+"""
+task_runtime/output/sink.py — 任务持续输出（§10.4 TaskOutputSink）
+
+职责：
+    提供与终态 notification 正交的 **append-only 输出缓冲**，支持按 task_id 追加与
+    按字节 offset 续读，供排障与（未来）CLI 回放。
+
+与 CC 对比：
+    CC 将任务 stdout 等落盘到 workspace 路径；本仓库先提供进程内 **InMemory** 实现，
+    上限策略与 ``never_truncate`` 类语义对齐为「超上限丢弃头部、保留尾部」。
+
+边界：
+    - 不负责持久化跨进程；跨重启持久化由调用方换用基于文件/SQLite 的 Sink 实现（未来）。
+"""
+
+from __future__ import annotations
+
+from threading import RLock
+from typing import Optional, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class TaskOutputSink(Protocol):
+    """Append-only task output; ``offset`` in :meth:`read_from` is **byte** offset."""
+
+    def append(self, task_id: str, chunk: str) -> None: ...
+
+    def read_from(self, task_id: str, offset: int = 0) -> tuple[str, int]:
+        """Return ``(decoded_text_slice, next_byte_offset)`` for the full buffer length."""
+        ...
+
+
+class InMemoryTaskOutputSink:
+    """进程内输出缓冲：UTF-8 字节存储；超上限时丢弃最旧字节（保留尾部）。"""
+
+    def __init__(self, *, max_bytes_per_task: Optional[int] = 1_048_576) -> None:
+        self._max_bytes_per_task = max_bytes_per_task
+        self._lock = RLock()
+        self._buffers: dict[str, bytearray] = {}
+
+    def append(self, task_id: str, chunk: str) -> None:
+        if not chunk:
+            return
+        raw = chunk.encode("utf-8")
+        with self._lock:
+            buf = self._buffers.setdefault(task_id, bytearray())
+            buf.extend(raw)
+            max_b = self._max_bytes_per_task
+            if max_b is not None and len(buf) > max_b:
+                del buf[: len(buf) - max_b]
+
+    def read_from(self, task_id: str, offset: int = 0) -> tuple[str, int]:
+        with self._lock:
+            buf = self._buffers.get(task_id)
+            if not buf:
+                return "", 0
+            data = bytes(buf)
+            total = len(data)
+            if offset < 0:
+                offset = 0
+            if offset >= total:
+                return "", total
+            tail = data[offset:]
+            return tail.decode("utf-8", errors="replace"), total

langchain_agentx/task_runtime/policy/__init__.py

@@ -0,0 +1,11 @@
+"""Runtime policies (withhold visibility, etc.)."""
+
+from .withhold_visibility import (
+    DEFAULT_WITHHOLD_TASK_EVENT_POLICY,
+    WithholdTaskEventPolicy,
+)
+
+__all__ = [
+    "DEFAULT_WITHHOLD_TASK_EVENT_POLICY",
+    "WithholdTaskEventPolicy",
+]

langchain_agentx/task_runtime/policy/withhold_visibility.py

@@ -0,0 +1,32 @@
+"""
+task_runtime/policy/withhold_visibility.py — withhold 与 task 事件可见性（§10.6）
+
+职责：
+    冻结 **可测试的策略占位**：withhold（输出截断窗口）期间，task 通知与输出 sink
+    与 loop 恢复的相对顺序。默认行为保守：不延迟终态通知、输出始终写入 sink。
+
+与 loop 的关系：
+    具体注入顺序由 ``create_loop_agent`` / controller 实现；本模块仅提供策略值对象，
+    供未来 loop 与 adapter 读取，避免魔法布尔散落在多处。
+
+边界：
+    - 本阶段不修改 loop 默认行为；未传入策略时等价于默认实例。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class WithholdTaskEventPolicy:
+    """withhold 窗口内 task 相关事件的可见性策略（§10.6 契约占位）。"""
+
+    delay_terminal_task_notification: bool = False
+    """若为 True，task 终态通知延迟到 withhold 解除后合并注入（未来）。"""
+
+    write_task_output_sink_during_withhold: bool = True
+    """若为 True，withhold 期间仍向 §10.4 sink 追加（便于排障）。"""
+
+
+DEFAULT_WITHHOLD_TASK_EVENT_POLICY = WithholdTaskEventPolicy()

langchain_agentx/task_runtime/queue/__init__.py

@@ -0,0 +1,5 @@
+"""Task notification queue implementations."""
+
+from .in_memory import InMemoryTaskCommandQueue
+
+__all__ = ["InMemoryTaskCommandQueue"]

langchain_agentx/task_runtime/queue/in_memory.py

@@ -0,0 +1,55 @@
+"""
+task_runtime/queue/in_memory.py — TaskCommandQueue 内存实现
+
+职责：
+    基于 list 的任务通知队列；采用 RLock 保证基础并发安全。
+"""
+
+from __future__ import annotations
+
+from threading import RLock
+
+from ..core.interfaces import TaskCommandQueue
+from ..core.types import (
+    QueuePriority,
+    TaskNotificationEnvelope,
+    TaskScope,
+)
+
+
+_PRIORITY_ORDER = {
+    QueuePriority.NOW: 0,
+    QueuePriority.NEXT: 1,
+    QueuePriority.LATER: 2,
+}
+
+
+class InMemoryTaskCommandQueue(TaskCommandQueue):
+    def __init__(self) -> None:
+        self._lock = RLock()
+        self._queue: list[TaskNotificationEnvelope] = []
+
+    def enqueue(self, env: TaskNotificationEnvelope) -> None:
+        with self._lock:
+            self._queue.append(env)
+
+    def peek_for_scope(
+        self, scope: TaskScope, max_priority: QueuePriority
+    ) -> list[TaskNotificationEnvelope]:
+        threshold = _PRIORITY_ORDER[max_priority]
+        with self._lock:
+            filtered = [
+                item
+                for item in self._queue
+                if item.scope.agent_id == scope.agent_id
+                and _PRIORITY_ORDER[item.priority] <= threshold
+            ]
+            filtered.sort(key=lambda item: _PRIORITY_ORDER[item.priority])
+            return filtered
+
+    def remove(self, command_ids: list[str]) -> None:
+        if not command_ids:
+            return
+        ids = set(command_ids)
+        with self._lock:
+            self._queue = [item for item in self._queue if item.command_id not in ids]

langchain_agentx/task_runtime/skill_prefetch/__init__.py

@@ -0,0 +1,4 @@
+from .provider import SkillPrefetchProvider
+
+__all__ = ["SkillPrefetchProvider"]
+

langchain_agentx/task_runtime/skill_prefetch/attachments.py

@@ -0,0 +1,46 @@
+"""
+task_runtime/skill_prefetch/attachments.py — Skill 附件构造器
+
+职责：
+    将 `SkillHint` 领域对象映射为 loop 可注入的 attachment message(dict)。
+
+对照：
+    对齐 CC 中 skill_listing / dynamic_skill attachment 的角色，
+    但复用本工程 `task_event_reserve` + dedup 契约。
+
+实现约束：
+    - 采用 OOP 构造器，不在外层散落函数；
+    - 兼容现有 dedup：复用 `metadata.task_notification.command_id`。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .models import SkillHint
+
+
+class SkillAttachmentBuilder:
+    def build(self, hint: SkillHint) -> dict[str, Any]:
+        return {
+            "role": "user",
+            "content": [{"type": "text", "text": self._build_text(hint)}],
+            "metadata": {
+                # Reuse task_notification.command_id for existing dedup filter.
+                "task_notification": {"command_id": hint.command_id},
+                "skill_notification": {
+                    "command_id": hint.command_id,
+                    "kind": hint.kind,
+                    "skill_name": hint.payload.get("skill_name"),
+                    "source": hint.payload.get("source", "prefetch"),
+                    "provider": "skill_prefetch",
+                    "turn_index": hint.payload.get("turn_index"),
+                },
+            },
+        }
+
+    def _build_text(self, hint: SkillHint) -> str:
+        if hint.kind == "skill_listing":
+            return f"[skill_listing] {hint.summary}"
+        return f"[dynamic_skill] {hint.summary}"
+

langchain_agentx/task_runtime/skill_prefetch/models.py

@@ -0,0 +1,37 @@
+"""
+tools/task_runtime/skill_prefetch/models.py — Skill 预取领域模型
+
+职责：
+    承载 Skill 预取阶段的稳定数据对象（hint / command 元信息）。
+
+对照：
+    对齐 CC skill discovery 的“轻量列表提示 + 动态候选提示”语义，
+    用 dataclass 固化本工程 provider 内部契约。
+
+实现约束：
+    - 仅定义数据模型，不承载队列/注入/渲染逻辑；
+    - 字段命名保持与 loop 注入 metadata 对齐（kind/command_id/source）。
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from ..core.types import QueuePriority, TaskScope
+
+SkillHintKind = Literal["skill_listing", "dynamic_skill"]
+
+
+@dataclass(frozen=True)
+class SkillHint:
+    kind: SkillHintKind
+    command_id: str
+    summary: str
+    scope: TaskScope
+    priority: QueuePriority = QueuePriority.NEXT
+    payload: dict[str, Any] = field(default_factory=dict)
+    dedup_key: str | None = None
+    created_at: float = field(default_factory=time.time)
+

langchain_agentx/task_runtime/skill_prefetch/provider.py

@@ -0,0 +1,344 @@
+"""
+task_runtime/skill_prefetch/provider.py — Skill 预取队列提供者
+
+职责：
+    在 loop 注入链中提供 skill 可见性附件（skill_listing / dynamic_skill）。
+
+对照：
+    对齐 CC “loop 提供可见性，SkillTool 负责执行”的分层；
+    本类只输出附件批次，不执行任何 skill 内容。
+
+实现约束：
+    - OOP 协作：技能发现、附件渲染、队列批次管理职责分离；
+    - 与 `QueuedCommandProvider` 契约对齐（build/ack/nack/has_pending/ingest）；
+    - 默认提供首轮可见性的 listing 注入能力。
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from threading import RLock
+from typing import TYPE_CHECKING
+from uuid import uuid4
+
+from langchain_agentx.workspace import resolve_agent_workspace_config
+
+from ..core.types import QueuePriority, TaskScope
+from ..integrations.loop_adapter import LoopInjectionBatch
+from .attachments import SkillAttachmentBuilder
+from .models import SkillHint
+
+if TYPE_CHECKING:
+    from langchain_agentx.tools.skill.loader import SkillCommandRepository
+
+_PRIORITY_ORDER = {
+    QueuePriority.NOW: 0,
+    QueuePriority.NEXT: 1,
+    QueuePriority.LATER: 2,
+}
+
+# 对齐 CC SkillTool prompt 的 listing 预算/截断语义。
+# - 总预算：listing 最多占上下文的一小部分，避免吞噬主对话 token。
+# - 单条上限：每个 skill 的描述做硬截断，避免个别长描述“挤掉”其它技能。
+SKILL_BUDGET_CONTEXT_PERCENT = 0.01
+CHARS_PER_TOKEN = 4
+DEFAULT_CHAR_BUDGET = 8_000
+MAX_LISTING_DESC_CHARS = 250
+MIN_DESC_LENGTH = 20
+
+
+class SkillPrefetchProvider:
+    def __init__(
+        self,
+        *,
+        workspace_root: str | Path = ".",
+        agent_home: str = ".langchain_agentx",
+        skills_root: str | Path | None = None,
+        repository: "SkillCommandRepository | None" = None,
+        attachment_builder: SkillAttachmentBuilder | None = None,
+        max_queue_size: int | None = None,
+        ttl_sec: float | None = None,
+    ) -> None:
+        del max_queue_size, ttl_sec
+        workspace_cfg = resolve_agent_workspace_config(
+            workspace_root=workspace_root,
+            agent_home=agent_home,
+        )
+        skills_dir = (
+            Path(skills_root).expanduser().resolve()
+            if skills_root
+            else workspace_cfg.skills_dir
+        )
+        if repository is None:
+            # 延迟导入，避免 task_runtime <-> tools 初始化循环依赖。
+            from langchain_agentx.tools.skill.loader import SkillCommandRepository
+
+            repository = SkillCommandRepository(skills_dir)
+        self._repository = repository
+        self._attachment_builder = attachment_builder or SkillAttachmentBuilder()
+        self._lock = RLock()
+        self._queue: list[SkillHint] = []
+        self._reserved_batches: dict[str, list[SkillHint]] = {}
+        # 可见 listing 的 (name, description, when_to_use) 签名，用于幂等刷新
+        self._listing_signature_by_scope: dict[str, tuple[tuple[str, str, str], ...]] = {}
+
+    def ingest_skill_items(
+        self,
+        *,
+        scope: TaskScope,
+        items: list[dict],
+        priority: QueuePriority = QueuePriority.NEXT,
+    ) -> int:
+        inserted = 0
+        for idx, item in enumerate(items):
+            skill_id = str(item.get("skill_id") or f"skill_{idx}")
+            summary = str(item.get("summary") or "").strip() or f"skill {skill_id}"
+            hint = SkillHint(
+                kind="dynamic_skill",
+                command_id=f"skill_{skill_id}",
+                summary=summary,
+                scope=scope,
+                priority=priority,
+                payload=dict(item),
+                dedup_key=f"skill:{scope.agent_id or 'main'}:{skill_id}",
+            )
+            self.enqueue_hint(hint)
+            inserted += 1
+        return inserted
+
+    def ingest_from_skill_metadata(
+        self,
+        *,
+        scope: TaskScope,
+        skills_metadata: list[dict],
+        priority: QueuePriority = QueuePriority.NEXT,
+    ) -> int:
+        items: list[dict] = []
+        for skill in skills_metadata:
+            skill_id = str(skill.get("name") or "").strip()
+            if not skill_id:
+                continue
+            items.append(
+                {
+                    "skill_id": skill_id,
+                    "summary": str(skill.get("description") or "").strip() or f"skill {skill_id}",
+                    "path": skill.get("path"),
+                    "source": skill.get("source", "prefetch"),
+                }
+            )
+        return self.ingest_skill_items(scope=scope, items=items, priority=priority)
+
+    def enqueue_hint(self, hint: SkillHint) -> None:
+        with self._lock:
+            if hint.dedup_key:
+                scope_id = self._scope_id(hint.scope)
+                self._queue = [
+                    item
+                    for item in self._queue
+                    if not (
+                        self._scope_id(item.scope) == scope_id
+                        and item.dedup_key == hint.dedup_key
+                    )
+                ]
+            self._queue.append(hint)
+
+    def build_batch(
+        self,
+        scope: TaskScope,
+        max_priority: QueuePriority = QueuePriority.NEXT,
+        *,
+        limit: int = 8,
+    ) -> LoopInjectionBatch:
+        # 仅把“当前 scope 且优先级满足阈值”的 hint 打包给 loop。
+        # 被选中的 hint 会先从队列移除并进入 reserved，等待 ack/nack。
+        threshold = _PRIORITY_ORDER[max_priority]
+        if limit <= 0:
+            return LoopInjectionBatch(batch_id="", command_ids=[], attachment_messages=[])
+        with self._lock:
+            selected = [
+                item
+                for item in self._queue
+                if self._scope_id(item.scope) == self._scope_id(scope)
+                and _PRIORITY_ORDER[item.priority] <= threshold
+            ]
+            selected.sort(key=lambda item: _PRIORITY_ORDER[item.priority])
+            selected = selected[:limit]
+            if not selected:
+                return LoopInjectionBatch(batch_id="", command_ids=[], attachment_messages=[])
+
+            selected_ids = {item.command_id for item in selected}
+            self._queue = [item for item in self._queue if item.command_id not in selected_ids]
+            batch_id = f"spbatch_{uuid4().hex[:10]}"
+            self._reserved_batches[batch_id] = selected
+            return LoopInjectionBatch(
+                batch_id=batch_id,
+                command_ids=[item.command_id for item in selected],
+                attachment_messages=[
+                    self._attachment_builder.build(item) for item in selected
+                ],
+            )
+
+    def ack_batch(self, batch: LoopInjectionBatch) -> None:
+        if not batch.batch_id:
+            return
+        with self._lock:
+            self._reserved_batches.pop(batch.batch_id, None)
+
+    def nack_batch(self, batch: LoopInjectionBatch, *, requeue: bool = True) -> None:
+        if not batch.batch_id:
+            return
+        with self._lock:
+            reserved = self._reserved_batches.pop(batch.batch_id, None)
+            if reserved and requeue:
+                self._queue.extend(reserved)
+
+    def has_pending(
+        self, scope: TaskScope, max_priority: QueuePriority = QueuePriority.NEXT
+    ) -> bool:
+        threshold = _PRIORITY_ORDER[max_priority]
+        with self._lock:
+            return any(
+                self._scope_id(item.scope) == self._scope_id(scope)
+                and _PRIORITY_ORDER[item.priority] <= threshold
+                for item in self._queue
+            )
+
+    def ingest_from_messages(self, *, scope: TaskScope, messages: list) -> int:
+        # v1：仅触发 listing 刷新（幂等），不从 messages 抽取动态候选。
+        # v2 特性：基于 messages 做 dynamic_skill 候选提取，待专项设计后启用。
+        del messages
+        hint = self._build_listing_hint(scope=scope)
+        if hint is None:
+            return 0
+        self.enqueue_hint(hint)
+        return 1
+
+    def _build_listing_hint(self, *, scope: TaskScope) -> SkillHint | None:
+        # 1) 从仓库读取所有命令并做可见性过滤（description/when_to_use/disable-model-invocation）。
+        # 2) 通过签名判断是否变化，未变化则不重复注入（减少上下文噪声）。
+        # 3) 生成“仅 metadata”的 listing 文本，正文由 skill 工具按需加载。
+        commands = self._repository.list_commands()
+        if not commands:
+            return None
+        ordered = sorted((c for c in commands if c.name), key=lambda c: c.name)
+        visible = [c for c in ordered if c.visible_in_slash_command_tool_listing()]
+        if not visible:
+            return None
+        signature = tuple(
+            (c.name, (c.description or "").strip(), (c.when_to_use or "").strip()) for c in visible
+        )
+        scope_id = self._scope_id(scope)
+        if self._listing_signature_by_scope.get(scope_id) == signature:
+            return None
+        self._listing_signature_by_scope[scope_id] = signature
+
+        # CC 对齐：listing 仅暴露 metadata，正文通过 skill 工具按需加载；
+        # 同时按上下文预算进行长度控制，避免 listing 吃掉过多上下文。
+        header = (
+            "Available skills (metadata only — call the `skill` tool with `skill_name` "
+            "to load full SKILL.md):"
+        )
+        summary = self._format_listing_within_budget(visible, header=header)
+
+        return SkillHint(
+            kind="skill_listing",
+            command_id=f"skill_listing_{scope_id}_{len(visible)}",
+            summary=summary,
+            scope=scope,
+            priority=QueuePriority.NEXT,
+            payload={"skill_count": len(visible), "source": "prefetch"},
+            dedup_key=f"skill_listing:{scope_id}",
+        )
+
+    @staticmethod
+    def _scope_id(scope: TaskScope) -> str:
+        return scope.agent_id or "main"
+
+    def _get_char_budget(self, context_window_tokens: int | None = None) -> int:
+        # 预算优先级：
+        #   1) 显式环境变量（便于压测/灰度）；
+        #   2) 模型上下文窗口推导；
+        #   3) 默认常量（与 CC 默认一致量级）。
+        raw = os.getenv("SLASH_COMMAND_TOOL_CHAR_BUDGET")
+        if raw:
+            try:
+                value = int(raw)
+            except ValueError:
+                value = 0
+            if value > 0:
+                return value
+        if context_window_tokens and context_window_tokens > 0:
+            return int(context_window_tokens * CHARS_PER_TOKEN * SKILL_BUDGET_CONTEXT_PERCENT)
+        return DEFAULT_CHAR_BUDGET
+
+    @staticmethod
+    def _truncate(text: str, max_len: int) -> str:
+        if max_len <= 0:
+            return ""
+        if len(text) <= max_len:
+            return text
+        if max_len == 1:
+            return "…"
+        return text[: max_len - 1] + "…"
+
+    def _command_description(self, cmd) -> str:
+        # CC 语义：展示 description + when_to_use（若同时存在），再做单条硬截断。
+        desc = (cmd.description or "").strip().replace("\n", " ")
+        wtu = (cmd.when_to_use or "").strip().replace("\n", " ")
+        merged = f"{desc} - {wtu}" if desc and wtu else (desc or wtu)
+        return self._truncate(merged, MAX_LISTING_DESC_CHARS)
+
+    def _format_command_line(self, cmd, *, desc_max_len: int | None = None) -> str:
+        desc = self._command_description(cmd)
+        if desc_max_len is not None:
+            desc = self._truncate(desc, desc_max_len)
+        if desc:
+            return f"- `/{cmd.name}`: {desc}"
+        return f"- `/{cmd.name}`"
+
+    def _format_listing_within_budget(self, commands: list, *, header: str) -> str:
+        """
+        在给定字符预算内渲染 skill listing。
+
+        逐级降级策略（对齐 CC 思路）：
+        1) 先尝试完整条目（每条已做 MAX_LISTING_DESC_CHARS 截断）；
+        2) 超预算时按“均摊描述长度”二次截断；
+        3) 若均摊长度过小，退化为 names-only；
+        4) 最后兜底：从尾部裁剪条目，保证绝不超预算。
+        """
+        if not commands:
+            return header
+        budget = max(self._get_char_budget(), len(header) + 1)
+        full_entries = [self._format_command_line(cmd) for cmd in commands]
+        full_text = header + "\n" + "\n".join(full_entries)
+        if len(full_text) <= budget:
+            return full_text
+
+        # 仅名称+固定前缀开销：`- `/{name}`: `
+        name_overhead = sum(len(f"- `/{cmd.name}`: ") for cmd in commands)
+        newline_overhead = max(len(commands) - 1, 0)
+        available_for_desc = budget - len(header) - 1 - name_overhead - newline_overhead
+        max_desc_len = available_for_desc // len(commands)
+
+        if max_desc_len < MIN_DESC_LENGTH:
+            names_only = [f"- `/{cmd.name}`" for cmd in commands]
+            return header + "\n" + "\n".join(names_only)
+
+        trimmed_entries = [
+            self._format_command_line(cmd, desc_max_len=max_desc_len) for cmd in commands
+        ]
+        trimmed_text = header + "\n" + "\n".join(trimmed_entries)
+        if len(trimmed_text) <= budget:
+            return trimmed_text
+
+        # 兜底：从末尾移除，保证不超预算
+        kept: list[str] = []
+        running_len = len(header)
+        for entry in trimmed_entries:
+            extra = 1 + len(entry)
+            if running_len + extra > budget:
+                break
+            kept.append(entry)
+            running_len += extra
+        return header + ("\n" + "\n".join(kept) if kept else "")

langchain_agentx/task_runtime/store/__init__.py

@@ -0,0 +1,6 @@
+"""Task record persistence implementations."""
+
+from .in_memory import InMemoryTaskStore
+from .sqlite_store import SqliteTaskStore
+
+__all__ = ["InMemoryTaskStore", "SqliteTaskStore"]