chore(release): devsper 2.5.0

LangChain/LangGraph integration adapters, examples, and tests.
Platform runtime events, execution graph metadata, MCP/tool runner
updates, and compatibility shims included in this release.

See CHANGELOG.md for details.

Made-with: Cursor

Author: rithulkamesh

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.5.0] — 2026-04-06
+
+### Added
+
+- **LangChain / LangGraph integrations** — `devsper.integrations.langchain_adapter` and `langgraph_adapter` for wrapping LangChain runnables as Devsper tasks and running compiled LangGraph nodes with Devsper DAG scheduling; CLI-friendly examples under `examples/langchain_agent.py` and `examples/langgraph_swarm.py`; optional extra `pip install 'devsper[langgraph]'` to pin LangGraph.
+
 ## [2.4.1] — 2026-03-31
 
 ### Fixed

README.md

@@ -129,6 +129,28 @@ Credentials are injected from the keyring (or env) when config is resolved—no
 
 ---
 
+## LangChain integration
+
+Devsper ships a **small adapter layer** (not a parallel orchestration stack) so you can keep building in **LangChain** and **LangGraph** while aligning execution with Devsper’s **task / DAG** mental model.
+
+| Module | Purpose |
+|--------|---------|
+| `devsper.integrations.langchain_adapter` | Wrap LangChain runnables and agents as tagged `Task`s; `run_langchain_runnable()` runs `ainvoke` / `invoke` and normalizes output for `Task.result`. |
+| `devsper.integrations.langgraph_adapter` | Derive a Devsper task graph from a compiled LangGraph graph (`compiled_graph_to_tasks`); `run_compiled_graph_as_devsper_tasks()` runs each node with bounded concurrency and pluggable state merge (default: concatenate list fields—good for `MessagesState`). |
+
+**Install:** `langchain` is a core dependency of the `devsper` package; **LangGraph** is pulled in transitively. To pin it explicitly: `pip install 'devsper[langgraph]'`.
+
+**Examples (from the runtime repo root):**
+
+```bash
+uv run python examples/langchain_agent.py --prompt "Say hi in one sentence."
+uv run python examples/langgraph_swarm.py --workers 4
+```
+
+Docs: [LangChain integration](https://docs.devsper.com/docs/langchain-integration) (source: `docs/docs/langchain-integration.md` in the docs tree).
+
+---
+
 ## Credentials
 
 API keys are **not** stored in config files. Use the **credential store** (OS keychain) or environment variables.
@@ -286,6 +308,8 @@ Rust workers: set `DEVSPER_WORKER_MODEL=github:gpt-4o` (or your model), `DEVSPER
 | Dataset analysis | `uv run python examples/data_science/dataset_analysis.py [path-to.csv]` |
 | Document intelligence | `uv run python examples/documents/analyze_documents.py [dir]` |
 | Parameter sweep | `uv run python examples/experiments/parameter_sweep.py --params '{"lr":[0.01,0.1]}'` |
+| LangChain agent (adapter) | `uv run python examples/langchain_agent.py [--live] [--prompt "..."]` |
+| LangGraph DAG (as Devsper tasks) | `uv run python examples/langgraph_swarm.py [--workers N]` |
 
 Outputs under `examples/output/`. Run from project root when using script paths.
 

devsper/contracts/__init__.py

@@ -0,0 +1,5 @@
+"""Shared contracts between runtime and platform (event type strings, etc.)."""
+
+from devsper.contracts.platform_event_type import DEVSPER_TO_PLATFORM, PlatformEventType
+
+__all__ = ["DEVSPER_TO_PLATFORM", "PlatformEventType"]

devsper/contracts/platform_event_type.py

@@ -0,0 +1,68 @@
+"""
+Canonical `event_type` strings accepted by the platform runtime ingest API and
+emitted by the runtime forwarder.
+
+**Single source of truth for Python.** Mirror:
+`platform/services/api/internal/contracts/runtime_events.go`
+"""
+
+from __future__ import annotations
+
+
+class PlatformEventType:
+    """Platform SSE / run_events.event_type values (string constants only)."""
+
+    RUN_STARTED = "run_started"
+    STEP_STARTED = "step_started"
+    STEP_COMPLETED = "step_completed"
+    AGENT_STARTED = "agent_started"
+    AGENT_FINISHED = "agent_finished"
+    RUN_PROGRESS = "run_progress"
+    TOOL_CALLED = "tool_called"
+    RUN_COMPLETED = "run_completed"
+    RUN_FAILED = "run_failed"
+    CLARIFICATION_REQUESTED = "clarification_requested"
+    CLARIFICATION_ANSWERED = "clarification_answered"
+    RUN_PAUSED = "run_paused"
+    RUN_RESUMED = "run_resumed"
+    LOG = "log"
+    EXECUTION_GRAPH_UPDATED = "EXECUTION_GRAPH_UPDATED"
+    SPECULATIVE_TASK_STARTED = "SPECULATIVE_TASK_STARTED"
+    SPECULATIVE_TASK_CANCELLED = "SPECULATIVE_TASK_CANCELLED"
+    HITL_REQUESTED = "HITL_REQUESTED"
+    HITL_RESOLVED = "HITL_RESOLVED"
+    WORKER_ASSIGNED = "WORKER_ASSIGNED"
+    AGENT_POOL_USED = "AGENT_POOL_USED"
+    EXECUTOR_FINISHED = "executor_finished"
+
+
+# DevSper `events` enum value (as string) -> platform ingest type
+DEVSPER_TO_PLATFORM: dict[str, str] = {
+    "swarm_started": PlatformEventType.RUN_STARTED,
+    "executor_started": PlatformEventType.RUN_STARTED,
+    "task_started": PlatformEventType.STEP_STARTED,
+    "task_completed": PlatformEventType.STEP_COMPLETED,
+    "agent_started": PlatformEventType.AGENT_STARTED,
+    "agent_finished": PlatformEventType.AGENT_FINISHED,
+    "run_completed": PlatformEventType.RUN_COMPLETED,
+    "task_failed": PlatformEventType.RUN_FAILED,
+    "run_failed": PlatformEventType.RUN_FAILED,
+    "tool_called": PlatformEventType.TOOL_CALLED,
+    "clarification_requested": PlatformEventType.CLARIFICATION_REQUESTED,
+    "clarification_needed": PlatformEventType.CLARIFICATION_REQUESTED,
+    "clarification_received": PlatformEventType.CLARIFICATION_ANSWERED,
+    "planner_started": PlatformEventType.RUN_PROGRESS,
+    "planner_finished": PlatformEventType.RUN_PROGRESS,
+    "reasoning_node_added": PlatformEventType.RUN_PROGRESS,
+    "budget_warning": PlatformEventType.RUN_PROGRESS,
+    "task_created": PlatformEventType.RUN_PROGRESS,
+    "task_model_selected": PlatformEventType.RUN_PROGRESS,
+    "agent_broadcast": PlatformEventType.RUN_PROGRESS,
+    "run_manifest_emitted": PlatformEventType.RUN_PROGRESS,
+    "worker_assigned": PlatformEventType.WORKER_ASSIGNED,
+    "speculative_started": PlatformEventType.SPECULATIVE_TASK_STARTED,
+    "speculative_cancelled": PlatformEventType.SPECULATIVE_TASK_CANCELLED,
+    "hitl_requested": PlatformEventType.HITL_REQUESTED,
+    "hitl_resolved": PlatformEventType.HITL_RESOLVED,
+    "executor_finished": PlatformEventType.EXECUTOR_FINISHED,
+}

devsper/debug_events.py

@@ -0,0 +1,38 @@
+"""DEVSPER_DEBUG_EVENTS=1 — log runtime → platform → delivery trail (stderr / logging)."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any
+
+_LOG = logging.getLogger("devsper.debug_events")
+
+
+def debug_events_enabled() -> bool:
+    return os.environ.get("DEVSPER_DEBUG_EVENTS", "").strip().lower() in (
+        "1",
+        "true",
+        "yes",
+        "on",
+    )
+
+
+def log_runtime_emit(stage: str, payload: dict[str, Any]) -> None:
+    if not debug_events_enabled():
+        return
+    try:
+        line = json.dumps({"debug_events": stage, **payload}, default=str)
+    except TypeError:
+        line = str(payload)
+    _LOG.info(line)
+
+
+def log_platform_body(body: dict[str, Any]) -> None:
+    if not debug_events_enabled():
+        return
+    try:
+        _LOG.info("[platform_event] %s", json.dumps(body, default=str))
+    except TypeError:
+        _LOG.info("[platform_event] %s", body)

devsper/docs/architecture/execution-model.md

@@ -6,7 +6,7 @@ The canonical execution model document lives under **docs**:
 
 That document is the source of truth for DAG execution, task state machine, HITL clarification (single-node and distributed, including Rust worker), bus topics, TUI lifecycle, and headless mode.
 
-For the latest runtime release notes (including 2.4.1 stabilization fixes), see:
+For the latest runtime release notes (including 2.5.0 LangChain/LangGraph adapters), see:
 
 - `https://docs.devsper.com/docs/release_notes`
 - `https://devsper.com/blog/distributed-runtime-upgrade-2-4-0`

devsper/integrations/__init__.py

@@ -0,0 +1,34 @@
+"""Optional bridges between Devsper and popular agent frameworks (LangChain, LangGraph)."""
+
+from __future__ import annotations
+
+__all__ = [
+    "langchain_task",
+    "run_langchain_runnable",
+    "stringify_langchain_output",
+    "LANGCHAIN_TASK_PREFIX",
+    "compiled_graph_to_tasks",
+    "default_list_merge_state",
+    "run_compiled_graph_as_devsper_tasks",
+]
+
+
+def __getattr__(name: str):
+    if name in (
+        "langchain_task",
+        "run_langchain_runnable",
+        "stringify_langchain_output",
+        "LANGCHAIN_TASK_PREFIX",
+    ):
+        from devsper.integrations import langchain_adapter as m
+
+        return getattr(m, name)
+    if name in (
+        "compiled_graph_to_tasks",
+        "default_list_merge_state",
+        "run_compiled_graph_as_devsper_tasks",
+    ):
+        from devsper.integrations import langgraph_adapter as m
+
+        return getattr(m, name)
+    raise AttributeError(name)

devsper/integrations/langchain_adapter.py

@@ -0,0 +1,80 @@
+"""Wrap LangChain runnables and agent pipelines as Devsper tasks (minimal surface, no extra framework)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+from devsper.types.task import Task, TaskStatus
+
+LANGCHAIN_TASK_PREFIX = "[devsper:langchain]"
+
+
+def langchain_task(
+    task_id: str,
+    *,
+    description: str = "",
+    dependencies: list[str] | None = None,
+    role: str | None = None,
+) -> Task:
+    """Return a Devsper `Task` tagged for LangChain execution (visible in logs and DAG exports)."""
+    desc = (description or "").strip() or f"LangChain runnable ({task_id})"
+    if LANGCHAIN_TASK_PREFIX not in desc:
+        desc = f"{LANGCHAIN_TASK_PREFIX} {desc}"
+    return Task(
+        id=task_id,
+        description=desc,
+        dependencies=list(dependencies or []),
+        status=TaskStatus.PENDING,
+        role=role,
+    )
+
+
+def stringify_langchain_output(value: Any, *, max_len: int = 32000) -> str:
+    """Normalize LangChain/LangGraph outputs to a string suitable for `Task.result`."""
+    if value is None:
+        return ""
+    if hasattr(value, "content"):
+        text = getattr(value, "content", value)
+        return str(text)[:max_len]
+    if isinstance(value, dict):
+        if "output" in value:
+            return stringify_langchain_output(value["output"], max_len=max_len)
+        if "messages" in value:
+            parts: list[str] = []
+            for m in value["messages"]:
+                if hasattr(m, "content"):
+                    parts.append(str(getattr(m, "content", m)))
+                else:
+                    parts.append(str(m))
+            return "\n".join(parts).strip()[:max_len]
+        try:
+            return json.dumps(value, default=str)[:max_len]
+        except TypeError:
+            return str(value)[:max_len]
+    if isinstance(value, str):
+        return value[:max_len]
+    return str(value)[:max_len]
+
+
+async def run_langchain_runnable(
+    task: Task,
+    runnable: Any,
+    input_data: dict[str, Any] | str | list[Any],
+    *,
+    config: Any | None = None,
+) -> str:
+    """
+    Run a LangChain `Runnable`, agent, or legacy executor with async `ainvoke` when available.
+
+    `input_data` may be a string (wrapped as `{"input": ...}`), a message list (chat models), or a dict.
+    """
+    inp: Any = input_data
+    if isinstance(inp, str):
+        inp = {"input": inp}
+    if hasattr(runnable, "ainvoke"):
+        out = await runnable.ainvoke(inp, config=config)
+    else:
+        out = await asyncio.to_thread(runnable.invoke, inp, config)
+    return stringify_langchain_output(out)