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

langchain_agentx/loop/subagent/orchestrator.py

@@ -0,0 +1,391 @@
+"""
+loop/subagent/orchestrator.py — SubagentOrchestrator 子代理启动编排
+
+职责：接管 AgentRuntimeTool.invoke 中的子代理启动逻辑：
+      异步决策 → 工具池组装 → 上下文派生 → run_subagent / register_background_agent 调用。
+在整体链路中的位置：AgentRuntimeTool.invoke() → SubagentOrchestrator.invoke_subagent()
+CC 对照：src/tools/AgentTool/AgentTool.tsx call() 中 runAgent / registerAsyncAgent 分支。
+当前裁剪范围：v1 三路异步决策 + plain/fork/coordinate 执行路径；
+      fork + worktree 时注入 CC 等价 ``buildWorktreeNotice`` user 消息（见 ``fork_worktree_notice``）。
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+import uuid
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from langchain_agentx.loop.runtime import RuntimeContextFactory, SubagentContextOverrides
+from langchain_agentx.loop.runtime.subagent_execution_paths import (
+    PreparedSubagentPaths,
+    SubagentExecutionPaths,
+)
+from langchain_agentx.loop.subagent.context import create_subagent_context
+from langchain_agentx.loop.subagent.prompt import enhance_system_prompt_with_env
+from langchain_agentx.utils.cwd import get_cwd, run_with_cwd_override
+from langchain_agentx.tools.agent.backend import assemble_tool_pool, should_run_async
+from langchain_agentx.loop.subagent.runner import (
+    BackgroundLaunchedResult,
+    _run_coroutine_sync,
+    run_subagent,
+    run_subagent_with_background_signal,
+)
+from langchain_agentx.loop.subagent.async_runner import register_background_agent
+from langchain_agentx.observability.logging import ObservabilityLoggerAdapter, build_log_context
+from langchain_agentx.workspace import resolve_agent_workspace_config
+
+if TYPE_CHECKING:
+    from langchain_agentx.loop.runtime import AgentLoopConfig
+    from langchain_agentx.tool_runtime.models import ToolExecutionContext
+    from langchain_agentx.tools.agent.models import AgentToolInput, AgentToolOutput
+    from langchain_agentx.tools.agent.registry.config import SubagentConfig
+
+logger = logging.getLogger(__name__)
+
+def _make_progress_handler(subagent_type: str, started_at: float):
+    """构造 on_progress 回调（2s hint 阈值 + stderr 单行覆写）。"""
+    import sys
+    hint_shown = False
+
+    def _on_progress(event: Any) -> None:
+        nonlocal hint_shown
+        if not hint_shown and time.monotonic() - started_at > 2.0:
+            hint_shown = True
+            print(
+                f"\r[Agent:{subagent_type}] task is running... (Ctrl+C to interrupt)",
+                file=sys.stderr,
+                flush=True,
+            )
+        if getattr(event, "summary", ""):
+            print(
+                f"\r[{subagent_type}] {event.summary:<80}",
+                file=sys.stderr,
+                end="",
+                flush=True,
+            )
+        if getattr(event, "type", "") == "completed":
+            print("", file=sys.stderr)
+
+    return _on_progress
+
+
+class SubagentOrchestrator:
+    """子代理启动编排器。
+
+    职责边界：
+    - 继承规则委托给 RuntimeContextFactory.derive()
+    - 工具池组装委托给 assemble_tool_pool()
+    - 执行委托给 run_subagent() / register_background_agent()
+    - 不承载 present / validate 等 RuntimeTool 生命周期钩子
+
+    CC 对照：AgentTool.tsx call() 中 runAgent / registerAsyncAgent 的分支逻辑。
+    """
+
+    def __init__(
+        self,
+        mode: str = "plain",
+        background_output_dir: str | None = None,
+    ) -> None:
+        self._mode = mode
+        self._background_output_dir = background_output_dir
+
+    def invoke_subagent(
+        self,
+        inp: "AgentToolInput",
+        ctx: "ToolExecutionContext",
+        subagent_config: "SubagentConfig",
+    ) -> "AgentToolOutput":
+        """执行子代理：派生上下文 → 组装工具池 → 按异步策略执行。
+
+        继承规则单点在 RuntimeContextFactory.derive()，不在此处散落。
+        """
+        from langchain_agentx.tools.agent.models import AgentToolOutput
+
+        log = self._build_logger(ctx)
+        child_agent_id = str(uuid.uuid4())
+        overrides, runtime_ctx, prepared = self._derive_runtime_context(
+            inp=inp,
+            ctx=ctx,
+            subagent_config=subagent_config,
+            child_agent_id=child_agent_id,
+        )
+        is_async = self._decide_async(inp=inp, ctx=ctx)
+
+        log.info(
+            "agent invoke mode=%s subagent_type=%s async=%s",
+            self._mode, inp.subagent_type or "general-purpose", is_async,
+        )
+
+        parent_registry = getattr(ctx, "tool_registry", None)
+        if parent_registry is None or not hasattr(parent_registry, "list"):
+            raise RuntimeError(
+                "tool_registry missing in ToolExecutionContext; "
+                "please construct the parent agent with ToolRuntimeLoader(loader=...)."
+            )
+        parent_loader = getattr(ctx, "tool_loader", None)
+        if parent_loader is None or not hasattr(parent_loader, "fork_with_tools"):
+            raise RuntimeError(
+                "tool_loader missing in ToolExecutionContext; "
+                "please construct the parent agent with ToolRuntimeLoader(loader=...)."
+            )
+
+        runtime_tools = list(parent_registry.list())
+        runtime_tools = assemble_tool_pool(runtime_tools, subagent_config, is_async=is_async)
+        allowed_tool_names: set[str] = {getattr(t, "name", "") for t in runtime_tools if getattr(t, "name", "")}
+        child_loader = parent_loader.fork_with_tools(runtime_tools)
+
+        system_prompt = enhance_system_prompt_with_env(
+            subagent_config.system_prompt_factory(),
+            runtime_ctx.cwd,
+        )
+
+        effective_cwd = runtime_ctx.cwd or get_cwd()
+        # CC：buildWorktreeNotice(getCwd(), …) 在子 cwd 覆盖生效之前取父工作目录
+        parent_notice_cwd = getattr(ctx, "cwd", None) or get_cwd()
+        inject_fork_wt = self._mode == "fork" and prepared.worktree_dir is not None
+        with run_with_cwd_override(effective_cwd):
+            output_dir = self._resolve_background_output_dir(runtime_ctx)
+            subagent_ctx = create_subagent_context(
+                parent_ctx=ctx,
+                task=inp.prompt,
+                subagent_type=inp.subagent_type or "general-purpose",
+                system_prompt=system_prompt,
+                max_steps=runtime_ctx.max_steps,
+                agent_depth=runtime_ctx.agent_depth,
+                isolation=overrides.isolation,
+                fork_from_parent=(self._mode == "fork"),
+                is_async=is_async,
+                model=runtime_ctx.model,
+                path_prep=prepared,
+                inject_fork_worktree_notice=inject_fork_wt,
+                fork_worktree_parent_cwd=parent_notice_cwd,
+                fork_worktree_path=prepared.worktree_dir,
+            )
+            # agent_id 由 RuntimeContextFactory 派生，同步到 subagent_ctx
+            subagent_ctx.agent_id = child_agent_id
+
+            _on_progress = _make_progress_handler(
+                inp.subagent_type or "general-purpose", time.monotonic()
+            )
+            os.makedirs(output_dir, exist_ok=True)
+
+            if is_async:
+                return self._launch_async_subagent(
+                    agent_output_cls=AgentToolOutput,
+                    subagent_ctx=subagent_ctx,
+                    loader=child_loader,
+                    model=runtime_ctx.model,
+                    description=inp.description,
+                    on_progress=_on_progress,
+                    parent_ctx=ctx,
+                    output_dir=output_dir,
+                )
+
+            background_signal = getattr(ctx, "background_signal", None)
+            if background_signal is not None:
+                result = self._run_with_background_signal(
+                    subagent_ctx=subagent_ctx,
+                    loader=child_loader,
+                    model=runtime_ctx.model,
+                    description=inp.description,
+                    on_progress=_on_progress,
+                    parent_ctx=ctx,
+                    background_signal=background_signal,
+                    allowed_tool_names=allowed_tool_names,
+                    output_dir=output_dir,
+                )
+                if isinstance(result, BackgroundLaunchedResult):
+                    output_file = os.path.join(
+                        output_dir, result.task_id, "output.txt"
+                    )
+                    log.info("agent switched to background task_id=%s", result.task_id)
+                    return AgentToolOutput(
+                        status="async_launched",
+                        content="",
+                        agent_id=result.agent_id,
+                        total_steps=0,
+                        terminal_reason="background_signal",
+                        task_id=result.task_id,
+                        output_file=output_file,
+                    )
+            else:
+                result = self._run_foreground_subagent(
+                    subagent_ctx=subagent_ctx,
+                    loader=child_loader,
+                    model=runtime_ctx.model,
+                    on_progress=_on_progress,
+                    allowed_tool_names=allowed_tool_names,
+                )
+
+        return AgentToolOutput(
+            status=result.status,
+            content=result.content,
+            agent_id=result.agent_id,
+            total_steps=result.total_steps,
+            terminal_reason=result.terminal_reason or None,
+            error_message=result.error_message or None,
+            output_file=getattr(result, "output_file", None),
+            child_run_id=getattr(result, "child_run_id", None),
+        )
+
+    def _build_logger(self, ctx: "ToolExecutionContext") -> ObservabilityLoggerAdapter:
+        return ObservabilityLoggerAdapter(
+            logger,
+            build_log_context(
+                session_id=getattr(ctx, "session_id", None),
+                tool_call_id=getattr(ctx, "tool_call_id", None),
+                agent_id=getattr(ctx, "agent_id", None),
+            ).as_extra(),
+        )
+
+    def _derive_runtime_context(
+        self,
+        *,
+        inp: "AgentToolInput",
+        ctx: "ToolExecutionContext",
+        subagent_config: "SubagentConfig",
+        child_agent_id: str,
+    ) -> tuple[SubagentContextOverrides, "AgentLoopConfig", PreparedSubagentPaths]:
+        overrides = SubagentContextOverrides(
+            model=inp.model or None,
+            isolation=inp.isolation,
+            cwd=inp.cwd or None,
+        )
+        prepared = SubagentExecutionPaths.prepare(parent_ctx=ctx, overrides=overrides)
+        runtime_ctx: AgentLoopConfig = RuntimeContextFactory.derive(
+            parent_ctx=ctx,
+            overrides=overrides,
+            subagent_config=subagent_config,
+            agent_id=child_agent_id,
+            subagent_effective_cwd=prepared.effective_cwd,
+        )
+        return overrides, runtime_ctx, prepared
+
+    def _decide_async(self, *, inp: "AgentToolInput", ctx: "ToolExecutionContext") -> bool:
+        is_coordinator = getattr(ctx, "is_coordinator", False)
+        is_fork_enabled = getattr(ctx, "is_fork_enabled", False)
+        if self._mode == "coordinate" and is_coordinator:
+            return True
+        if self._mode == "fork" and is_fork_enabled:
+            return True
+        return should_run_async(inp, ctx)
+
+    def _register_background_agent(
+        self,
+        *,
+        subagent_ctx: Any,
+        loader: Any,
+        model: Any,
+        description: str | None,
+        on_progress: Any,
+        parent_ctx: "ToolExecutionContext",
+        output_dir: str,
+    ) -> Any:
+        return register_background_agent(
+            ctx=subagent_ctx,
+            loader=loader,
+            model=model,
+            output_dir=output_dir,
+            description=description,
+            on_progress=on_progress,
+            parent_ctx=parent_ctx,
+        )
+
+    def _launch_async_subagent(
+        self,
+        *,
+        agent_output_cls: type[Any],
+        subagent_ctx: Any,
+        loader: Any,
+        model: Any,
+        description: str | None,
+        on_progress: Any,
+        parent_ctx: "ToolExecutionContext",
+        output_dir: str,
+    ) -> Any:
+        handle = self._register_background_agent(
+            subagent_ctx=subagent_ctx,
+            loader=loader,
+            model=model,
+            description=description,
+            on_progress=on_progress,
+            parent_ctx=parent_ctx,
+            output_dir=output_dir,
+        )
+        return agent_output_cls(
+            status="async_launched",
+            content="",
+            agent_id=handle.agent_id,
+            total_steps=0,
+            terminal_reason="background",
+            task_id=handle.task_id,
+            output_file=handle.output_file,
+        )
+
+    def _run_with_background_signal(
+        self,
+        *,
+        subagent_ctx: Any,
+        loader: Any,
+        model: Any,
+        description: str | None,
+        on_progress: Any,
+        parent_ctx: "ToolExecutionContext",
+        background_signal: Any,
+        allowed_tool_names: set[str],
+        output_dir: str,
+    ) -> Any:
+        def _register_from_signal(child_ctx: Any) -> str:
+            handle = self._register_background_agent(
+                subagent_ctx=child_ctx,
+                loader=loader,
+                model=model,
+                description=description,
+                on_progress=on_progress,
+                parent_ctx=parent_ctx,
+                output_dir=output_dir,
+            )
+            return handle.task_id
+
+        return _run_coroutine_sync(
+            run_subagent_with_background_signal(
+                ctx=subagent_ctx,
+                loader=loader,
+                model=model,
+                on_progress=on_progress,
+                background_signal=background_signal,
+                on_background_request=_register_from_signal,
+                allowed_tool_names=allowed_tool_names,
+            )
+        )
+
+    def _resolve_background_output_dir(self, runtime_ctx: "AgentLoopConfig") -> str:
+        if self._background_output_dir:
+            return self._background_output_dir
+        workspace_cfg = resolve_agent_workspace_config(
+            workspace_root=runtime_ctx.workspace_root or Path.cwd(),
+            agent_home=runtime_ctx.agent_home,
+        )
+        return str(workspace_cfg.tasks_dir)
+
+    def _run_foreground_subagent(
+        self,
+        *,
+        subagent_ctx: Any,
+        loader: Any,
+        model: Any,
+        on_progress: Any,
+        allowed_tool_names: set[str],
+    ) -> Any:
+        return _run_coroutine_sync(
+            run_subagent(
+                ctx=subagent_ctx,
+                loader=loader,
+                model=model,
+                on_progress=on_progress,
+                allowed_tool_names=allowed_tool_names,
+            )
+        )

langchain_agentx/loop/subagent/progress.py

@@ -0,0 +1,30 @@
+"""Subagent Progress Event 数据结构
+
+职责：进度事件载荷（Channel B）
+在整体链路中的位置：runner.py 构造 → AgentRuntimeTool.invoke() 的 on_progress 回调消费
+CC 对照：src/agent/subagent/progress.ts onProgress 回调参数类型
+当前裁剪范围：v1 基础事件类型，无 async 路径
+"""
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+@dataclass
+class SubagentProgressEvent:
+    """子 Agent 进度事件
+
+    type 枚举：
+    - tool_use: 工具调用开始
+    - tool_result: 工具调用结束
+    - model_step: 模型推理完成
+    - hint: 后台化提示（v2）
+    - completed: 子 Agent 完成
+    """
+    type: Literal["tool_use", "tool_result", "model_step", "hint", "completed"]
+    subagent_type: str = ""
+    agent_id: str = ""
+    step: int = 0
+    tool_name: str = ""
+    summary: str = ""
+    meta: dict = field(default_factory=dict)

langchain_agentx/loop/subagent/prompt.py

@@ -0,0 +1,52 @@
+"""
+loop/subagent/prompt.py — 子代理 system prompt 环境信息注入
+
+职责：enhance_system_prompt_with_env()，在子代理 base prompt 基础上追加
+      env 块（工作区根、进程 cwd、git、agent_home、builtin 总闸等）与行为 notes。
+在整体链路中的位置：SubagentOrchestrator.invoke_subagent() 调用（built-in 与 Markdown 子代理共用）。
+CC 对照：constants/prompts.ts computeEnvInfo + enhanceSystemPromptWithEnvDetails。
+"""
+
+from __future__ import annotations
+
+from langchain_agentx.utils.subprocess_text import default_text_subprocess_runner
+
+
+_AGENT_NOTES = """Notes:
+- Always use absolute file paths, never relative paths.
+- In your final response, share file paths (always absolute) relevant to the task."""
+
+
+def _is_git_repo(path: str) -> bool:
+    try:
+        runner = default_text_subprocess_runner()
+        result = runner.run(
+            ["git", "-C", path, "rev-parse", "--is-inside-work-tree"],
+            capture_output=True,
+            timeout=3,
+        )
+        return result.returncode == 0
+    except Exception:
+        return False
+
+
+def enhance_system_prompt_with_env(
+    base_prompt: str,
+    cwd: str | None,
+) -> str:
+    """在 base_prompt 基础上追加环境信息块与行为 notes。
+
+    cwd 为 None 时原样返回，不注入任何内容。
+    CC 对照：computeEnvInfo + enhanceSystemPromptWithEnvDetails 的组合。
+    """
+    if not cwd:
+        return base_prompt
+
+    is_git = _is_git_repo(cwd)
+    env_block = (
+        f"<env>\n"
+        f"Working directory: {cwd}\n"
+        f"Is directory a git repo: {'Yes' if is_git else 'No'}\n"
+        f"</env>"
+    )
+    return f"{base_prompt}\n\n{_AGENT_NOTES}\n\n{env_block}"