deep-agent-cli 0.1.0__py3-none-any.whl

agent/session_runtime.py

@@ -0,0 +1,209 @@
+"""Session ownership: which persisted thread this runner may write, and its lease.
+
+The runtime owns the thread lease, the switch bookkeeping and the session
+catalog metadata. It never touches the graph — loading snapshots and rebuilding
+models stay with AgentRunner, which coordinates through these primitives.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from threading import Event
+from typing import Any, Callable
+from uuid import uuid4
+
+from agent.config import Settings
+from agent.middleware.recovery import RecoveryContext
+from agent.permission import (
+    PermissionMode,
+    allow_mode_available,
+    parse_permission_mode,
+)
+from agent.session import SessionInfo, SessionStore, StopReason
+from agent.session_lock import (
+    InProcessSessionLease,
+    InProcessSessionLockManager,
+    SessionLease,
+    SessionLockBusyError,
+)
+
+SessionLeaseLike = SessionLease | InProcessSessionLease
+
+
+@dataclass(frozen=True)
+class RestorePlan:
+    """Model and permission a target thread should run with after a switch."""
+
+    model_id: str
+    permission_mode: PermissionMode
+    notices: tuple[str, ...] = ()
+
+
+class SessionRuntime:
+    """Lease lifecycle plus catalog metadata for one runner's session."""
+
+    def __init__(
+        self,
+        *,
+        session_store: SessionStore | None,
+        checkpointer: Any | None,
+        settings: Settings | None,
+    ) -> None:
+        self._store = session_store
+        self._settings = settings
+        self._in_process_locks = (
+            None if session_store is not None else InProcessSessionLockManager(checkpointer)
+        )
+        self._thread_id: str | None = None
+        self._lease: SessionLeaseLike | None = None
+        self._pending_switch: str | None = None
+        self._abort_wait = Event()
+
+    @property
+    def thread_id(self) -> str | None:
+        return self._thread_id
+
+    @property
+    def lease(self) -> SessionLeaseLike | None:
+        return self._lease
+
+    @property
+    def pending_switch(self) -> str | None:
+        return self._pending_switch
+
+    def owns(self, thread_id: str) -> bool:
+        return self._lease is not None and self._lease.thread_id == thread_id
+
+    def acquire_initial(
+        self, thread_id: str | None, *, model_id: str, permission_mode: str,
+    ) -> str:
+        """Resolve or create the first thread, then take its lease."""
+        if self._store is None:
+            target = thread_id or f"cli-{uuid4()}"
+        elif thread_id is None:
+            info = self._store.create_session(model_id=model_id, permission_mode=permission_mode)
+            target = info.id
+        else:
+            if self._store.get(thread_id) is None:
+                self._store.create_session(
+                    session_id=thread_id, model_id=model_id, permission_mode=permission_mode,
+                )
+            target = thread_id
+        lease = self.try_acquire(target)
+        if lease is None:
+            raise SessionLockBusyError(f"Session {target} is already open in another window")
+        self._thread_id = target
+        self._lease = lease
+        return target
+
+    def try_acquire(self, thread_id: str) -> SessionLeaseLike | None:
+        if self._store is not None:
+            return self._store.try_acquire_session(thread_id)
+        assert self._in_process_locks is not None
+        return self._in_process_locks.try_acquire(thread_id)
+
+    def wait_acquire(
+        self, thread_id: str, *, cancelled: Callable[[], bool] | None = None,
+    ) -> SessionLeaseLike | None:
+        def combined() -> bool:
+            return self._abort_wait.is_set() or (cancelled is not None and cancelled())
+
+        if self._store is not None:
+            return self._store.wait_acquire_session(thread_id, cancelled=combined)
+        assert self._in_process_locks is not None
+        return self._in_process_locks.wait_acquire(thread_id, cancelled=combined)
+
+    def adopt(self, thread_id: str, lease: SessionLeaseLike) -> None:
+        """Bind a freshly acquired target and drop the previous lease."""
+        previous = self._lease
+        self._thread_id = thread_id
+        self._lease = lease
+        self._pending_switch = None
+        if previous is not None:
+            previous.release()
+
+    def adopt_new(self, thread_id: str) -> None:
+        """Take over a thread this runner just created."""
+        lease = self.try_acquire(thread_id)
+        if lease is None:
+            raise SessionLockBusyError(f"Session {thread_id} is already open in another window")
+        self.adopt(thread_id, lease)
+
+    def bind(self, thread_id: str) -> None:
+        """Point at a thread whose lease is already held (A→A reload)."""
+        self._thread_id = thread_id
+        self._pending_switch = None
+
+    def detach_for_wait(self, target_id: str) -> None:
+        """Release the current lease and refuse operations while waiting."""
+        lease = self._lease
+        self._lease = None
+        if lease is not None:
+            lease.release()
+        self._pending_switch = target_id
+
+    def clear_pending(self) -> None:
+        self._pending_switch = None
+
+    def release(self) -> None:
+        lease = self._lease
+        self._lease = None
+        if lease is not None:
+            lease.release()
+
+    def abort_wait(self) -> None:
+        self._abort_wait.set()
+
+    def close(self) -> None:
+        self._abort_wait.set()
+        self.release()
+
+    def list_sessions(self, *, limit: int = 50) -> list[SessionInfo]:
+        if self._store is None:
+            return []
+        return self._store.list_sessions(limit=limit)
+
+    def resolve(self, session_id: str) -> SessionInfo | None:
+        if self._store is None:
+            return None
+        return self._store.resolve_prefix(session_id) or self._store.get(session_id)
+
+    def get(self, session_id: str) -> SessionInfo | None:
+        if self._store is None:
+            return None
+        return self._store.get(session_id)
+
+    def thread_has_checkpoint(self, thread_id: str) -> bool:
+        if self._store is None:
+            return False
+        return self._store.checkpointer.get_tuple(
+            {"configurable": {"thread_id": thread_id}}
+        ) is not None
+
+    def restore_plan(self, info: SessionInfo, *, execution_mode: Any) -> RestorePlan:
+        """Decide which model and permission the target thread should run with."""
+        notices: list[str] = []
+        profile = self._settings.active_profile if self._settings is not None else None
+        if self._settings is not None and info.model_id:
+            try:
+                profile = self._settings.get_profile(info.model_id)
+            except KeyError:
+                notices.append(f"Saved model {info.model_id} is unavailable; using {profile.id}.")
+        mode = parse_permission_mode(info.permission_mode or "ask") or PermissionMode.ASK
+        if mode is PermissionMode.ALLOW and not allow_mode_available(execution_mode):
+            mode = PermissionMode.ASK
+            notices.append("Saved allow permission is unavailable here; using ask.")
+        return RestorePlan(
+            model_id=profile.id if profile is not None else "",
+            permission_mode=mode,
+            notices=tuple(notices),
+        )
+
+    def recovery_context(
+        self, info: SessionInfo, *, has_checkpoint: bool, interrupt_active: bool,
+    ) -> RecoveryContext | None:
+        needs_recovery = info.last_run_status in {StopReason.ABORTED, StopReason.ERROR} or (
+            info.last_run_status is StopReason.PENDING and has_checkpoint
+        )
+        if needs_recovery and not interrupt_active:
+            return RecoveryContext.for_stop_reason(info.last_run_status)
+        return None

agent/stream.py

@@ -0,0 +1,168 @@
+# Token-level streaming for reasoning / assistant via LangChain callbacks.
+# ChatOpenAI(..., streaming=True) emits AIMessageChunk; this splits think vs visible text.
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from langchain_core.callbacks import BaseCallbackHandler
+from langchain_core.messages import AIMessageChunk, BaseMessage
+
+DeltaHandler = Callable[[str, str], None]
+
+
+def message_text(message: BaseMessage) -> str:
+    text = getattr(message, "text", None)
+    if isinstance(text, str) and text:
+        return text
+    content = message.content
+    if isinstance(content, str):
+        return content
+    parts: list[str] = []
+    for block in content if isinstance(content, list) else []:
+        if isinstance(block, dict) and block.get("type") == "text":
+            parts.append(str(block.get("text", "")))
+        elif isinstance(block, str):
+            parts.append(block)
+    return "".join(parts)
+
+
+def _split_think(text: str) -> tuple[str, str]:
+    """Split complete or streaming think tags without exposing partial tags."""
+    visible: list[str] = []
+    reasoning: list[str] = []
+    lower = text.lower()
+    cursor = 0
+    while (start := lower.find("<think>", cursor)) >= 0:
+        visible.append(_without_partial_tag(text[cursor:start]))
+        end = lower.find("</think>", start + len("<think>"))
+        if end < 0:
+            reasoning.append(_without_partial_tag(text[start + len("<think>"):]))
+            return "".join(visible), "".join(reasoning)
+        reasoning.append(text[start + len("<think>"):end])
+        cursor = end + len("</think>")
+    visible.append(_without_partial_tag(text[cursor:]))
+    return "".join(visible), "".join(reasoning)
+
+
+def _without_partial_tag(text: str) -> str:
+    marker = text.rfind("<")
+    if marker >= 0 and any(
+        tag.startswith(text[marker:].lower()) for tag in ("<think>", "</think>")
+    ):
+        return text[:marker]
+    return text
+
+
+def reasoning_text(message: BaseMessage) -> str:
+    extra = getattr(message, "additional_kwargs", None) or {}
+    for key in ("reasoning_content", "reasoning", "thinking", "reasoning_summary"):
+        value = extra.get(key)
+        if isinstance(value, str) and value:
+            return value
+    meta = getattr(message, "response_metadata", None) or {}
+    for key in ("reasoning_content", "reasoning", "thinking"):
+        value = meta.get(key)
+        if isinstance(value, str) and value:
+            return value
+    content = message.content
+    parts: list[str] = []
+    for block in content if isinstance(content, list) else []:
+        if not isinstance(block, dict):
+            continue
+        if str(block.get("type") or "") not in {"reasoning", "thinking"}:
+            continue
+        summary = block.get("summary")
+        if isinstance(summary, list):
+            for item in summary:
+                if isinstance(item, dict):
+                    parts.append(str(item.get("text") or ""))
+                elif item:
+                    parts.append(str(item))
+        parts.append(str(block.get("text") or block.get("reasoning") or block.get("reasoning_content") or ""))
+    if parts:
+        return "".join(parts)
+    return _split_think(message_text(message))[1]
+
+
+def visible_text(message: BaseMessage) -> str:
+    return _split_think(message_text(message))[0]
+
+
+def _chunk_message(chunk: Any) -> BaseMessage | None:
+    if chunk is None:
+        return None
+    if isinstance(chunk, BaseMessage):
+        return chunk
+    message = getattr(chunk, "message", None)
+    return message if isinstance(message, BaseMessage) else None
+
+
+class StreamDeltaCallback(BaseCallbackHandler):
+    """LangChain token callback → on_delta("reasoning"|"assistant", cumulative_text)."""
+
+    def __init__(
+        self,
+        on_delta: DeltaHandler,
+        *,
+        on_reasoning: Callable[[str], None] | None = None,
+        on_assistant: Callable[[str], None] | None = None,
+        on_start: Callable[[], None] | None = None,
+        on_end: Callable[[str, str], None] | None = None,
+    ) -> None:
+        super().__init__()
+        self._on_delta = on_delta
+        self._on_reasoning = on_reasoning
+        self._on_assistant = on_assistant
+        self._on_start = on_start
+        self._on_end = on_end
+        self._assistant = ""
+        self._reasoning = ""
+        self._message: AIMessageChunk | None = None
+        self._raw_text = ""
+
+    def on_llm_start(self, *args: Any, **kwargs: Any) -> None:
+        self._assistant = ""
+        self._reasoning = ""
+        self._message = None
+        self._raw_text = ""
+        if self._on_start:
+            self._on_start()
+
+    def on_llm_new_token(self, token: str, *, chunk: Any = None, **kwargs: Any) -> None:
+        message = _chunk_message(chunk)
+        if isinstance(message, AIMessageChunk):
+            self._message = message if self._message is None else self._message + message
+            visible = visible_text(self._message)
+            reasoning = reasoning_text(self._message)
+        else:
+            self._raw_text += token
+            visible, reasoning = _split_think(self._raw_text)
+        if reasoning != self._reasoning:
+            self._reasoning = reasoning
+            self._on_delta("reasoning", reasoning)
+            if self._on_reasoning:
+                self._on_reasoning(reasoning)
+        if visible != self._assistant:
+            self._assistant = visible
+            self._on_delta("assistant", visible)
+            if self._on_assistant:
+                self._on_assistant(visible)
+
+    def on_llm_end(self, *args: Any, **kwargs: Any) -> None:
+        if self._on_end:
+            self._on_end(self._assistant, self._reasoning)
+        self._assistant = ""
+        self._reasoning = ""
+
+
+def merge_stream_callbacks(config: dict[str, Any], callback: BaseCallbackHandler) -> dict[str, Any]:
+    merged = dict(config)
+    existing = merged.get("callbacks")
+    if isinstance(existing, list):
+        merged["callbacks"] = [*existing, callback]
+    elif existing:
+        merged["callbacks"] = [existing, callback]
+    else:
+        merged["callbacks"] = [callback]
+    return merged

agent/tools/__init__.py

@@ -0,0 +1,9 @@
+from agent.tools.examples import build_example_tools
+from agent.tools.execute import build_execute_tool
+from agent.tools.human_input import build_human_input_tools
+
+__all__ = [
+    "build_example_tools",
+    "build_execute_tool",
+    "build_human_input_tools",
+]

agent/tools/examples.py

@@ -0,0 +1,30 @@
+# Optional documentation lookup example. It is not part of the default agent.
+from langchain_core.tools import BaseTool, StructuredTool
+
+DOCS = {
+    "deep-agent": "Deep Agents 以 create_deep_agent() 装配 LangGraph 图，中间件负责文件系统、HITL、Skills 与重试。",
+    "middleware": "模板默认栈：PauseGate → ModelRetry → Filesystem。",
+    "hitl": "interrupt_on 标记的工具会在执行前暂停，等待 approve / reject。",
+}
+
+
+def lookup_docs(query: str) -> str:
+    """Search local documentation. ALLOW — runs immediately without confirmation."""
+    key = (query or "").strip().lower()
+    for name, text in DOCS.items():
+        if name in key or key in name:
+            return text
+    return "未找到文档。可检索：deep-agent、middleware、hitl。"
+
+
+def build_example_tools() -> list[BaseTool]:
+    return [
+        StructuredTool.from_function(
+            func=lookup_docs,
+            name="lookup_docs",
+            description=(
+                "检索本地文档。参数 query 为关键词（deep-agent / middleware / hitl）。"
+                "该工具可直接执行，不需要人工确认。"
+            ),
+        ),
+    ]

agent/tools/execute.py

@@ -0,0 +1,73 @@
+"""Local execute tool with optional NETWORK capability declaration."""
+from __future__ import annotations
+
+from deepagents.backends.protocol import SandboxBackendProtocol
+from langchain_core.tools import BaseTool, StructuredTool
+from agent.network import reset_execute_network, set_execute_network
+
+_ASK_DESCRIPTION = (
+    "Run a shell command inside the sandbox workspace (/workspace). "
+    "Defaults to no network. Under permission ask every execute needs "
+    "approval. network=true grants host network access, including localhost "
+    "and LAN addresses, for this command. "
+    "Prefer ls/read_file/glob/grep/write_file for filesystem work."
+)
+_ALLOW_DESCRIPTION = (
+    "Run a shell command inside the sandbox workspace (/workspace). "
+    "Permission allow mode: commands run without approval and host network "
+    "(internet, localhost, LAN) is enabled by default for every call. "
+    "Prefer ls/read_file/glob/grep/write_file for filesystem work."
+)
+
+
+def build_execute_tool(
+    backend: SandboxBackendProtocol,
+    *,
+    network_by_default: bool = False,
+) -> BaseTool:
+    """Shell execute bound to a sandbox backend.
+
+    ``network=True`` shares the host network namespace for this command.
+    ``network_by_default=True`` (permission mode allow) opens host network
+    for every call; a per-call ``network=false`` cannot turn it off.
+    """
+
+    def execute(
+        command: str,
+        timeout: int | None = None,
+        network: bool = False,
+    ) -> tuple[str, dict[str, object]]:
+        token = set_execute_network(network or network_by_default)
+        try:
+            if timeout is not None:
+                response = backend.execute(command, timeout=timeout)
+            else:
+                response = backend.execute(command)
+        finally:
+            reset_execute_network(token)
+        output = response.output or ""
+        if response.exit_code not in (0, None):
+            suffix = f"\n\nExit code: {response.exit_code}"
+            if suffix.strip() not in output:
+                output = f"{output.rstrip()}{suffix}"
+        if response.truncated:
+            marker = "\n\n[output truncated]"
+            if "[Output truncated: showing " not in output and marker not in output:
+                output = f"{output.rstrip()}{marker}"
+        artifact: dict[str, object] = {
+            "exit_code": response.exit_code,
+            "truncated": response.truncated,
+            "host_log_path": getattr(response, "host_log_path", None),
+            "agent_log_path": getattr(response, "agent_log_path", None),
+            "log_error": getattr(response, "log_error", None),
+            "termination_reason": getattr(response, "termination_reason", None),
+            "max_output_bytes": getattr(response, "max_output_bytes", None),
+        }
+        return output, artifact
+
+    return StructuredTool.from_function(
+        func=execute,
+        name="execute",
+        response_format="content_and_artifact",
+        description=_ALLOW_DESCRIPTION if network_by_default else _ASK_DESCRIPTION,
+    )

agent/tools/human_input.py

@@ -0,0 +1,170 @@
+# request_human_input — local LangGraph interrupt tool.
+# The tool body only builds a Semantic Interaction Schema and calls interrupt().
+# Resume hands the human's values back to the agent. No side effects before interrupt().
+from __future__ import annotations
+
+import json
+from typing import Any
+from uuid import uuid4
+
+from langchain_core.tools import BaseTool, StructuredTool
+from langgraph.types import interrupt
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field, field_validator
+
+from agent.tools.human_interaction import (
+    FIELD_TYPES,
+    INTERACTION_TYPES,
+    FieldType,
+    InteractionType,
+    normalize_interaction_request,
+    resume_values,
+)
+
+
+REQUEST_TOOL_NAME = "request_human_input"
+
+
+class FieldOption(BaseModel):
+    """single_select / multi_select 的一条候选项。"""
+
+    model_config = ConfigDict(extra="ignore")
+
+    value: str = Field(
+        default="",
+        description="选项值，用户选中后按这个值回传",
+        validation_alias=AliasChoices("value", "id"),
+    )
+    label: str = Field(default="", description="展示给用户的选项文案")
+    description: str = Field(default="", description="选项补充说明，可留空")
+
+
+class FieldSpec(BaseModel):
+    """一个待用户填写的字段。只声明交互语义，不指定前端组件。"""
+
+    model_config = ConfigDict(extra="ignore")
+
+    id: str = Field(default="", description="字段 id，用户的回答按这个 key 回传")
+    type: FieldType = Field(default="text", description="字段类型")
+    label: str = Field(default="", description="字段标题")
+    required: bool = Field(default=False, description="是否必须回答")
+    placeholder: str = Field(default="", description="输入框占位提示，可留空")
+    options: list[FieldOption] = Field(
+        default_factory=list,
+        description="single_select / multi_select 的候选项，其他类型留空数组",
+    )
+
+    @field_validator("type", mode="before")
+    @classmethod
+    def _lenient_type(cls, value: Any) -> str:
+        text = str(value or "").strip().lower()
+        return text if text in FIELD_TYPES else "text"
+
+
+class Recommendation(BaseModel):
+    """推荐答案。value 对应某个 field 的选项值或建议填写的内容。"""
+
+    model_config = ConfigDict(extra="ignore")
+
+    value: str = Field(default="", description="推荐选中或填写的内容")
+    reason: str = Field(default="", description="推荐理由，可留空")
+
+
+class HumanInputArgs(BaseModel):
+    """request_human_input 的参数。fields / recommendation / impact 必须是原生 JSON 结构。"""
+
+    model_config = ConfigDict(extra="ignore")
+
+    reason: str = Field(description="为什么必须由用户介入才能继续")
+    question: str = Field(description="简短题干，不要把选项写成 Markdown 列表")
+    interaction_type: InteractionType = Field(
+        default="clarification", description="交互类型"
+    )
+    title: str = Field(default="", description="交互标题，可留空")
+    fields: list[FieldSpec] = Field(
+        default_factory=list,
+        description="需要用户填写的字段；留空表示只有一个自由文本回复框",
+    )
+    recommendation: Recommendation | None = Field(
+        default=None, description="推荐答案，没有明确推荐时整个省略"
+    )
+    impact: list[str] = Field(
+        default_factory=list, description="这个决策会影响什么，每条一句；可留空"
+    )
+
+    @field_validator("interaction_type", mode="before")
+    @classmethod
+    def _lenient_interaction_type(cls, value: Any) -> str:
+        text = str(value or "").strip().lower()
+        return text if text in INTERACTION_TYPES else "clarification"
+
+    @field_validator("fields", "recommendation", "impact", mode="before")
+    @classmethod
+    def _decode_json_text(cls, value: Any) -> Any:
+        # 模型和网关有时会把嵌套参数整体 json.dumps 成字符串；解析失败时原样返回，
+        # 交给 pydantic 报错，再由 ToolArgHintMiddleware 转成可操作的提示。
+        return _decode_json_text(value)
+
+
+def build_human_input_tools() -> list[BaseTool]:
+    return [_build_tool(REQUEST_TOOL_NAME, _request_description())]
+
+
+def _build_tool(name: str, description: str) -> BaseTool:
+    def request_human_input(
+        reason: str,
+        question: str,
+        interaction_type: InteractionType = "clarification",
+        title: str = "",
+        fields: list[FieldSpec] | None = None,
+        recommendation: Recommendation | None = None,
+        impact: list[str] | None = None,
+    ) -> str:
+        payload = normalize_interaction_request(
+            reason=reason,
+            question=question,
+            interaction_type=interaction_type,
+            title=title,
+            fields=[_plain(field) for field in fields] if fields is not None else None,
+            recommendation=_plain(recommendation),
+            impact=list(impact) if impact is not None else None,
+            interaction_id=str(uuid4()),
+        )
+        answer = interrupt(payload)
+        values = resume_values(answer)
+        return json.dumps(values, ensure_ascii=False)
+
+    return StructuredTool.from_function(
+        func=request_human_input,
+        name=name,
+        description=description,
+        args_schema=HumanInputArgs,
+    )
+
+
+def _decode_json_text(value: Any) -> Any:
+    if not isinstance(value, str):
+        return value
+    text = value.strip()
+    if not text or text[0] not in "[{":
+        return value
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return value
+
+
+def _plain(value: Any) -> Any:
+    return value.model_dump() if isinstance(value, BaseModel) else value
+
+
+def _request_description() -> str:
+    return (
+        "请求用户提供继续执行所需的信息或决策，并暂停直到收到响应。"
+        "当你要让用户从多个后续操作中选择时，必须调用本工具，不要只在普通回复中列出编号选项。"
+        "只声明交互语义，不要指定前端组件。"
+        "fields / recommendation / impact 必须传原生 JSON 结构，不要序列化成字符串。"
+        "有可选项时必须用 single_select 或 multi_select，选项写进该字段的 options，"
+        "不要把选项写成 question 里的 Markdown 列表。"
+        "question 只保留简短题干。"
+        "recommendation 与 impact 可选。这不是工具权限确认。"
+    )