exoclaw-executor-dbos 0.1.0__tar.gz

exoclaw_executor_dbos-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+dist/
+*.egg-info/
+.coverage

exoclaw_executor_dbos-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: exoclaw-executor-dbos
+Version: 0.1.0
+Summary: DBOS-backed durable executor for exoclaw — turns and tool calls survive restarts
+Requires-Python: >=3.11
+Requires-Dist: dbos>=1.0.0
+Requires-Dist: exoclaw>=0.9.0
+Requires-Dist: structlog>=24.0.0
+Description-Content-Type: text/markdown
+
+# exoclaw-executor-dbos
+
+DBOS-backed durable executor for exoclaw. Makes agent turns survive process restarts.
+
+Every LLM call and tool execution is a DBOS step, checkpointed to SQLite. If the process restarts mid-turn, DBOS replays completed steps and continues from the next one.

exoclaw_executor_dbos-0.1.0/README.md

@@ -0,0 +1,5 @@
+# exoclaw-executor-dbos
+
+DBOS-backed durable executor for exoclaw. Makes agent turns survive process restarts.
+
+Every LLM call and tool execution is a DBOS step, checkpointed to SQLite. If the process restarts mid-turn, DBOS replays completed steps and continues from the next one.

exoclaw_executor_dbos-0.1.0/exoclaw_executor_dbos/__init__.py

@@ -0,0 +1,5 @@
+from .executor import DBOSExecutor
+from .startup import init_dbos, recover
+from .turn import run_durable_turn, set_turn_context
+
+__all__ = ["DBOSExecutor", "init_dbos", "recover", "run_durable_turn", "set_turn_context"]

exoclaw_executor_dbos-0.1.0/exoclaw_executor_dbos/executor.py

@@ -0,0 +1,196 @@
+"""DBOS-backed durable executor for exoclaw.
+
+Drop-in replacement for DirectExecutor. Every LLM call and tool execution
+is a DBOS step, automatically checkpointed to SQLite. If the process
+restarts mid-turn, DBOS replays completed steps from the journal.
+
+Architecture follows the same pattern as standd_agent's TemporalExecutor:
+the agent loop runs inside a @DBOS.workflow(), and each chat/tool call
+is a @DBOS.step().
+
+Usage in nanobot wiring:
+    from exoclaw_executor_dbos import run_durable_turn, DBOSExecutor
+
+    # In message processing, instead of calling AgentLoop._process_message:
+    await run_durable_turn(session_id, message, ...)
+"""
+
+from __future__ import annotations
+
+import contextvars
+import dataclasses
+import json
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from dbos import DBOS
+from exoclaw.agent.conversation import Conversation
+from exoclaw.agent.tools.protocol import ToolContext
+from exoclaw.agent.tools.registry import ToolRegistry
+from exoclaw.providers.protocol import LLMProvider
+from exoclaw.providers.types import LLMResponse, ToolCallRequest
+
+# ── Serialization helpers ────────────────────────────────────────────────────
+
+
+def _response_to_dict(resp: LLMResponse) -> dict[str, Any]:
+    return dataclasses.asdict(resp)
+
+
+def _dict_to_response(d: dict[str, Any]) -> LLMResponse:
+    d = dict(d)  # don't mutate caller's dict
+    tool_calls = [ToolCallRequest(**tc) for tc in d.pop("tool_calls", [])]
+    return LLMResponse(tool_calls=tool_calls, **d)
+
+
+# ── Per-task context for non-serializable refs ───────────────────────────────
+# ContextVars are safe for concurrent workflows — each asyncio Task gets
+# its own copy, so parallel turns don't stomp on each other.
+
+_provider_var: contextvars.ContextVar[LLMProvider | None] = contextvars.ContextVar(
+    "_provider_var", default=None
+)
+_registry_var: contextvars.ContextVar[ToolRegistry | None] = contextvars.ContextVar(
+    "_registry_var", default=None
+)
+
+
+# ── DBOS step functions ──────────────────────────────────────────────────────
+# Module-level so DBOS can register and replay them.
+
+
+@DBOS.step(retries_allowed=True, max_attempts=3, interval_seconds=2)
+async def _chat_step(
+    messages: list[dict[str, Any]],
+    tools_json: str | None,
+    model: str | None,
+    temperature: float,
+    max_tokens: int,
+    reasoning_effort: str | None,
+) -> dict[str, Any]:
+    """Durable LLM call. Result is cached by DBOS on completion."""
+    provider = _provider_var.get()
+    if provider is None:
+        raise RuntimeError("provider not set — call set_turn_context() before running turns")
+    tools = json.loads(tools_json) if tools_json else None
+    resp = await provider.chat(
+        messages=messages,
+        tools=tools,
+        model=model,
+        temperature=temperature,
+        max_tokens=max_tokens,
+        reasoning_effort=reasoning_effort,
+    )
+    return _response_to_dict(resp)
+
+
+@DBOS.step(retries_allowed=True, max_attempts=2, interval_seconds=1)
+async def _tool_step(
+    name: str,
+    params: dict[str, Any],
+    ctx_data: dict[str, Any] | None,
+) -> str:
+    """Durable tool execution. Result is cached by DBOS on completion."""
+    registry = _registry_var.get()
+    if registry is None:
+        raise RuntimeError("registry not set — call set_turn_context() before running turns")
+    ctx = ToolContext(**ctx_data) if ctx_data else None
+    return await registry.execute(name, params, ctx)
+
+
+# ── DBOSExecutor ─────────────────────────────────────────────────────────────
+
+
+class DBOSExecutor:
+    """Executor that routes AgentLoop operations through DBOS steps.
+
+    Must be used inside a @DBOS.workflow() — see run_durable_turn().
+    Sets ContextVar refs so steps can access provider/registry safely
+    across concurrent workflows.
+    """
+
+    async def chat(
+        self,
+        provider: LLMProvider,
+        *,
+        messages: list[dict[str, object]],
+        tools: list[dict[str, object]] | None = None,
+        model: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int = 4096,
+        reasoning_effort: str | None = None,
+    ) -> LLMResponse:
+        _provider_var.set(provider)
+        tools_json = json.dumps(tools) if tools else None
+        result = await _chat_step(
+            messages=list(messages),
+            tools_json=tools_json,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            reasoning_effort=reasoning_effort,
+        )
+        return _dict_to_response(result)
+
+    async def execute_tool(
+        self,
+        registry: ToolRegistry,
+        name: str,
+        params: dict[str, object],
+        ctx: ToolContext | None = None,
+        *,
+        tool_call_id: str | None = None,
+    ) -> str:
+        _registry_var.set(registry)
+        ctx_data = dataclasses.asdict(ctx) if ctx else None
+        return await _tool_step(
+            name=name,
+            params=dict(params),
+            ctx_data=ctx_data,
+        )
+
+    async def build_prompt(
+        self,
+        conversation: Conversation,
+        session_id: str,
+        message: str,
+        *,
+        channel: str | None = None,
+        chat_id: str | None = None,
+        media: list[str] | None = None,
+        plugin_context: list[str] | None = None,
+        **kwargs: list[str] | None,
+    ) -> list[dict[str, object]]:
+        return await conversation.build_prompt(
+            session_id,
+            message,
+            channel=channel,
+            chat_id=chat_id,
+            media=media,
+            plugin_context=plugin_context,
+            **kwargs,
+        )
+
+    async def record(
+        self,
+        conversation: Conversation,
+        session_id: str,
+        new_messages: list[dict[str, object]],
+    ) -> None:
+        await conversation.record(session_id, new_messages)
+
+    async def clear(
+        self,
+        conversation: Conversation,
+        session_id: str,
+    ) -> bool:
+        return await conversation.clear(session_id)
+
+    async def run_hook(
+        self,
+        fn: Callable[..., Awaitable[object]],
+        /,
+        *args: object,
+        **kwargs: object,
+    ) -> object:
+        return await fn(*args, **kwargs)

exoclaw_executor_dbos-0.1.0/exoclaw_executor_dbos/startup.py

@@ -0,0 +1,43 @@
+"""DBOS initialization and recovery for exoclaw.
+
+Call init_dbos() once at app startup to initialize DBOS with SQLite.
+Call recover() after set_turn_context() to resume incomplete workflows.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import structlog
+from dbos import DBOS
+
+logger = structlog.get_logger()
+
+
+def init_dbos(db_path: str | Path = "exoclaw.sqlite") -> None:
+    """Initialize DBOS with SQLite.
+
+    Call this once at startup, before any turns run.
+    Does NOT trigger recovery — call recover() separately after
+    set_turn_context() has been called.
+    """
+    DBOS(
+        config={
+            "name": "exoclaw",
+            "system_database_url": f"sqlite:///{db_path}",
+        }
+    )
+    DBOS.launch()
+    logger.info("dbos_initialized", db_path=str(db_path))
+
+
+def recover() -> None:
+    """Recover incomplete workflows from a previous run.
+
+    Must be called AFTER set_turn_context() so that recovered
+    workflows have access to provider/conversation/tools.
+    """
+    recover_fn = getattr(DBOS, "recover_pending_workflows", None)
+    if recover_fn is not None:
+        recover_fn()
+    logger.info("dbos_recovery_complete")

exoclaw_executor_dbos-0.1.0/exoclaw_executor_dbos/turn.py

@@ -0,0 +1,157 @@
+"""Durable turn — runs an agent turn as a DBOS workflow.
+
+Equivalent to standd_agent's _run_turn() but using DBOS instead of Temporal.
+The agent loop runs inside the workflow, with each chat/tool call as a step.
+"""
+
+from __future__ import annotations
+
+import contextvars
+from typing import Any
+
+from dbos import DBOS
+from exoclaw.agent.conversation import Conversation
+from exoclaw.agent.loop import AgentLoop
+from exoclaw.agent.tools.protocol import Tool
+from exoclaw.providers.protocol import LLMProvider
+
+from .executor import DBOSExecutor
+
+
+class _NullBus:
+    """No-op bus — AgentLoop requires one but DBOSExecutor bypasses it."""
+
+    async def publish_inbound(self, msg: Any) -> None:
+        pass
+
+    async def publish_outbound(self, msg: Any) -> None:
+        pass
+
+    async def get_inbound(self) -> Any:
+        raise NotImplementedError
+
+    async def get_outbound(self) -> Any:
+        raise NotImplementedError
+
+
+# ── Per-task context for non-serializable deps ───────────────────────────────
+# ContextVars are safe for concurrent workflows — each asyncio Task gets
+# its own copy.
+
+_ctx_provider: contextvars.ContextVar[LLMProvider | None] = contextvars.ContextVar(
+    "_ctx_provider", default=None
+)
+_ctx_conversation: contextvars.ContextVar[Conversation | None] = contextvars.ContextVar(
+    "_ctx_conversation", default=None
+)
+_ctx_tools: contextvars.ContextVar[list[Tool] | None] = contextvars.ContextVar(
+    "_ctx_tools", default=None
+)
+_ctx_on_tool_calls: contextvars.ContextVar[Any] = contextvars.ContextVar(
+    "_ctx_on_tool_calls", default=None
+)
+_ctx_on_tool_result: contextvars.ContextVar[Any] = contextvars.ContextVar(
+    "_ctx_on_tool_result", default=None
+)
+_ctx_on_pre_tool: contextvars.ContextVar[Any] = contextvars.ContextVar(
+    "_ctx_on_pre_tool", default=None
+)
+
+
+def set_turn_context(
+    *,
+    provider: LLMProvider,
+    conversation: Conversation,
+    tools: list[Tool] | None = None,
+    on_tool_calls: Any = None,
+    on_tool_result: Any = None,
+    on_pre_tool: Any = None,
+) -> None:
+    """Set the non-serializable context for durable turns.
+
+    Call once at startup. The same provider/conversation/tools are used
+    for all turns and workflow recovery. Safe for concurrent turns via
+    ContextVar inheritance.
+    """
+    _ctx_provider.set(provider)
+    _ctx_conversation.set(conversation)
+    _ctx_tools.set(tools)
+    _ctx_on_tool_calls.set(on_tool_calls)
+    _ctx_on_tool_result.set(on_tool_result)
+    _ctx_on_pre_tool.set(on_pre_tool)
+
+
+@DBOS.workflow()
+async def run_durable_turn(
+    session_id: str,
+    message: str,
+    *,
+    channel: str = "cli",
+    chat_id: str = "direct",
+    media: list[str] | None = None,
+    plugin_context: list[str] | None = None,
+    max_iterations: int = 40,
+    temperature: float = 0.7,
+    max_tokens: int = 4096,
+    model: str | None = None,
+    reasoning_effort: str | None = None,
+    turn_context: list[str] | None = None,
+    skills: list[str] | None = None,
+) -> str | None:
+    """Run one full agent turn as a durable DBOS workflow.
+
+    Every LLM call and tool execution within the turn is a DBOS step.
+    If the process restarts, DBOS replays completed steps and continues.
+
+    Returns the final assistant content, or None if max iterations reached.
+    """
+    provider = _ctx_provider.get()
+    conversation = _ctx_conversation.get()
+    tools = _ctx_tools.get()
+
+    if provider is None:
+        raise RuntimeError("provider must be set via set_turn_context()")
+    if conversation is None:
+        raise RuntimeError("conversation must be set via set_turn_context()")
+
+    executor = DBOSExecutor()
+
+    loop = AgentLoop(
+        bus=_NullBus(),  # type: ignore[arg-type]
+        provider=provider,
+        conversation=conversation,
+        executor=executor,
+        tools=tools,
+        model=model,
+        max_iterations=max_iterations,
+        temperature=temperature,
+        max_tokens=max_tokens,
+        reasoning_effort=reasoning_effort,
+        on_tool_calls=_ctx_on_tool_calls.get(),
+        on_tool_result=_ctx_on_tool_result.get(),
+        on_pre_tool=_ctx_on_pre_tool.get(),
+    )
+
+    kwargs: dict[str, Any] = {}
+    if skills:
+        kwargs["skills"] = skills
+
+    initial = await executor.build_prompt(
+        conversation,
+        session_id,
+        message,
+        channel=channel,
+        chat_id=chat_id,
+        media=media,
+        plugin_context=plugin_context,
+        turn_context=turn_context,
+        **kwargs,
+    )
+
+    final_content, _, all_msgs = await loop._run_agent_loop(initial)
+
+    # Persist the turn
+    new_msgs = all_msgs[len(initial) - 1 :]
+    await executor.record(conversation, session_id, new_msgs)
+
+    return final_content

exoclaw_executor_dbos-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "exoclaw-executor-dbos"
+version = "0.1.0"
+description = "DBOS-backed durable executor for exoclaw — turns and tool calls survive restarts"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "exoclaw>=0.9.0",
+    "dbos>=1.0.0",
+    "structlog>=24.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

exoclaw_executor_dbos-0.1.0/tests/test_executor.py

@@ -0,0 +1,68 @@
+"""Basic tests for exoclaw-executor-dbos."""
+
+from exoclaw.providers.types import LLMResponse, ToolCallRequest
+from exoclaw_executor_dbos.executor import (
+    DBOSExecutor,
+    _dict_to_response,
+    _response_to_dict,
+)
+
+
+class TestSerialization:
+    def test_response_roundtrip(self) -> None:
+        resp = LLMResponse(
+            content="hello",
+            tool_calls=[ToolCallRequest(id="1", name="exec", arguments={"cmd": "ls"})],
+            finish_reason="tool_calls",
+            usage={"prompt_tokens": 10, "completion_tokens": 5},
+        )
+        d = _response_to_dict(resp)
+        restored = _dict_to_response(d)
+        assert restored.content == "hello"
+        assert len(restored.tool_calls) == 1
+        assert restored.tool_calls[0].name == "exec"
+        assert restored.tool_calls[0].arguments == {"cmd": "ls"}
+        assert restored.finish_reason == "tool_calls"
+
+    def test_response_roundtrip_no_tools(self) -> None:
+        resp = LLMResponse(content="done", finish_reason="stop")
+        d = _response_to_dict(resp)
+        restored = _dict_to_response(d)
+        assert restored.content == "done"
+        assert restored.tool_calls == []
+        assert restored.finish_reason == "stop"
+
+    def test_response_roundtrip_with_reasoning(self) -> None:
+        resp = LLMResponse(
+            content="answer",
+            reasoning_content="I thought about it",
+            thinking_blocks=[{"type": "thinking", "text": "hmm"}],
+        )
+        d = _response_to_dict(resp)
+        restored = _dict_to_response(d)
+        assert restored.reasoning_content == "I thought about it"
+        assert restored.thinking_blocks == [{"type": "thinking", "text": "hmm"}]
+
+    def test_dict_to_response_does_not_mutate_input(self) -> None:
+        d = {
+            "content": "hi",
+            "tool_calls": [{"id": "1", "name": "exec", "arguments": {}}],
+            "finish_reason": "stop",
+            "usage": {},
+            "reasoning_content": None,
+            "thinking_blocks": None,
+        }
+        original_keys = set(d.keys())
+        _dict_to_response(d)
+        assert set(d.keys()) == original_keys  # not mutated
+
+
+class TestDBOSExecutorProtocol:
+    def test_has_required_methods(self) -> None:
+        executor = DBOSExecutor()
+        assert hasattr(executor, "chat")
+        assert hasattr(executor, "execute_tool")
+        assert hasattr(executor, "build_prompt")
+        assert hasattr(executor, "record")
+        assert hasattr(executor, "clear")
+        assert hasattr(executor, "run_hook")