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

langchain_agentx/task_runtime/tasks/base/contracts.py

@@ -0,0 +1,24 @@
+"""
+task_runtime/tasks/base/contracts.py — 任务语义契约基类
+
+职责：
+    用不可变数据类描述「某一 TaskType 的终态集合与摘要前缀」，
+    与具体 ``TaskExecutor`` 解耦，便于文档化与静态检查。
+
+与 CC 对比：
+    CC 在 ``TaskStateBase`` / 各 task 的 ``type`` 判别式中分散语义；
+    本仓库用 ``TaskSemanticContract`` 收敛为可导入的单一事实来源（SSOT 子集）。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...core.types import TaskStatus, TaskType
+
+
+@dataclass(frozen=True)
+class TaskSemanticContract:
+    task_type: TaskType
+    terminal_statuses: tuple[TaskStatus, ...]
+    summary_prefix: str

langchain_agentx/task_runtime/tasks/custom/__init__.py

@@ -0,0 +1,7 @@
+"""CUSTOM 语义包（扩展任务类型）。"""
+
+from .executor import CustomTaskExecutor
+from .semantics import CUSTOM_SEMANTIC
+from .spec import CustomTaskInput
+
+__all__ = ["CustomTaskExecutor", "CUSTOM_SEMANTIC", "CustomTaskInput"]

langchain_agentx/task_runtime/tasks/custom/executor.py

@@ -0,0 +1,60 @@
+"""
+tasks/custom/executor.py — CUSTOM 执行器
+
+职责：
+    解析 ``CustomTaskInput`` 后按 ``payload.handler`` / ``metadata.custom_handler`` 分发；
+    未指定 handler 时回退为 ``CustomTaskNotificationFormatter`` 终态摘要。
+
+与 CC 对比：
+    CC 无独立 ``custom`` Task 类型；本枚举为扩展点，handler 名与 payload 由业务约定。
+"""
+
+from __future__ import annotations
+
+from ...core.interfaces import TaskExecutor
+from ...core.types import TaskExecutionResult, TaskStatus
+
+from .notification import CustomTaskNotificationFormatter
+from .spec import CustomTaskInput
+
+
+def _handler_name(record, parsed: CustomTaskInput) -> str | None:
+    pl = parsed.payload
+    if isinstance(pl, dict):
+        h = pl.get("handler")
+        if isinstance(h, str) and h.strip():
+            return h.strip().lower()
+    meta = record.metadata or {}
+    h2 = meta.get("custom_handler")
+    if isinstance(h2, str) and h2.strip():
+        return h2.strip().lower()
+    return None
+
+
+class CustomTaskExecutor(TaskExecutor):
+    def execute(self, record) -> TaskExecutionResult:
+        try:
+            parsed = CustomTaskInput.from_mapping(dict(record.input or {}))
+        except ValueError as e:
+            return TaskExecutionResult(status=TaskStatus.FAILED, summary=str(e))
+
+        name = _handler_name(record, parsed)
+        if name == "echo":
+            return TaskExecutionResult(
+                status=TaskStatus.COMPLETED,
+                summary=f"custom[echo]: {parsed.body}",
+            )
+        if name == "upper":
+            return TaskExecutionResult(
+                status=TaskStatus.COMPLETED,
+                summary=f"custom[upper]: {parsed.body.upper()}",
+            )
+        if name in ("fail", "failed"):
+            reason = ""
+            if isinstance(parsed.payload, dict):
+                reason = str(parsed.payload.get("reason") or "").strip()
+            summary = reason or "custom handler requested failure"
+            return TaskExecutionResult(status=TaskStatus.FAILED, summary=summary)
+
+        summary = CustomTaskNotificationFormatter.format_completion(body=parsed.body)
+        return TaskExecutionResult(status=TaskStatus.COMPLETED, summary=summary)

langchain_agentx/task_runtime/tasks/custom/notification.py

@@ -0,0 +1,7 @@
+"""tasks/custom/notification.py — 终态摘要（OOP）"""
+
+
+class CustomTaskNotificationFormatter:
+    @classmethod
+    def format_completion(cls, *, body: str) -> str:
+        return f"custom task completed: {body[:280]}"

langchain_agentx/task_runtime/tasks/custom/semantics.py

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

langchain_agentx/task_runtime/tasks/custom/spec.py

@@ -0,0 +1,33 @@
+"""
+tasks/custom/spec.py — CUSTOM 输入契约（OOP）
+
+职责：
+    扩展任务类型的最小结构化入口；业务侧应在 ``metadata`` 中标注 handler 版本。
+
+与 CC 对比：
+    CC ``types.ts`` 中未单独列 ``custom``；本仓库 ``TaskType.CUSTOM`` 对应「无法归入五类」
+    的扩展点，输入必须显式包含 ``message`` 或 ``payload`` 之一。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class CustomTaskInput:
+    body: str
+    payload: dict[str, Any]
+
+    @classmethod
+    def from_mapping(cls, raw: Mapping[str, Any]) -> CustomTaskInput:
+        msg = raw.get("message")
+        if isinstance(msg, str) and msg.strip():
+            return cls(body=msg.strip(), payload=dict(raw.get("payload") or {}))
+        pl = raw.get("payload")
+        if isinstance(pl, Mapping) and pl:
+            text = str(pl.get("message") or pl.get("summary") or "").strip()
+            if text:
+                return cls(body=text, payload=dict(pl))
+        raise ValueError("CUSTOM requires non-empty 'message' or payload with message/summary")

langchain_agentx/task_runtime/tasks/dream_task/__init__.py

@@ -0,0 +1,15 @@
+"""DREAM_TASK 语义包（CC ``DreamTask``）。"""
+
+from .executor import DreamTaskExecutor
+from .notification import DreamTaskNotificationFormatter
+from .semantics import DREAM_TASK_SEMANTIC
+from .spec import DreamTaskInput
+from .state import DreamTaskState
+
+__all__ = [
+    "DreamTaskExecutor",
+    "DreamTaskNotificationFormatter",
+    "DreamTaskInput",
+    "DreamTaskState",
+    "DREAM_TASK_SEMANTIC",
+]

langchain_agentx/task_runtime/tasks/dream_task/executor.py

@@ -0,0 +1,61 @@
+"""
+tasks/dream_task/executor.py — DREAM_TASK 执行器
+
+职责：
+    按 ``constraints.max_turns`` 驱动轻量 **phase / progress** 状态机（``starting`` →
+    ``updating`` → ``completed``），终态摘要由 ``DreamTaskNotificationFormatter`` 产出。
+
+与 CC 对比：
+    CC ``addDreamTurn`` / ``DreamTaskState`` 多轮 richer；本实现用同步循环模拟 turn，
+    真 multi-turn LLM 可在循环体内替换为异步调度（保持 ``DreamTaskState`` 更新语义）。
+"""
+
+from __future__ import annotations
+
+from ...core.interfaces import TaskExecutor
+from ...core.types import TaskExecutionResult, TaskStatus
+
+from .notification import DreamTaskNotificationFormatter
+from .spec import DreamTaskInput
+from .state import DreamTaskState
+
+
+def _clamp_turns(raw: object) -> int:
+    if raw is None:
+        return 1
+    try:
+        n = int(raw)
+    except (TypeError, ValueError):
+        return 1
+    return max(1, min(n, 48))
+
+
+class DreamTaskExecutor(TaskExecutor):
+    def execute(self, record) -> TaskExecutionResult:
+        try:
+            parsed = DreamTaskInput.from_mapping(dict(record.input or {}))
+        except ValueError as e:
+            return TaskExecutionResult(status=TaskStatus.FAILED, summary=str(e))
+
+        max_turns = _clamp_turns(parsed.constraints.get("max_turns", 1))
+        state = DreamTaskState()
+
+        for turn in range(max_turns):
+            if turn == 0:
+                state.phase = "starting"
+            else:
+                state.phase = "updating"
+            state.progress = (turn + 1) / float(max_turns)
+            state.latest_note = (
+                f"turn {turn + 1}/{max_turns} goal={parsed.goal[:120]!r}"
+            )
+
+        state.phase = "completed"
+        state.progress = 1.0
+        ctx_hint = ""
+        if parsed.context_snapshot:
+            ctx_hint = f" ctx_keys={list(parsed.context_snapshot.keys())[:8]}"
+        state.latest_note = f"dream finished{ctx_hint}"
+
+        summary = DreamTaskNotificationFormatter.build_summary(state)
+        return TaskExecutionResult(status=TaskStatus.COMPLETED, summary=summary)

langchain_agentx/task_runtime/tasks/dream_task/notification.py

@@ -0,0 +1,19 @@
+"""
+tasks/dream_task/notification.py — 进度/终态摘要（OOP）
+
+与 CC 对比：
+    CC ``DreamTaskState`` 含 ``turns``、``filesTouched``；本仓库 ``DreamTaskState``
+    为轻量占位，由 ``DreamTaskNotificationFormatter`` 生成可读摘要。
+"""
+
+from __future__ import annotations
+
+from .state import DreamTaskState
+
+
+class DreamTaskNotificationFormatter:
+    @classmethod
+    def build_summary(cls, state: DreamTaskState) -> str:
+        pct = int(max(0.0, min(1.0, state.progress)) * 100)
+        note = state.latest_note.strip() or "running"
+        return f"dream_task phase={state.phase} progress={pct}% note={note}"

langchain_agentx/task_runtime/tasks/dream_task/semantics.py

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

langchain_agentx/task_runtime/tasks/dream_task/spec.py

@@ -0,0 +1,35 @@
+"""
+tasks/dream_task/spec.py — DREAM_TASK 输入契约（OOP）
+
+职责：
+    约束 dream / 记忆整理类任务的 goal 与可选约束字典。
+
+与 CC 对比：
+    ``DreamTask/DreamTask.ts`` 中 ``DreamTaskState``（phase、turns 等）更丰富；
+    本仓库用 ``DreamTaskInput.from_mapping`` 表达最小可执行字段，状态机分期扩展。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class DreamTaskInput:
+    goal: str
+    constraints: dict[str, Any] = field(default_factory=dict)
+    context_snapshot: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_mapping(cls, raw: Mapping[str, Any]) -> DreamTaskInput:
+        goal = str(raw.get("goal") or "").strip()
+        if not goal:
+            raise ValueError("DREAM_TASK requires non-empty 'goal'")
+        cons = raw.get("constraints")
+        ctx = raw.get("context_snapshot")
+        return cls(
+            goal=goal,
+            constraints=dict(cons) if isinstance(cons, Mapping) else {},
+            context_snapshot=dict(ctx) if isinstance(ctx, Mapping) else {},
+        )

langchain_agentx/task_runtime/tasks/dream_task/state.py

@@ -0,0 +1,17 @@
+"""
+tasks/dream_task/state.py — 轻量状态占位
+
+与 CC 对比：
+    CC ``DreamPhase`` = starting | updating；此处用字符串 phase 占位。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class DreamTaskState:
+    phase: str = "starting"
+    progress: float = 0.0
+    latest_note: str = ""

langchain_agentx/task_runtime/tasks/in_process_teammate/__init__.py

@@ -0,0 +1,12 @@
+"""IN_PROCESS_TEAMMATE 语义包（CC ``InProcessTeammateTask``）。"""
+
+from .executor import InProcessTeammateExecutor
+from .semantics import IN_PROCESS_TEAMMATE_SEMANTIC
+from .spec import InProcessTeammateTaskInput, TeammateIdentity
+
+__all__ = [
+    "InProcessTeammateExecutor",
+    "IN_PROCESS_TEAMMATE_SEMANTIC",
+    "InProcessTeammateTaskInput",
+    "TeammateIdentity",
+]

langchain_agentx/task_runtime/tasks/in_process_teammate/executor.py

@@ -0,0 +1,36 @@
+"""
+tasks/in_process_teammate/executor.py — IN_PROCESS_TEAMMATE 执行器
+
+职责：
+    校验 identity + prompt，按 ``plan_mode_required`` 分支生成 CC 对齐的终态摘要
+    （协作者 pill / transcript 文案骨架）。
+
+与 CC 对比：
+    CC ``InProcessTeammateTask`` 含 ``runAgent``、权限与 plan 模式；此处将 **plan_mode**
+    显式反映在通知字符串中，执行体仍保持进程内同步（不触碰主线程 messages）。
+"""
+
+from __future__ import annotations
+
+from ...core.interfaces import TaskExecutor
+from ...core.types import TaskExecutionResult, TaskStatus
+
+from .notification import InProcessTeammateNotificationFormatter
+from .spec import InProcessTeammateTaskInput
+
+
+class InProcessTeammateExecutor(TaskExecutor):
+    def execute(self, record) -> TaskExecutionResult:
+        try:
+            parsed = InProcessTeammateTaskInput.from_mapping(dict(record.input or {}))
+        except ValueError as e:
+            return TaskExecutionResult(status=TaskStatus.FAILED, summary=str(e))
+        i = parsed.identity
+        summary = InProcessTeammateNotificationFormatter.format_completion(
+            agent_name=i.agent_name,
+            team_name=i.team_name,
+            prompt=parsed.prompt,
+            plan_mode_required=i.plan_mode_required,
+            parent_session_id=i.parent_session_id,
+        )
+        return TaskExecutionResult(status=TaskStatus.COMPLETED, summary=summary)

langchain_agentx/task_runtime/tasks/in_process_teammate/notification.py

@@ -0,0 +1,25 @@
+"""
+tasks/in_process_teammate/notification.py — 终态摘要（OOP）
+
+与 CC 对比：
+    CC 协作者任务在 UI pill / transcript 中展示 identity + 进度；
+    此处仅格式化完成摘要字符串。
+"""
+
+
+class InProcessTeammateNotificationFormatter:
+    @classmethod
+    def format_completion(
+        cls,
+        *,
+        agent_name: str,
+        team_name: str,
+        prompt: str,
+        plan_mode_required: bool = False,
+        parent_session_id: str = "",
+    ) -> str:
+        excerpt = prompt[:160]
+        base = f"Teammate [{agent_name}@{team_name}] completed: {excerpt}"
+        sess = f" parent_session={parent_session_id}" if parent_session_id else ""
+        plan = " [plan_mode=required]" if plan_mode_required else ""
+        return f"{base}{sess}{plan}"

langchain_agentx/task_runtime/tasks/in_process_teammate/semantics.py

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

langchain_agentx/task_runtime/tasks/in_process_teammate/spec.py

@@ -0,0 +1,63 @@
+"""
+tasks/in_process_teammate/spec.py — IN_PROCESS_TEAMMATE 输入契约（OOP）
+
+职责：
+    校验 ``identity`` 子对象与 ``prompt``；对齐 CC 持久化结构的最小字段集。
+
+与 CC 对比：
+    ``InProcessTeammateTask/types.ts`` 中 ``TeammateIdentity`` + ``prompt``；
+    本仓库用 ``TeammateIdentity.from_mapping`` / ``InProcessTeammateTaskInput.from_mapping``
+    表达，不包含 ``AbortController`` 等仅运行时字段。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class TeammateIdentity:
+    agent_id: str
+    agent_name: str
+    team_name: str
+    parent_session_id: str
+    plan_mode_required: bool = False
+
+    @classmethod
+    def from_mapping(cls, raw: Mapping[str, Any]) -> TeammateIdentity:
+        return cls(
+            agent_id=str(raw.get("agent_id") or "").strip(),
+            agent_name=str(raw.get("agent_name") or "").strip(),
+            team_name=str(raw.get("team_name") or "").strip(),
+            parent_session_id=str(raw.get("parent_session_id") or "").strip(),
+            plan_mode_required=bool(raw.get("plan_mode_required", False)),
+        )
+
+    def validate(self) -> None:
+        for name, val in (
+            ("agent_id", self.agent_id),
+            ("agent_name", self.agent_name),
+            ("team_name", self.team_name),
+            ("parent_session_id", self.parent_session_id),
+        ):
+            if not val:
+                raise ValueError(f"identity.{name} is required")
+
+
+@dataclass(frozen=True)
+class InProcessTeammateTaskInput:
+    identity: TeammateIdentity
+    prompt: str
+
+    @classmethod
+    def from_mapping(cls, raw: Mapping[str, Any]) -> InProcessTeammateTaskInput:
+        ident_raw = raw.get("identity")
+        if not isinstance(ident_raw, Mapping):
+            raise ValueError("IN_PROCESS_TEAMMATE requires mapping 'identity'")
+        identity = TeammateIdentity.from_mapping(ident_raw)
+        identity.validate()
+        prompt = str(raw.get("prompt") or "").strip()
+        if not prompt:
+            raise ValueError("IN_PROCESS_TEAMMATE requires non-empty 'prompt'")
+        return cls(identity=identity, prompt=prompt)

langchain_agentx/task_runtime/tasks/local_agent/__init__.py

@@ -0,0 +1,14 @@
+"""LOCAL_AGENT 语义包（CC ``LocalAgentTask`` / ``LocalMainSessionTask``）。"""
+
+from .executor import LocalAgentExecutor
+from .runner import DefaultLocalAgentRunner, LocalAgentRunner
+from .semantics import LOCAL_AGENT_SEMANTIC
+from .spec import LocalAgentTaskInput
+
+__all__ = [
+    "DefaultLocalAgentRunner",
+    "LocalAgentExecutor",
+    "LocalAgentRunner",
+    "LOCAL_AGENT_SEMANTIC",
+    "LocalAgentTaskInput",
+]

langchain_agentx/task_runtime/tasks/local_agent/executor.py

@@ -0,0 +1,33 @@
+"""
+tasks/local_agent/executor.py — LOCAL_AGENT 执行器
+
+职责：
+    解析输入并委托 ``LocalAgentRunner``；默认 ``DefaultLocalAgentRunner`` 为 CC 对齐的
+    **单轮**终态路径。生产环境注入自定义 runner（子图 ``invoke`` / 线程池）即可。
+
+与 CC 对比：
+    CC 在 ``LocalAgentTask`` 内驱动完整 agent loop；本类不内置 loop，仅保证
+    ``TaskRuntime.spawn → run_task → mark_terminal`` 与 runner 契约稳定。
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ...core.interfaces import TaskExecutor
+from ...core.types import TaskExecutionResult, TaskStatus
+
+from .runner import DefaultLocalAgentRunner, LocalAgentRunner
+from .spec import LocalAgentTaskInput
+
+
+class LocalAgentExecutor(TaskExecutor):
+    def __init__(self, runner: Optional[LocalAgentRunner] = None) -> None:
+        self._runner: LocalAgentRunner = runner or DefaultLocalAgentRunner()
+
+    def execute(self, record) -> TaskExecutionResult:
+        try:
+            parsed = LocalAgentTaskInput.from_mapping(dict(record.input or {}))
+        except ValueError as e:
+            return TaskExecutionResult(status=TaskStatus.FAILED, summary=str(e))
+        return self._runner(record, parsed)

langchain_agentx/task_runtime/tasks/local_agent/notification.py

@@ -0,0 +1,21 @@
+"""
+tasks/local_agent/notification.py — 终态摘要（OOP）
+
+与 CC 对比：
+    CC ``LocalAgentTask`` 使用 ``AgentProgress``、token 累计等；
+    此处仅提供最小可测的摘要拼接类。
+"""
+
+
+class LocalAgentNotificationFormatter:
+    @classmethod
+    def format_completion(
+        cls,
+        *,
+        prompt_excerpt: str,
+        agent_label: str | None,
+        task_id: str | None = None,
+    ) -> str:
+        label = f" [{agent_label}]" if agent_label else ""
+        tid = f" id={task_id}" if task_id else ""
+        return f"Local agent task completed{label}{tid}: {prompt_excerpt[:200]}"

langchain_agentx/task_runtime/tasks/local_agent/runner.py

@@ -0,0 +1,43 @@
+"""
+tasks/local_agent/runner.py — LOCAL_AGENT 执行体（CC LocalAgentTask 单轮路径）
+
+职责：
+    将「解析后的输入 → TaskExecutionResult」从 Executor 中抽出，便于注入真实
+    **子图 invoke / 线程化 runner**（生产），默认实现保持 **无外部依赖** 的可测单轮摘要。
+
+与 CC 对比：
+    CC ``LocalAgentTask`` 内嵌完整 agent loop；此处 ``DefaultLocalAgentRunner`` 仅产出
+    与 ``LocalAgentNotificationFormatter`` 一致的终态摘要。接入 LangGraph 时实现
+    ``LocalAgentRunner`` 协议并传入 ``LocalAgentExecutor(runner=...)`` 即可。
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from ...core.types import TaskExecutionResult, TaskRecord, TaskStatus
+from .notification import LocalAgentNotificationFormatter
+from .spec import LocalAgentTaskInput
+
+
+@runtime_checkable
+class LocalAgentRunner(Protocol):
+    def __call__(
+        self, record: TaskRecord, parsed: LocalAgentTaskInput
+    ) -> TaskExecutionResult:
+        """由调用方实现：可同步调用子图或包装异步结果。"""
+        ...
+
+
+class DefaultLocalAgentRunner:
+    """默认单轮 runner：结构化终态摘要（含 ``task_id`` 便于观测对齐 CC 轨迹）。"""
+
+    def __call__(
+        self, record: TaskRecord, parsed: LocalAgentTaskInput
+    ) -> TaskExecutionResult:
+        summary = LocalAgentNotificationFormatter.format_completion(
+            prompt_excerpt=parsed.prompt,
+            agent_label=parsed.agent_label,
+            task_id=record.task_id,
+        )
+        return TaskExecutionResult(status=TaskStatus.COMPLETED, summary=summary)

langchain_agentx/task_runtime/tasks/local_agent/semantics.py

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

langchain_agentx/task_runtime/tasks/local_agent/spec.py

@@ -0,0 +1,31 @@
+"""
+tasks/local_agent/spec.py — LOCAL_AGENT 输入契约（OOP）
+
+职责：
+    解析子 agent / 后台会话类任务的输入；失败抛 ``ValueError``。
+
+与 CC 对比：
+    ``LocalAgentTask.tsx``、``LocalMainSessionTask.ts`` 使用更丰富的
+    AgentDefinition / 进度追踪；本仓库用 ``LocalAgentTaskInput.from_mapping``
+    表达最小可执行契约，真子图/长会话在 executor 内分期替换实现。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class LocalAgentTaskInput:
+    prompt: str
+    agent_label: str | None = None
+
+    @classmethod
+    def from_mapping(cls, raw: Mapping[str, Any]) -> LocalAgentTaskInput:
+        prompt = str(raw.get("prompt") or "").strip()
+        if not prompt:
+            raise ValueError("LOCAL_AGENT requires non-empty 'prompt'")
+        label = raw.get("agent_label")
+        agent_label = str(label).strip() if label not in (None, "") else None
+        return cls(prompt=prompt, agent_label=agent_label)

langchain_agentx/task_runtime/tasks/local_bash/__init__.py

@@ -0,0 +1,13 @@
+"""LOCAL_BASH 语义包（CC ``LocalShellTask``）。"""
+
+from .executor import LocalBashExecutor
+from .notification import LocalBashNotificationFormatter
+from .semantics import LOCAL_BASH_SEMANTIC
+from .spec import LocalBashTaskInput
+
+__all__ = [
+    "LocalBashExecutor",
+    "LOCAL_BASH_SEMANTIC",
+    "LocalBashNotificationFormatter",
+    "LocalBashTaskInput",
+]