devsper 2.2.0__tar.gz → 2.4.0__tar.gz

{devsper-2.2.0 → devsper-2.4.0}/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.0] — 2026-03-31
+
+### Added
+
+- **Distributed runtime extension layer** — Added `devsper.distributed` package with controller and worker-runtime wrappers for clean orchestration composition.
+- **Agent pool** — Added `runtime/agent_pool.py` with reusable, worker-aware concurrent agent leasing (`acquire_agent`, `release_agent`, `run_agent`, `run_parallel`).
+- **Model router (runtime layer)** — Added `runtime/model_router.py` for planning/reasoning/validation model routing with fallback chains.
+- **Speculative planner (runtime layer)** — Added `runtime/speculative_planner.py` to predict and stage speculative successor tasks.
+- **Runtime HITL manager** — Added `runtime/hitl.py` for pause/resume and explicit human-input request lifecycle handling.
+- **Execution graph upgrades** — Extended runtime execution graph with worker assignment metadata and distributed lineage tracking.
+
+### Changed
+
+- **Executor composition** — Runtime executor now integrates AgentPool, ModelRouter, speculative planning hooks, and distributed assignment tracking while preserving default behavior.
+- **Task runner routing** — Task execution now supports pool-backed agent execution, scoped model routing, and fallback chain handling.
+- **Tool execution control** — Runtime ToolRunner now supports bounded concurrency, dependency-aware batching, per-call timeout, cancellation, and structured results.
+- **Event backpressure handling** — Runtime event stream now uses bounded queues with controlled overflow behavior.
+- **Runtime docs** — Updated runtime architecture docs in `devsper/README.md` with distributed flow, worker/controller lifecycle, and HITL/speculative execution details.
+
+## [2.3.0] — 2026-03-30
+
+### Added
+
+- **Autonomous Missions capability layer** — New `devsper.missions` package for long-horizon autonomous execution across research, coding, and experiment workflows.
+- **Mission planner and DAG generation** — Added `missions/mission_planner.py` to break goals into mission tasks, assign role agents, and define dependency graphs.
+- **Research mission workflow** — Added mission agents (`researcher_agent`, `reviewer_agent`, `writer_agent`, `editor_agent`) and end-to-end flow: research → critique → improve → finalize.
+- **Coding mission workflow** — Added mission agents (`architect_agent`, `coder_agent`, `tester_agent`, `debugger_agent`, `docs_agent`) and end-to-end flow: design → code → test → fix → document.
+- **Iteration engine** — Added `missions/iteration_loop.py` for quality-threshold-driven iterative execution with critique/improvement cycles.
+- **Mission memory** — Added `missions/mission_memory.py` to persist research findings, decisions, and experiment artifacts per mission.
+- **Long-running mission support** — Added checkpointing/resume support in `missions/mission_runner.py` plus HITL task-gating callback support.
+- **Mission UI** — Added dashboard `MissionView` and TUI mission execution path (`mission:research ...`, `mission:coding ...`, `mission:experiment ...`) to show goal, DAG, and iteration progress.
+
+### Changed
+
+- **SDK surface** — Exported `MissionRunner` from `devsper` package root for straightforward mission execution from Python.
+- **Testing** — Added runtime tests for mission DAG planning and checkpoint creation.
+
 ## [2.2.0] — 2026-03-28
 
 ### Added

{devsper-2.2.0 → devsper-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devsper
-Version: 2.2.0
+Version: 2.4.0
 Summary: Orchestrate distributed swarms of AI agents that collaboratively solve complex tasks.
 Project-URL: Homepage, https://github.com/devsper-com/runtime
 Project-URL: Documentation, https://docs.devsper.com
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.12
+Requires-Dist: duckduckgo-search>=8.1.1
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: keyring>=24.0
 Requires-Dist: langchain-anthropic>=1.3.4

devsper-2.4.0/devsper/README.md

@@ -0,0 +1,148 @@
+# Devsper Runtime Core
+
+Devsper runtime is built as a modular orchestration core with bounded concurrency, dynamic DAG mutation, and event-stream-driven observability.
+
+## Runtime Architecture Diagram
+
+```text
+User Task
+   |
+   v
+Swarm.run()
+   |
+   v
+Planner -> Scheduler (DAG)
+   |
+   v
+Runtime Executor ------------------------------+
+   |                                           |
+   +-> RuntimeStateManager                     |
+   +-> ExecutionGraph                          |
+   +-> RuntimeEventStream -> EventLog -> SSE  |
+   +-> TaskRunner                              |
+         +-> AgentRunner (optional stream-tool loop)
+               +-> Agent
+               +-> ToolRunner / tools.tool_runner
+```
+
+## Core Components
+
+- `swarm/swarm.py`
+  - Public entrypoint (`Swarm`), config/wiring, planning and execution bootstrap.
+- `runtime/executor.py`
+  - Event-driven scheduler loop, bounded parallel execution, cancellation propagation, dynamic task injection.
+- `runtime/state_manager.py`
+  - Concurrency-safe task state transitions and runtime DAG mutation entrypoint.
+- `runtime/execution_graph.py`
+  - Execution graph with lineage, edges, attempts, and status transitions.
+- `runtime/planner.py`
+  - Runtime wrapper for dynamic planner expansion and parent-child lineage.
+- `runtime/task_runner.py`
+  - Task lifecycle orchestration with scoped retries and fallback model handling.
+- `runtime/agent_runner.py`
+  - Async agent wrapper with optional streaming tool invocation loop.
+- `runtime/tool_runner.py`
+  - Parallel tool scheduler with bounded concurrency, dependency-aware batching, timeout, and cancellation.
+- `runtime/event_stream.py`
+  - In-process stream with queue backpressure policy (drop-oldest on overflow).
+- `runtime/retry.py`
+  - Retry scopes (`tool`, `agent`, `task`, `model_fallback`) and backoff policies.
+
+## Execution Lifecycle
+
+1. `Swarm.run()` creates root task, plans subtasks, and builds scheduler DAG.
+2. Executor emits `EXECUTOR_STARTED` and begins bounded task dispatch.
+3. Ready tasks transition to running through `RuntimeStateManager`.
+4. `TaskRunner` executes with scoped retries.
+5. `AgentRunner` may invoke tools (normal or streaming tool loop).
+6. Task completion/failure updates scheduler + execution graph.
+7. Adaptive mode can inject follow-up tasks at runtime.
+8. Executor emits `EXECUTOR_FINISHED` and `RUN_COMPLETED`.
+
+## Tool Calling Flow
+
+1. Agent determines tool intent from model output.
+2. Tool calls are parsed and scheduled.
+3. `ToolRunner.run_many(...)` executes calls in parallel with:
+   - `max_concurrency` semaphore
+   - dependency constraints (`depends_on`)
+   - per-call timeouts
+   - cancellation checks
+4. Results are isolated per call and fed back into agent loop.
+
+## Planner Flow
+
+1. Initial decomposition by `swarm/planner.py`.
+2. Runtime execution completes a task.
+3. `RuntimePlanner.expand(...)` optionally creates follow-up tasks.
+4. `RuntimeStateManager.add_tasks(...)` mutates DAG safely.
+5. `ExecutionGraph` records lineage from parent task.
+
+## Concurrency Model
+
+- Bounded executor workers (`worker_count`).
+- Bounded tool concurrency (`ToolRunner` semaphore).
+- Queue backpressure in event streaming (`max_queue_size` with controlled dropping).
+- Cooperative pause/resume and cancellation propagation across runtime loops.
+- Lock-guarded scheduler mutations via `RuntimeStateManager`.
+
+## Distributed Runtime Architecture
+
+```text
+Controller
+   |
+   v
+Worker Pool
+   |
+   v
+Worker Runtime
+   |
+   v
+Runtime Executor
+   |
+   v
+Agent Pool
+   |
+   v
+Tool Runner
+```
+
+- `distributed/controller.py`
+  - Worker registry, health state, load-aware assignment, reassignment hooks.
+- `distributed/worker_runtime.py`
+  - Worker-local runtime composition: `Executor`, `AgentPool`, `ModelRouter`, `ToolRunner`.
+- Existing multi-node transport/control remains in `nodes/controller.py` and `nodes/worker.py`.
+
+## Worker Lifecycle
+
+1. Worker registers with controller.
+2. Controller assigns tasks based on health and load.
+3. Worker executes task locally through runtime executor stack.
+4. Worker returns completion/failure.
+5. Controller updates worker/task state and reassigns on failure.
+
+## Controller Lifecycle
+
+1. Track worker registration and health.
+2. Assign ready tasks using load-aware strategy.
+3. Handle failures and perform retry/reassignment.
+4. Maintain global execution progress via event/log channels.
+
+## Agent Pool
+
+- `AgentPool` manages reusable agent instances per worker.
+- Supports `acquire_agent`, `release_agent`, `run_agent`, and `run_parallel`.
+- Enables worker-local, concurrent, reuse-based execution.
+
+## Speculative Execution
+
+- `SpeculativePlanner` predicts likely successor tasks.
+- Executor marks/schedules speculative tasks early.
+- Unused speculative branches can be cancelled on dependency failure.
+
+## HITL Flow
+
+1. Agent indicates human input is required.
+2. Runtime emits HITL/clarification event.
+3. Task pauses until response or timeout.
+4. Execution resumes or fails based on response policy.

{devsper-2.2.0 → devsper-2.4.0}/devsper/__init__.py

@@ -20,7 +20,7 @@ except Exception:  # pragma: no cover - missing dist metadata (e.g. bare checkou
 
 from devsper.config import get_config
 
-__all__ = ["Swarm", "get_config", "__version__"]
+__all__ = ["Swarm", "MissionRunner", "get_config", "__version__"]
 
 
 def __getattr__(name: str):
@@ -29,4 +29,8 @@ def __getattr__(name: str):
         from devsper.swarm.swarm import Swarm  # local import
 
         return Swarm
+    if name == "MissionRunner":
+        from devsper.missions import MissionRunner  # local import
+
+        return MissionRunner
     raise AttributeError(name)