steerable-sidecar 0.1.0__tar.gz

steerable_sidecar-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: steerable-sidecar
+Version: 0.1.0
+Summary: Steerable agent runtime sidecar — JSON-RPC over stdio.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: steerable-agent-protocol<1.0.0,>=0.1.0
+Requires-Dist: steerable-agent-harness<1.0.0,>=0.1.0
+Requires-Dist: steerable-agent-runtime<1.0.0,>=0.1.0
+
+# steerable-sidecar
+
+The portable Python entrypoint for the **steerable** framework. Designed to be
+spawned by an Electron / desktop host (or directly from a CLI) and addressed
+via stdio JSON-RPC 2.0.
+
+## Quick start
+
+```bash
+pip install steerable-sidecar
+python -m steerable_sidecar
+```
+
+Or use the console script:
+
+```bash
+steerable-sidecar
+```
+
+The process:
+
+1. Initializes the in-memory storage and a default tool router.
+2. Prints the **ready signal** on **stderr** as a single line:
+   `__SIDECAR_READY__:<json>` matching `spec/sidecar/SidecarHealth`.
+3. Begins reading JSON-RPC frames from stdin (one frame per line).
+4. Writes responses and notifications to stdout.
+
+See `spec/sidecar/README.md` for the full method/notification catalog.
+
+## Embedding
+
+```python
+import asyncio
+from steerable_sidecar import Sidecar
+
+async def main() -> None:
+    sidecar = Sidecar()
+    sidecar.tools.register(my_tool)
+    await sidecar.serve()
+
+asyncio.run(main())
+```

steerable_sidecar-0.1.0/README.md

@@ -0,0 +1,42 @@
+# steerable-sidecar
+
+The portable Python entrypoint for the **steerable** framework. Designed to be
+spawned by an Electron / desktop host (or directly from a CLI) and addressed
+via stdio JSON-RPC 2.0.
+
+## Quick start
+
+```bash
+pip install steerable-sidecar
+python -m steerable_sidecar
+```
+
+Or use the console script:
+
+```bash
+steerable-sidecar
+```
+
+The process:
+
+1. Initializes the in-memory storage and a default tool router.
+2. Prints the **ready signal** on **stderr** as a single line:
+   `__SIDECAR_READY__:<json>` matching `spec/sidecar/SidecarHealth`.
+3. Begins reading JSON-RPC frames from stdin (one frame per line).
+4. Writes responses and notifications to stdout.
+
+See `spec/sidecar/README.md` for the full method/notification catalog.
+
+## Embedding
+
+```python
+import asyncio
+from steerable_sidecar import Sidecar
+
+async def main() -> None:
+    sidecar = Sidecar()
+    sidecar.tools.register(my_tool)
+    await sidecar.serve()
+
+asyncio.run(main())
+```

steerable_sidecar-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "steerable-sidecar"
+version = "0.1.0"
+description = "Steerable agent runtime sidecar — JSON-RPC over stdio."
+readme = "README.md"
+requires-python = ">=3.10"
+# Pre-1.0 inter-package pins use `>=X,<1.0.0` ranges so release-please can
+# bump individual packages without forcing a coordinated re-pin here.
+# See packages/agent-harness/py/pyproject.toml for the rationale.
+dependencies = [
+  "pydantic>=2.10.0",
+  "steerable-agent-protocol>=0.1.0,<1.0.0",
+  "steerable-agent-harness>=0.1.0,<1.0.0",
+  "steerable-agent-runtime>=0.1.0,<1.0.0",
+]
+
+[project.scripts]
+steerable-sidecar = "steerable_sidecar.__main__:main"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.uv.sources]
+steerable-agent-protocol = { workspace = true }
+steerable-agent-harness = { workspace = true }
+steerable-agent-runtime = { workspace = true }
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

steerable_sidecar-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

steerable_sidecar-0.1.0/src/steerable_sidecar/__init__.py

@@ -0,0 +1,6 @@
+"""steerable-sidecar — portable runtime entrypoint."""
+
+from .sidecar import Sidecar, SidecarConfig
+
+__all__ = ["Sidecar", "SidecarConfig"]
+__version__ = "0.1.0"

steerable_sidecar-0.1.0/src/steerable_sidecar/__main__.py

@@ -0,0 +1,41 @@
+"""``python -m steerable_sidecar`` entrypoint."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+
+from .sidecar import Sidecar, SidecarConfig
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="steerable-sidecar")
+    parser.add_argument(
+        "--log-level",
+        default="INFO",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        help="Sidecar log level (logged on stderr).",
+    )
+    parser.add_argument(
+        "--quiet-ready",
+        action="store_true",
+        help="Skip the __SIDECAR_READY__ stderr marker.",
+    )
+    return parser
+
+
+def main() -> int:
+    parser = _build_parser()
+    args = parser.parse_args()
+    config = SidecarConfig(log_level=args.log_level, quiet_stderr=args.quiet_ready)
+    sidecar = Sidecar(config=config)
+    try:
+        asyncio.run(sidecar.serve())
+    except KeyboardInterrupt:
+        logging.getLogger("steerable_sidecar").info("interrupted")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

steerable_sidecar-0.1.0/src/steerable_sidecar/sidecar.py

@@ -0,0 +1,582 @@
+"""Sidecar core: wires the runtime adapters into a JSON-RPC server.
+
+Methods (see spec/sidecar/README.md for the full catalog):
+
+  system.ping              -> SidecarHealth
+  system.shutdown          -> null
+  system.shutdown_now      -> null
+  agent.session.create     -> AgentSession
+  agent.session.resume     -> AgentSession
+  agent.session.list       -> AgentSession[]
+  agent.chat.stream        -> { streamId } (chunks pushed via `stream.chunk`,
+                                            terminator via `stream.done`)
+  agent.chat.cancel        -> null         (best-effort cancel of an in-flight stream)
+  tool.list                -> ToolDescriptor[]
+  tool.invoke              -> ToolResult
+  trace.fetch              -> { trace, spans, events }
+  config.get / config.set
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import platform
+import sys
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+from steerable_agent_protocol.generated import (
+    AgentSession,
+    SidecarHealth,
+    ToolCall,
+)
+from steerable_agent_runtime import (
+    BudgetExhaustedError,
+    PolicyDeniedError,
+    StorageError,
+    ToolDispatchError,
+    ToolRouter,
+)
+from steerable_agent_runtime.llm import LLMMessage, LLMProvider
+from steerable_agent_runtime.storage import InMemoryStorage, StorageAdapter
+from steerable_agent_runtime.transport.stdio_jsonrpc import (
+    JsonRpcError,
+    JsonRpcServer,
+    StdioJsonRpcTransport,
+    encode_frame,
+)
+
+logger = logging.getLogger("steerable_sidecar")
+
+PROTOCOL_VERSION = "0.1.0"
+SIDECAR_VERSION = "0.1.0"
+READY_PREFIX = "__SIDECAR_READY__:"
+
+
+@dataclass
+class SidecarConfig:
+    """Sidecar runtime configuration."""
+
+    log_level: str = "INFO"
+    quiet_stderr: bool = False
+    grace_period_seconds: float = 5.0
+    install_signal_handlers: bool = True
+    initial_tools: list[Any] = field(default_factory=list)
+
+
+class Sidecar:
+    """In-process sidecar harness.
+
+    The main entrypoint composes a `JsonRpcServer`, a default `ToolRouter`, an
+    `InMemoryStorage`, and a `StdioJsonRpcTransport`. Embedders can swap any of
+    these by setting the corresponding attribute before calling ``serve()``.
+    """
+
+    def __init__(
+        self,
+        *,
+        config: SidecarConfig | None = None,
+        storage: StorageAdapter | None = None,
+        tools: ToolRouter | None = None,
+        llm_provider_factory: Any | None = None,
+    ) -> None:
+        self.config = config or SidecarConfig()
+        self.storage: StorageAdapter = storage or InMemoryStorage()
+        self.tools: ToolRouter = tools or ToolRouter()
+        self.server = JsonRpcServer()
+        self._llm_provider_factory = llm_provider_factory or default_llm_provider_factory
+        self._streams: dict[str, asyncio.Task[Any]] = {}
+        self._transport: StdioJsonRpcTransport | None = None
+        self._started_ms = int(time.monotonic() * 1000)
+        self._wall_started_ms = int(time.time() * 1000)
+        self._shutdown_requested = asyncio.Event()
+        self._serving = False
+
+        self._register_default_methods()
+        for tool in self.config.initial_tools:
+            self.tools.register(tool)
+
+    # ------------------------------------------------------------------
+    # Method registration
+    # ------------------------------------------------------------------
+
+    def _register_default_methods(self) -> None:
+        register = self.server.register
+        register("system.ping", self._handle_ping)
+        register("system.shutdown", self._handle_shutdown)
+        register("system.shutdown_now", self._handle_shutdown_now)
+        register("agent.session.create", self._handle_session_create)
+        register("agent.session.resume", self._handle_session_resume)
+        register("agent.session.list", self._handle_session_list)
+        register("tool.list", self._handle_tool_list)
+        register("tool.invoke", self._handle_tool_invoke)
+        register("trace.fetch", self._handle_trace_fetch)
+        register("config.get", self._handle_config_get)
+        register("config.set", self._handle_config_set)
+        register("agent.chat.stream", self._handle_chat_stream)
+        register("agent.chat.cancel", self._handle_chat_cancel)
+
+    # ------------------------------------------------------------------
+    # Entrypoint
+    # ------------------------------------------------------------------
+
+    async def serve(self) -> None:
+        """Run the sidecar until shutdown is requested."""
+
+        self._configure_logging()
+        if self.config.install_signal_handlers:
+            self._install_signal_handlers()
+
+        ready = await self.snapshot_health()
+        self._emit_ready_marker(ready)
+
+        reader, writer = await self._connect_stdio()
+        transport = StdioJsonRpcTransport(writer)
+        self._transport = transport
+        await transport.emit_notification(
+            "lifecycle.ready",
+            {
+                "version": SIDECAR_VERSION,
+                "protocolVersion": PROTOCOL_VERSION,
+                "pid": os.getpid(),
+                "listenInfo": {"transport": "stdio"},
+            },
+        )
+
+        self._serving = True
+        try:
+            while not self._shutdown_requested.is_set():
+                line_task = asyncio.ensure_future(reader.readline())
+                shutdown_task = asyncio.ensure_future(self._shutdown_requested.wait())
+                done, pending = await asyncio.wait(
+                    {line_task, shutdown_task},
+                    return_when=asyncio.FIRST_COMPLETED,
+                )
+                for task in pending:
+                    task.cancel()
+                if shutdown_task in done:
+                    break
+                line = line_task.result()
+                if not line:
+                    break
+                response = await self.server.handle_frame(line.decode("utf-8"))
+                if response is None:
+                    continue
+                writer.write(encode_frame(response))
+                await self._maybe_drain(writer)
+        finally:
+            await transport.emit_notification(
+                "lifecycle.shutdown",
+                {"reason": "normal" if self._shutdown_requested.is_set() else "eof"},
+            )
+            await transport.aclose()
+            close = getattr(writer, "close", None)
+            if close is not None:
+                close()
+            self._serving = False
+
+    async def request_shutdown(self) -> None:
+        self._shutdown_requested.set()
+
+    async def snapshot_health(self) -> SidecarHealth:
+        uptime = int(time.monotonic() * 1000) - self._started_ms
+        return SidecarHealth(
+            status="ok" if self._serving or self._started_ms else "starting",
+            version=SIDECAR_VERSION,
+            protocolVersion=PROTOCOL_VERSION,
+            uptimeMs=max(0, uptime),
+            pid=os.getpid(),
+            pythonVersion=platform.python_version(),
+            platform=f"{sys.platform}-{platform.machine()}",
+            loadedTools=len(self.tools.list_tools()),
+            activeTraces=0,
+        )
+
+    # ------------------------------------------------------------------
+    # Method handlers
+    # ------------------------------------------------------------------
+
+    async def _handle_ping(self, _params: dict[str, Any] | None) -> dict[str, Any]:
+        health = await self.snapshot_health()
+        return health.model_dump(exclude_none=True)
+
+    async def _handle_shutdown(self, _params: dict[str, Any] | None) -> None:
+        # Schedule the actual stop so the response can be drained first.
+        loop = asyncio.get_running_loop()
+        loop.call_later(0.1, lambda: self._shutdown_requested.set())
+        return None
+
+    async def _handle_shutdown_now(self, _params: dict[str, Any] | None) -> None:
+        self._shutdown_requested.set()
+        return None
+
+    async def _handle_session_create(self, params: dict[str, Any] | None) -> dict[str, Any]:
+        params = _require_params(params)
+        session = AgentSession(
+            sessionId=params.get("sessionId") or _new_session_id(),
+            userId=params.get("userId") or "local",
+            chatId=params["chatId"],
+            currentStage=params.get("currentStage", "plan"),
+            isActive=True,
+            createdAt=_iso_now(),
+            updatedAt=_iso_now(),
+            scenario=params.get("scenario", "agent-entry"),
+            stageData=params.get("stageData"),
+            projectId=params.get("projectId"),
+        )
+        try:
+            stored = await self.storage.upsert_session(session)
+        except StorageError as exc:
+            raise JsonRpcError(str(exc), code=-32011, kind="internal") from exc
+        return stored.model_dump(exclude_none=True)
+
+    async def _handle_session_resume(self, params: dict[str, Any] | None) -> dict[str, Any]:
+        params = _require_params(params)
+        session_id = params.get("sessionId")
+        if not session_id:
+            raise JsonRpcError("sessionId required", code=-32602, kind="invalid_params")
+        session = await self.storage.get_session(session_id)
+        if session is None:
+            raise JsonRpcError(
+                f"session not found: {session_id}", code=-32004, kind="invalid_request"
+            )
+        return session.model_dump(exclude_none=True)
+
+    async def _handle_session_list(self, params: dict[str, Any] | None) -> list[dict[str, Any]]:
+        params = params or {}
+        sessions = await self.storage.list_sessions(
+            user_id=params.get("userId"),
+            chat_id=params.get("chatId"),
+            active_only=bool(params.get("activeOnly", False)),
+        )
+        return [s.model_dump(exclude_none=True) for s in sessions]
+
+    async def _handle_tool_list(self, _params: dict[str, Any] | None) -> list[dict[str, Any]]:
+        return self.tools.describe()
+
+    async def _handle_tool_invoke(self, params: dict[str, Any] | None) -> dict[str, Any]:
+        params = _require_params(params)
+        try:
+            call = ToolCall(
+                id=params.get("id") or _new_call_id(),
+                name=params["name"],
+                arguments=params.get("arguments") or {},
+            )
+        except KeyError as exc:
+            raise JsonRpcError(
+                f"missing argument: {exc.args[0]}", code=-32602, kind="invalid_params"
+            ) from exc
+        try:
+            result = await self.tools.dispatch(
+                call,
+                consent_granted=bool(params.get("consentGranted", False)),
+                context=params.get("context"),
+            )
+        except PolicyDeniedError as exc:
+            raise JsonRpcError(
+                exc.message, code=-32020, kind="policy_denied", data=exc.data
+            ) from exc
+        except BudgetExhaustedError as exc:
+            raise JsonRpcError(
+                exc.message, code=-32021, kind="budget_exhausted", data=exc.data
+            ) from exc
+        except ToolDispatchError as exc:
+            raise JsonRpcError(
+                exc.message, code=-32030, kind="tool_failed", data=exc.data
+            ) from exc
+        return result.model_dump(exclude_none=True)
+
+    async def _handle_trace_fetch(self, params: dict[str, Any] | None) -> dict[str, Any]:
+        params = _require_params(params)
+        trace_id = params.get("traceId")
+        if not trace_id:
+            raise JsonRpcError("traceId required", code=-32602, kind="invalid_params")
+        trace = await self.storage.get_trace(trace_id)
+        if trace is None:
+            raise JsonRpcError(
+                f"trace not found: {trace_id}", code=-32004, kind="invalid_request"
+            )
+        spans = await self.storage.list_spans(trace_id)
+        events = await self.storage.list_events(trace_id)
+        return {
+            "trace": trace.model_dump(exclude_none=True),
+            "spans": [s.model_dump(exclude_none=True) for s in spans],
+            "events": [e.model_dump(exclude_none=True) for e in events],
+        }
+
+    async def _handle_config_get(self, _params: dict[str, Any] | None) -> dict[str, Any]:
+        return {
+            "logLevel": self.config.log_level,
+            "gracePeriodSeconds": self.config.grace_period_seconds,
+            "version": SIDECAR_VERSION,
+            "protocolVersion": PROTOCOL_VERSION,
+        }
+
+    async def _handle_config_set(self, params: dict[str, Any] | None) -> None:
+        params = _require_params(params)
+        log_level = params.get("logLevel")
+        if log_level is not None:
+            self.config.log_level = str(log_level)
+            logging.getLogger().setLevel(self.config.log_level)
+        return None
+
+    async def _handle_chat_stream(self, params: dict[str, Any] | None) -> dict[str, Any]:
+        """Start a streaming chat-completion run.
+
+        Params shape (all optional unless noted)::
+
+            {
+              "provider": "openai_compat" | "anthropic" | <custom>,  # required
+              "model": "gpt-4o-mini",                                # required
+              "messages": [{"role": "...", "content": "..."}],       # required
+              "baseUrl": "https://api.example.com/v1",
+              "apiKey":  "sk-...",
+              "temperature": 0.2,
+              "maxTokens": 1024,
+              "tools":   [...],         # OpenAI tool descriptors
+              "streamId": "str_xyz",    # auto-generated if omitted
+              "providerOptions": {...}, # passthrough
+            }
+
+        Returns ``{"streamId": "..."}`` immediately. Chunks arrive as
+        ``stream.chunk`` notifications with ``{"streamId", "delta"}``;
+        completion is signalled by ``stream.done`` with ``{"streamId",
+        "finishReason", "usage"}``. Errors mid-stream are emitted as
+        ``stream.error``.
+        """
+
+        params = _require_params(params)
+        if self._transport is None:
+            raise JsonRpcError(
+                "transport not ready", code=-32099, kind="internal"
+            )
+        try:
+            provider = self._llm_provider_factory(params)
+        except Exception as exc:  # surface as RPC error before scheduling task
+            raise JsonRpcError(
+                f"failed to construct LLM provider: {exc}",
+                code=-32602,
+                kind="invalid_params",
+            ) from exc
+
+        stream_id = params.get("streamId") or _new_stream_id()
+        messages = _coerce_messages(params.get("messages") or [])
+        kwargs = _build_provider_kwargs(params)
+
+        transport = self._transport
+        task = asyncio.create_task(
+            self._run_chat_stream(provider, messages, kwargs, stream_id, transport)
+        )
+        self._streams[stream_id] = task
+        return {"streamId": stream_id}
+
+    async def _handle_chat_cancel(self, params: dict[str, Any] | None) -> None:
+        params = _require_params(params)
+        stream_id = params.get("streamId")
+        if not stream_id:
+            raise JsonRpcError("streamId required", code=-32602, kind="invalid_params")
+        task = self._streams.pop(stream_id, None)
+        if task is not None and not task.done():
+            task.cancel()
+        return None
+
+    async def _run_chat_stream(
+        self,
+        provider: LLMProvider,
+        messages: list[LLMMessage],
+        kwargs: dict[str, Any],
+        stream_id: str,
+        transport: StdioJsonRpcTransport,
+    ) -> None:
+        try:
+            iterator = provider.stream(messages, **kwargs)
+            async for chunk in iterator:
+                payload: dict[str, Any] = {"streamId": stream_id}
+                if chunk.content_delta is not None:
+                    payload["delta"] = chunk.content_delta
+                if chunk.reasoning_delta is not None:
+                    payload["reasoningDelta"] = chunk.reasoning_delta
+                if chunk.tool_call_delta is not None:
+                    payload["toolCall"] = chunk.tool_call_delta.model_dump(
+                        exclude_none=True
+                    )
+                if chunk.finish_reason is not None:
+                    payload["finishReason"] = chunk.finish_reason
+                if chunk.usage is not None:
+                    payload["usage"] = {
+                        "promptTokens": chunk.usage.prompt_tokens,
+                        "completionTokens": chunk.usage.completion_tokens,
+                        "totalTokens": chunk.usage.total_tokens,
+                    }
+                await transport.emit_notification("stream.chunk", payload)
+            await transport.emit_notification(
+                "stream.done", {"streamId": stream_id, "ok": True}
+            )
+        except asyncio.CancelledError:
+            await transport.emit_notification(
+                "stream.done", {"streamId": stream_id, "ok": False, "cancelled": True}
+            )
+        except Exception as exc:
+            logger.exception("chat stream %s failed", stream_id)
+            await transport.emit_notification(
+                "stream.error",
+                {
+                    "streamId": stream_id,
+                    "kind": exc.__class__.__name__,
+                    "message": str(exc),
+                },
+            )
+        finally:
+            self._streams.pop(stream_id, None)
+
+    # ------------------------------------------------------------------
+    # Plumbing
+    # ------------------------------------------------------------------
+
+    def _emit_ready_marker(self, health: SidecarHealth) -> None:
+        if self.config.quiet_stderr:
+            return
+        payload = json.dumps(health.model_dump(exclude_none=True), separators=(",", ":"))
+        sys.stderr.write(f"{READY_PREFIX}{payload}\n")
+        sys.stderr.flush()
+
+    def _configure_logging(self) -> None:
+        logging.basicConfig(
+            level=self.config.log_level,
+            format="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+            stream=sys.stderr,
+        )
+
+    def _install_signal_handlers(self) -> None:
+        loop = asyncio.get_running_loop()
+        try:
+            import signal
+
+            for sig in (signal.SIGINT, signal.SIGTERM):
+                loop.add_signal_handler(sig, lambda: self._shutdown_requested.set())
+        except (NotImplementedError, RuntimeError):
+            # Windows event-loop policies that lack add_signal_handler.
+            pass
+
+    @staticmethod
+    async def _connect_stdio() -> tuple[asyncio.StreamReader, asyncio.StreamWriter]:
+        loop = asyncio.get_running_loop()
+        reader = asyncio.StreamReader()
+        protocol = asyncio.StreamReaderProtocol(reader)
+        await loop.connect_read_pipe(lambda: protocol, sys.stdin)
+        transport, _ = await loop.connect_write_pipe(asyncio.streams.FlowControlMixin, sys.stdout)
+        writer = asyncio.StreamWriter(transport, protocol, reader, loop)
+        return reader, writer
+
+    @staticmethod
+    async def _maybe_drain(writer: Any) -> None:
+        drain = getattr(writer, "drain", None)
+        if drain is None:
+            return
+        result = drain()
+        if asyncio.iscoroutine(result):
+            await result
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _require_params(params: Any) -> dict[str, Any]:
+    if not isinstance(params, dict):
+        raise JsonRpcError("params must be an object", code=-32602, kind="invalid_params")
+    return params
+
+
+def _iso_now() -> str:
+    from datetime import datetime, timezone
+
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _new_session_id() -> str:
+    return f"sess_{uuid.uuid4().hex}"
+
+
+def _new_call_id() -> str:
+    return f"call_{uuid.uuid4().hex}"
+
+
+def _new_stream_id() -> str:
+    return f"str_{uuid.uuid4().hex}"
+
+
+def _coerce_messages(items: Any) -> list[LLMMessage]:
+    if not isinstance(items, list):
+        raise JsonRpcError("messages must be a list", code=-32602, kind="invalid_params")
+    out: list[LLMMessage] = []
+    for entry in items:
+        if not isinstance(entry, dict):
+            raise JsonRpcError(
+                "each message must be an object", code=-32602, kind="invalid_params"
+            )
+        role = entry.get("role")
+        if role not in {"system", "user", "assistant", "tool"}:
+            raise JsonRpcError(
+                f"invalid role: {role!r}", code=-32602, kind="invalid_params"
+            )
+        out.append(
+            LLMMessage(
+                role=role,  # type: ignore[arg-type]
+                content=str(entry.get("content", "")),
+                name=entry.get("name"),
+                tool_call_id=entry.get("toolCallId"),
+            )
+        )
+    return out
+
+
+def _build_provider_kwargs(params: dict[str, Any]) -> dict[str, Any]:
+    kwargs: dict[str, Any] = {}
+    if (tools := params.get("tools")) is not None:
+        kwargs["tools"] = tools
+    if (temp := params.get("temperature")) is not None:
+        kwargs["temperature"] = float(temp)
+    if (max_tokens := params.get("maxTokens")) is not None:
+        kwargs["max_tokens"] = int(max_tokens)
+    extra = params.get("providerOptions") or {}
+    if isinstance(extra, dict):
+        kwargs.update(extra)
+    return kwargs
+
+
+def default_llm_provider_factory(params: dict[str, Any]) -> LLMProvider:
+    """Construct an LLMProvider from a chat-stream request payload.
+
+    Embedders can override this by passing ``llm_provider_factory=`` to
+    ``Sidecar(...)`` — useful for tests or for sites that want to enforce a
+    single configured provider.
+    """
+
+    provider_kind = (params.get("provider") or "").strip().lower()
+    model = params.get("model")
+    if not model:
+        raise ValueError("model is required")
+    base_url = params.get("baseUrl") or params.get("base_url")
+    api_key = params.get("apiKey") or params.get("api_key") or ""
+
+    if provider_kind in {"openai", "openai_compat", "openai-compatible", "ollama"}:
+        from steerable_agent_runtime.llm import OpenAICompatProvider
+
+        return OpenAICompatProvider(
+            base_url=base_url or "https://api.openai.com/v1",
+            api_key=api_key,
+            model=str(model),
+        )
+    if provider_kind in {"anthropic", "claude"}:
+        from steerable_agent_runtime.llm import AnthropicProvider
+
+        return AnthropicProvider(api_key=api_key, model=str(model))
+
+    raise ValueError(f"unknown provider: {provider_kind!r}")

steerable_sidecar-0.1.0/src/steerable_sidecar.egg-info/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: steerable-sidecar
+Version: 0.1.0
+Summary: Steerable agent runtime sidecar — JSON-RPC over stdio.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: steerable-agent-protocol<1.0.0,>=0.1.0
+Requires-Dist: steerable-agent-harness<1.0.0,>=0.1.0
+Requires-Dist: steerable-agent-runtime<1.0.0,>=0.1.0
+
+# steerable-sidecar
+
+The portable Python entrypoint for the **steerable** framework. Designed to be
+spawned by an Electron / desktop host (or directly from a CLI) and addressed
+via stdio JSON-RPC 2.0.
+
+## Quick start
+
+```bash
+pip install steerable-sidecar
+python -m steerable_sidecar
+```
+
+Or use the console script:
+
+```bash
+steerable-sidecar
+```
+
+The process:
+
+1. Initializes the in-memory storage and a default tool router.
+2. Prints the **ready signal** on **stderr** as a single line:
+   `__SIDECAR_READY__:<json>` matching `spec/sidecar/SidecarHealth`.
+3. Begins reading JSON-RPC frames from stdin (one frame per line).
+4. Writes responses and notifications to stdout.
+
+See `spec/sidecar/README.md` for the full method/notification catalog.
+
+## Embedding
+
+```python
+import asyncio
+from steerable_sidecar import Sidecar
+
+async def main() -> None:
+    sidecar = Sidecar()
+    sidecar.tools.register(my_tool)
+    await sidecar.serve()
+
+asyncio.run(main())
+```

steerable_sidecar-0.1.0/src/steerable_sidecar.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/steerable_sidecar/__init__.py
+src/steerable_sidecar/__main__.py
+src/steerable_sidecar/sidecar.py
+src/steerable_sidecar.egg-info/PKG-INFO
+src/steerable_sidecar.egg-info/SOURCES.txt
+src/steerable_sidecar.egg-info/dependency_links.txt
+src/steerable_sidecar.egg-info/entry_points.txt
+src/steerable_sidecar.egg-info/requires.txt
+src/steerable_sidecar.egg-info/top_level.txt
+tests/test_sidecar_methods.py
+tests/test_sidecar_subprocess.py

steerable_sidecar-0.1.0/src/steerable_sidecar.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

steerable_sidecar-0.1.0/src/steerable_sidecar.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+steerable-sidecar = steerable_sidecar.__main__:main

steerable_sidecar-0.1.0/src/steerable_sidecar.egg-info/requires.txt

@@ -0,0 +1,4 @@
+pydantic>=2.10.0
+steerable-agent-protocol<1.0.0,>=0.1.0
+steerable-agent-harness<1.0.0,>=0.1.0
+steerable-agent-runtime<1.0.0,>=0.1.0

steerable_sidecar-0.1.0/src/steerable_sidecar.egg-info/top_level.txt

@@ -0,0 +1 @@
+steerable_sidecar

steerable_sidecar-0.1.0/tests/test_sidecar_methods.py

@@ -0,0 +1,327 @@
+"""Direct unit tests for the JSON-RPC method handlers (no real stdio)."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from steerable_sidecar import Sidecar
+
+
+@pytest.fixture
+def sidecar() -> Sidecar:
+    return Sidecar()
+
+
+async def _call(sidecar: Sidecar, method: str, params: dict | None = None, request_id: int = 1):
+    raw = json.dumps({"jsonrpc": "2.0", "id": request_id, "method": method, "params": params})
+    return await sidecar.server.handle_frame(raw)
+
+
+async def test_system_ping_returns_health(sidecar: Sidecar) -> None:
+    response = await _call(sidecar, "system.ping")
+    assert response["result"]["version"] == "0.1.0"
+    assert response["result"]["protocolVersion"] == "0.1.0"
+    assert response["result"]["loadedTools"] == 0
+
+
+async def test_session_create_then_resume(sidecar: Sidecar) -> None:
+    create = await _call(
+        sidecar,
+        "agent.session.create",
+        {"chatId": "chat-1", "userId": "user-1"},
+    )
+    session_id = create["result"]["sessionId"]
+    resume = await _call(sidecar, "agent.session.resume", {"sessionId": session_id})
+    assert resume["result"]["sessionId"] == session_id
+    assert resume["result"]["chatId"] == "chat-1"
+
+
+async def test_session_list_filters_by_user(sidecar: Sidecar) -> None:
+    await _call(sidecar, "agent.session.create", {"chatId": "c1", "userId": "u1"})
+    await _call(sidecar, "agent.session.create", {"chatId": "c2", "userId": "u2"})
+    listed = await _call(sidecar, "agent.session.list", {"userId": "u1"})
+    assert len(listed["result"]) == 1
+    assert listed["result"][0]["userId"] == "u1"
+
+
+async def test_tool_invoke_runs_registered_handler(sidecar: Sidecar) -> None:
+    async def echo(value: str = "default") -> dict:
+        return {"echoed": value}
+
+    sidecar.tools.register(echo)
+    response = await _call(
+        sidecar,
+        "tool.invoke",
+        {"name": "echo", "arguments": {"value": "hi"}},
+    )
+    assert response["result"]["success"] is True
+    assert response["result"]["data"]["value"] == {"echoed": "hi"}
+
+
+async def test_tool_invoke_missing_tool_returns_failure() -> None:
+    sidecar = Sidecar()
+    response = await _call(
+        sidecar,
+        "tool.invoke",
+        {"name": "missing"},
+    )
+    # Unknown tool is reported as ToolResult success=False, not as JSON-RPC error.
+    assert response["result"]["success"] is False
+
+
+async def test_tool_invoke_destructive_requires_consent() -> None:
+    sidecar = Sidecar()
+
+    async def delete_thing() -> None:
+        return None
+
+    sidecar.tools.register(delete_thing)
+    denied = await _call(sidecar, "tool.invoke", {"name": "delete_thing"})
+    assert denied["error"]["kind"] == "policy_denied"
+    granted = await _call(
+        sidecar,
+        "tool.invoke",
+        {"name": "delete_thing", "consentGranted": True},
+    )
+    assert granted["result"]["success"] is True
+
+
+async def test_unknown_method_returns_not_found(sidecar: Sidecar) -> None:
+    response = await _call(sidecar, "agent.nope")
+    assert response["error"]["kind"] == "method_not_found"
+
+
+async def test_invalid_params_object_returns_invalid_params(sidecar: Sidecar) -> None:
+    response = await _call(sidecar, "agent.session.create", None)
+    assert response["error"]["kind"] == "invalid_params"
+
+
+async def test_resume_unknown_session_returns_invalid_request(sidecar: Sidecar) -> None:
+    response = await _call(sidecar, "agent.session.resume", {"sessionId": "nope"})
+    assert response["error"]["kind"] == "invalid_request"
+
+
+async def test_config_get_set_round_trip(sidecar: Sidecar) -> None:
+    initial = await _call(sidecar, "config.get")
+    assert initial["result"]["logLevel"] == "INFO"
+    await _call(sidecar, "config.set", {"logLevel": "DEBUG"})
+    after = await _call(sidecar, "config.get")
+    assert after["result"]["logLevel"] == "DEBUG"
+
+
+async def test_health_snapshot_includes_pid_and_python(sidecar: Sidecar) -> None:
+    health = await sidecar.snapshot_health()
+    assert health.pid is not None
+    assert health.pythonVersion is not None
+    assert health.platform is not None
+
+
+# ---------------------------------------------------------------------------
+# agent.chat.stream
+# ---------------------------------------------------------------------------
+
+
+class _FakeProvider:
+    """Pure-Python LLMProvider used by the chat-stream tests.
+
+    Implements just enough of the Protocol surface (``stream``) and feeds a
+    deterministic sequence of chunks so we can assert the sidecar transport
+    behavior without touching a real network."""
+
+    name = "fake"
+    model = "fake-model"
+
+    def __init__(self, *, chunks=None, raise_on=None):
+        from steerable_agent_runtime.llm import LLMStreamChunk, LLMUsage
+
+        self._chunks = chunks or [
+            LLMStreamChunk(content_delta="Hello "),
+            LLMStreamChunk(content_delta="world"),
+            LLMStreamChunk(
+                finish_reason="stop",
+                usage=LLMUsage(prompt_tokens=10, completion_tokens=2, total_tokens=12),
+            ),
+        ]
+        self._raise_on = raise_on
+
+    async def complete(self, *args, **kwargs):
+        raise NotImplementedError
+
+    def stream(self, messages, **kwargs):
+        async def _gen():
+            for i, chunk in enumerate(self._chunks):
+                if self._raise_on is not None and i == self._raise_on:
+                    raise RuntimeError("upstream blew up")
+                yield chunk
+
+        return _gen()
+
+
+class _CapturingTransport:
+    """Drop-in for StdioJsonRpcTransport that just buffers notifications."""
+
+    def __init__(self):
+        self.events: list[tuple[str, dict]] = []
+
+    async def emit_notification(self, method: str, params: dict | None = None) -> None:
+        self.events.append((method, params or {}))
+
+    async def aclose(self) -> None:
+        return None
+
+
+@pytest.fixture
+def sidecar_with_fake_llm():
+    sidecar = Sidecar(llm_provider_factory=lambda params: _FakeProvider())
+    transport = _CapturingTransport()
+    sidecar._transport = transport  # type: ignore[attr-defined]
+    return sidecar, transport
+
+
+async def test_chat_stream_emits_chunks_then_done(sidecar_with_fake_llm) -> None:
+    sidecar, transport = sidecar_with_fake_llm
+    response = await _call(
+        sidecar,
+        "agent.chat.stream",
+        {
+            "provider": "openai_compat",
+            "model": "fake-model",
+            "messages": [{"role": "user", "content": "hi"}],
+        },
+    )
+    stream_id = response["result"]["streamId"]
+    assert stream_id.startswith("str_")
+
+    # Wait for the stream task to finish so all notifications are flushed.
+    task = sidecar._streams.get(stream_id) or next(iter(sidecar._streams.values()), None)
+    if task is not None:
+        await task
+
+    methods = [name for name, _ in transport.events]
+    assert methods.count("stream.chunk") == 3
+    assert methods.count("stream.done") == 1
+    assert methods[-1] == "stream.done"
+    assert transport.events[-1][1] == {"streamId": stream_id, "ok": True}
+    # finish_reason / usage propagate on the last chunk.
+    last_chunk = transport.events[-2][1]
+    assert last_chunk["finishReason"] == "stop"
+    assert last_chunk["usage"]["totalTokens"] == 12
+
+
+async def test_chat_stream_invalid_provider_returns_invalid_params() -> None:
+    def factory(_params):
+        raise ValueError("nope")
+
+    sidecar = Sidecar(llm_provider_factory=factory)
+    sidecar._transport = _CapturingTransport()  # type: ignore[attr-defined]
+    response = await _call(
+        sidecar,
+        "agent.chat.stream",
+        {"provider": "bogus", "model": "x", "messages": []},
+    )
+    assert response["error"]["kind"] == "invalid_params"
+
+
+async def test_chat_stream_invalid_message_role_rejected() -> None:
+    sidecar = Sidecar(llm_provider_factory=lambda params: _FakeProvider())
+    sidecar._transport = _CapturingTransport()  # type: ignore[attr-defined]
+    response = await _call(
+        sidecar,
+        "agent.chat.stream",
+        {
+            "provider": "openai_compat",
+            "model": "x",
+            "messages": [{"role": "wizard", "content": "spell"}],
+        },
+    )
+    assert response["error"]["kind"] == "invalid_params"
+
+
+async def test_chat_stream_emits_error_on_provider_failure() -> None:
+    sidecar = Sidecar(
+        llm_provider_factory=lambda params: _FakeProvider(raise_on=1),
+    )
+    transport = _CapturingTransport()
+    sidecar._transport = transport  # type: ignore[attr-defined]
+    response = await _call(
+        sidecar,
+        "agent.chat.stream",
+        {
+            "provider": "openai_compat",
+            "model": "fake-model",
+            "messages": [{"role": "user", "content": "hi"}],
+        },
+    )
+    stream_id = response["result"]["streamId"]
+    task = sidecar._streams.get(stream_id) or next(iter(sidecar._streams.values()), None)
+    if task is not None:
+        await task
+
+    methods = [name for name, _ in transport.events]
+    assert "stream.error" in methods
+    err_payload = next(p for n, p in transport.events if n == "stream.error")
+    assert err_payload["streamId"] == stream_id
+    assert err_payload["kind"] == "RuntimeError"
+
+
+async def test_chat_cancel_terminates_in_flight_stream() -> None:
+    import asyncio as _asyncio
+
+    from steerable_agent_runtime.llm import LLMStreamChunk
+
+    class _SlowProvider:
+        name = "slow"
+        model = "slow-model"
+
+        async def complete(self, *a, **k):
+            raise NotImplementedError
+
+        def stream(self, messages, **kwargs):
+            async def _gen():
+                yield LLMStreamChunk(content_delta="first")
+                # Block long enough that cancel can land.
+                await _asyncio.sleep(5.0)
+                yield LLMStreamChunk(content_delta="never")
+
+            return _gen()
+
+    sidecar = Sidecar(llm_provider_factory=lambda params: _SlowProvider())
+    transport = _CapturingTransport()
+    sidecar._transport = transport  # type: ignore[attr-defined]
+
+    response = await _call(
+        sidecar,
+        "agent.chat.stream",
+        {
+            "provider": "openai_compat",
+            "model": "slow-model",
+            "messages": [{"role": "user", "content": "hi"}],
+        },
+    )
+    stream_id = response["result"]["streamId"]
+    # Give the task one tick to start streaming.
+    await _asyncio.sleep(0)
+
+    cancel_response = await _call(sidecar, "agent.chat.cancel", {"streamId": stream_id})
+    # Successful void calls drop the `result` key via model_dump(exclude_none=True).
+    assert "error" not in cancel_response
+
+    # Drain any leftover task (it should have been cancelled).
+    leftover = sidecar._streams.get(stream_id)
+    if leftover is not None:
+        with pytest.raises(_asyncio.CancelledError):
+            await leftover
+
+    cancel_done = next(
+        (p for n, p in transport.events if n == "stream.done" and p.get("cancelled")),
+        None,
+    )
+    # Either a cancelled-stream.done was emitted, or the task was cancelled
+    # before the finally block ran. Both are acceptable; we just ensure no
+    # `never` chunk leaked.
+    chunk_deltas = [p.get("delta") for n, p in transport.events if n == "stream.chunk"]
+    assert "never" not in chunk_deltas
+    if cancel_done is not None:
+        assert cancel_done["streamId"] == stream_id

steerable_sidecar-0.1.0/tests/test_sidecar_subprocess.py

@@ -0,0 +1,97 @@
+"""End-to-end smoke test: spawn the sidecar subprocess and round-trip a frame."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+
+import pytest
+
+
+pytestmark = pytest.mark.skipif(
+    os.environ.get("CI_SKIP_SIDECAR_SUBPROCESS") == "1",
+    reason="explicitly disabled via CI_SKIP_SIDECAR_SUBPROCESS",
+)
+
+
+async def _spawn_sidecar() -> asyncio.subprocess.Process:
+    return await asyncio.create_subprocess_exec(
+        sys.executable,
+        "-m",
+        "steerable_sidecar",
+        "--log-level",
+        "ERROR",
+        stdin=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+
+
+async def _read_ready_marker(proc: asyncio.subprocess.Process) -> dict:
+    assert proc.stderr is not None
+    while True:
+        line = await asyncio.wait_for(proc.stderr.readline(), timeout=10.0)
+        if not line:
+            raise RuntimeError("sidecar exited before ready marker")
+        decoded = line.decode("utf-8").rstrip()
+        if decoded.startswith("__SIDECAR_READY__:"):
+            return json.loads(decoded.removeprefix("__SIDECAR_READY__:"))
+
+
+async def _read_lifecycle_ready(proc: asyncio.subprocess.Process) -> dict:
+    assert proc.stdout is not None
+    while True:
+        line = await asyncio.wait_for(proc.stdout.readline(), timeout=10.0)
+        if not line:
+            raise RuntimeError("sidecar exited before lifecycle.ready notification")
+        payload = json.loads(line)
+        if payload.get("method") == "lifecycle.ready":
+            return payload
+
+
+async def _round_trip(proc: asyncio.subprocess.Process, request: dict) -> dict:
+    assert proc.stdin is not None and proc.stdout is not None
+    proc.stdin.write((json.dumps(request) + "\n").encode("utf-8"))
+    await proc.stdin.drain()
+    while True:
+        line = await asyncio.wait_for(proc.stdout.readline(), timeout=10.0)
+        if not line:
+            raise RuntimeError("sidecar closed without responding")
+        payload = json.loads(line)
+        if payload.get("id") == request.get("id"):
+            return payload
+
+
+async def test_subprocess_full_handshake_and_ping() -> None:
+    proc = await _spawn_sidecar()
+    try:
+        ready = await _read_ready_marker(proc)
+        assert ready["status"] in {"ok", "starting"}
+        assert ready["protocolVersion"] == "0.1.0"
+
+        lifecycle = await _read_lifecycle_ready(proc)
+        assert lifecycle["params"]["protocolVersion"] == "0.1.0"
+        assert lifecycle["params"]["pid"] > 0
+
+        response = await _round_trip(
+            proc,
+            {"jsonrpc": "2.0", "id": 1, "method": "system.ping"},
+        )
+        assert response["result"]["protocolVersion"] == "0.1.0"
+
+        # graceful shutdown
+        await _round_trip(
+            proc, {"jsonrpc": "2.0", "id": 2, "method": "system.shutdown"}
+        )
+    finally:
+        try:
+            proc.stdin.close()
+        except Exception:
+            pass
+        try:
+            await asyncio.wait_for(proc.wait(), timeout=5.0)
+        except asyncio.TimeoutError:
+            proc.kill()
+            await proc.wait()