harness-runtime 0.1.0__tar.gz

harness_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: harness-runtime
+Version: 0.1.0
+Summary: LangGraph Agent Execution Engine — stdio subprocess pattern
+Author: Bizmatters Team
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: deepagents>=0.2.7
+Requires-Dist: langgraph>=1.0.0
+Requires-Dist: langgraph-checkpoint-postgres>=3.0.0
+Requires-Dist: langchain>=1.0.0
+Requires-Dist: langchain-openai>=0.3.0
+Requires-Dist: langchain-anthropic>=1.0.0
+Requires-Dist: langsmith>=0.2.0
+Requires-Dist: psycopg[binary,pool]>=3.2.0
+Requires-Dist: structlog>=24.4.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3.0; extra == "dev"
+Requires-Dist: black>=24.1.1; extra == "dev"
+Requires-Dist: ruff>=0.1.13; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+
+# harness-runtime
+
+LangGraph agent execution engine designed for the **stdio subprocess pattern** — spawned as a child process by the Waypoint SDK, communicating via NDJSON over stdin/stdout using the **LiteLLM frame protocol**.
+
+## Overview
+
+```
+Waypoint SDK → spawn → harness-runtime → stdin NDJSON → turn frames → stdout NDJSON → exit
+```
+
+- **Execution**: LangGraph DAG execution with PostgreSQL checkpointing
+- **Protocol**: LiteLLM-compatible NDJSON frame protocol over stdio
+- **Persistence**: LangGraph `PostgresSaver` for multi-turn conversations
+- **No network, no K8s, no Redis**: Runs as a local subprocess
+
+## Quick Start
+
+```bash
+# Install
+pip install .
+
+# Run (expects NDJSON on stdin)
+DATABASE_URL=postgresql://user:pass@localhost:5432/db harness-runtime
+```
+
+### Example NDJSON session
+
+```bash
+echo '{"type":"control_request","request_id":"req_1","request":{"subtype":"initialize","agent_definition":{...},"input_payload":{"messages":[]}}}' | \
+DATABASE_URL=postgresql://user:pass@localhost:5432/db harness-runtime
+```
+
+## Protocol
+
+See [ADR-003](../waypoint/docs/adr/003-harness-runtime-as-stdio-subprocess.md) for the full protocol specification.
+
+### Frame Types (SDK → Server)
+
+| Type | Purpose |
+|------|---------|
+| `control_request {initialize}` | Build LangGraph, init PostgresSaver |
+| `control_request {interrupt}` | Cancel in-flight turn |
+| `user {message}` | Each turn — runs graph with the input |
+
+### Frame Types (Server → SDK)
+
+| Type | Purpose |
+|------|---------|
+| `control_response {success}` | Ack for initialize/interrupt |
+| `system {init}` | Start of turn — model, tools |
+| `assistant {content}` | Complete assistant message with `text` / `tool_use` blocks |
+| `user {content}` | Echo of internal tool results (`tool_result` blocks) |
+| `stream_event {content_block_delta}` | Streaming LLM token deltas |
+| `result` | **Terminates the turn** — `success`, `error_max_turns`, or `error_during_execution` |
+
+## Architecture
+
+```
+harness-runtime/
+├── cli.py                      # CLI entry point — stdin NDJSON loop
+├── core/
+│   ├── builder.py              # GraphBuilder — builds LangGraph DAG
+│   ├── event_publisher.py      # StdioPublisher — LiteLLM frame emitter
+│   ├── executor.py             # ExecutionManager — runs graph, maps events → frames
+│   ├── session.py              # Session — multi-turn lifecycle
+│   ├── model_factory.py        # LLM model creation
+│   ├── model_identifier.py     # "provider:model" string builder
+│   ├── subagent_builder.py     # Specialist agent compilation
+│   ├── tool_loader.py          # Dynamic tool loading from script defs
+│   └── state_schema_builder.py # Dynamic AgentState subclass creation
+├── models/
+│   ├── __init__.py
+│   └── frames.py               # LiteLLM frame dataclasses + content blocks
+├── migrations/                  # PostgreSQL schema migrations (checkpointer)
+├── scripts/ci/run.sh           # Docker entrypoint
+├── Dockerfile
+└── pyproject.toml
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DATABASE_URL` | Yes | PostgreSQL connection string for LangGraph checkpointer |
+| `USE_MOCK_LLM` | No | `true` to use mock LLM (default: `false`) |
+| `LLM_MODEL_NAME` | No | Model name for real LLM calls (default: `gpt-4o-mini`) |
+
+LLM provider API keys are read from environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.) or from Agent Vault via proxy env vars.
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Code quality
+black .
+ruff check .
+mypy .
+
+# Testing
+pytest
+```
+
+## References
+
+- [ADR-003](../waypoint/docs/adr/003-harness-runtime-as-stdio-subprocess.md)
+- [LiteLLM Frame Protocol](../waypoint/archived/agents/lite-harness/src/sdk/PROTOCOL.md)
+- [LangGraph Documentation](https://python.langchain.com/docs/langgraph)

harness_runtime-0.1.0/README.md

@@ -0,0 +1,109 @@
+# harness-runtime
+
+LangGraph agent execution engine designed for the **stdio subprocess pattern** — spawned as a child process by the Waypoint SDK, communicating via NDJSON over stdin/stdout using the **LiteLLM frame protocol**.
+
+## Overview
+
+```
+Waypoint SDK → spawn → harness-runtime → stdin NDJSON → turn frames → stdout NDJSON → exit
+```
+
+- **Execution**: LangGraph DAG execution with PostgreSQL checkpointing
+- **Protocol**: LiteLLM-compatible NDJSON frame protocol over stdio
+- **Persistence**: LangGraph `PostgresSaver` for multi-turn conversations
+- **No network, no K8s, no Redis**: Runs as a local subprocess
+
+## Quick Start
+
+```bash
+# Install
+pip install .
+
+# Run (expects NDJSON on stdin)
+DATABASE_URL=postgresql://user:pass@localhost:5432/db harness-runtime
+```
+
+### Example NDJSON session
+
+```bash
+echo '{"type":"control_request","request_id":"req_1","request":{"subtype":"initialize","agent_definition":{...},"input_payload":{"messages":[]}}}' | \
+DATABASE_URL=postgresql://user:pass@localhost:5432/db harness-runtime
+```
+
+## Protocol
+
+See [ADR-003](../waypoint/docs/adr/003-harness-runtime-as-stdio-subprocess.md) for the full protocol specification.
+
+### Frame Types (SDK → Server)
+
+| Type | Purpose |
+|------|---------|
+| `control_request {initialize}` | Build LangGraph, init PostgresSaver |
+| `control_request {interrupt}` | Cancel in-flight turn |
+| `user {message}` | Each turn — runs graph with the input |
+
+### Frame Types (Server → SDK)
+
+| Type | Purpose |
+|------|---------|
+| `control_response {success}` | Ack for initialize/interrupt |
+| `system {init}` | Start of turn — model, tools |
+| `assistant {content}` | Complete assistant message with `text` / `tool_use` blocks |
+| `user {content}` | Echo of internal tool results (`tool_result` blocks) |
+| `stream_event {content_block_delta}` | Streaming LLM token deltas |
+| `result` | **Terminates the turn** — `success`, `error_max_turns`, or `error_during_execution` |
+
+## Architecture
+
+```
+harness-runtime/
+├── cli.py                      # CLI entry point — stdin NDJSON loop
+├── core/
+│   ├── builder.py              # GraphBuilder — builds LangGraph DAG
+│   ├── event_publisher.py      # StdioPublisher — LiteLLM frame emitter
+│   ├── executor.py             # ExecutionManager — runs graph, maps events → frames
+│   ├── session.py              # Session — multi-turn lifecycle
+│   ├── model_factory.py        # LLM model creation
+│   ├── model_identifier.py     # "provider:model" string builder
+│   ├── subagent_builder.py     # Specialist agent compilation
+│   ├── tool_loader.py          # Dynamic tool loading from script defs
+│   └── state_schema_builder.py # Dynamic AgentState subclass creation
+├── models/
+│   ├── __init__.py
+│   └── frames.py               # LiteLLM frame dataclasses + content blocks
+├── migrations/                  # PostgreSQL schema migrations (checkpointer)
+├── scripts/ci/run.sh           # Docker entrypoint
+├── Dockerfile
+└── pyproject.toml
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DATABASE_URL` | Yes | PostgreSQL connection string for LangGraph checkpointer |
+| `USE_MOCK_LLM` | No | `true` to use mock LLM (default: `false`) |
+| `LLM_MODEL_NAME` | No | Model name for real LLM calls (default: `gpt-4o-mini`) |
+
+LLM provider API keys are read from environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.) or from Agent Vault via proxy env vars.
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Code quality
+black .
+ruff check .
+mypy .
+
+# Testing
+pytest
+```
+
+## References
+
+- [ADR-003](../waypoint/docs/adr/003-harness-runtime-as-stdio-subprocess.md)
+- [LiteLLM Frame Protocol](../waypoint/archived/agents/lite-harness/src/sdk/PROTOCOL.md)
+- [LangGraph Documentation](https://python.langchain.com/docs/langgraph)

harness_runtime-0.1.0/cli.py

@@ -0,0 +1,116 @@
+import json
+import os
+import sys
+from pathlib import Path
+from typing import NoReturn
+
+from dotenv import load_dotenv
+
+from core.event_publisher import StdioPublisher
+from core.executor import ExecutionManager
+from core.session import Session
+
+env_path = Path(__file__).parent / ".env"
+load_dotenv(dotenv_path=env_path)
+
+
+def main() -> None:
+    database_url = os.getenv("DATABASE_URL")
+    if not database_url:
+        _error_exit("DATABASE_URL environment variable is required", 2)
+
+    session: Session | None = None
+    execution_manager: ExecutionManager | None = None
+    publisher = StdioPublisher()
+
+    try:
+        execution_manager = ExecutionManager(
+            postgres_connection_string=database_url,
+            publisher=publisher,
+        )
+
+        for line in sys.stdin:
+            line = line.strip()
+            if not line:
+                continue
+
+            try:
+                msg = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            msg_type = msg.get("type")
+
+            if msg_type == "control_request":
+                request = msg.get("request", {})
+                subtype = request.get("subtype")
+                request_id = msg.get("request_id", "")
+
+                if subtype == "initialize":
+                    agent_definition = request.get("agent_definition", {})
+                    input_payload = request.get("input_payload", {})
+
+                    session = Session(
+                        agent_definition=agent_definition,
+                        input_payload=input_payload,
+                        execution_manager=execution_manager,
+                        publisher=publisher,
+                    )
+                    session.initialize()
+
+                    publisher.publish_control_response(
+                        request_id=request_id,
+                        session_id=session.session_id,
+                    )
+
+                elif subtype == "interrupt":
+                    publisher.publish_control_response(
+                        request_id=request_id,
+                    )
+
+            elif msg_type == "user":
+                if session is None:
+                    publisher.publish_control_response(
+                        request_id="",
+                        subtype="error",
+                        error="Session not initialized",
+                    )
+                    continue
+
+                try:
+                    user_content = ""
+                    user_msg = msg.get("message", {})
+                    raw_content = user_msg.get("content", "")
+                    if isinstance(raw_content, str):
+                        user_content = raw_content
+                    elif isinstance(raw_content, list):
+                        texts = [
+                            b.get("text", "") for b in raw_content
+                            if isinstance(b, dict) and b.get("type") == "text"
+                        ]
+                        user_content = " ".join(texts)
+
+                    session.run_turn(user_content=user_content)
+                except Exception as e:
+                    publisher.publish_result(
+                        session_id=session.session_id,
+                        subtype="error_during_execution",
+                        is_error=True,
+                        result=str(e),
+                    )
+                    sys.exit(1)
+
+    except KeyboardInterrupt:
+        pass
+    finally:
+        if execution_manager:
+            execution_manager.close()
+
+
+def _error_exit(message: str, code: int = 1) -> NoReturn:
+    print(message, file=sys.stderr)
+    sys.exit(code)
+
+
+if __name__ == "__main__":
+    main()

harness_runtime-0.1.0/core/__init__.py

@@ -0,0 +1,47 @@
+"""Core business logic for graph building and execution.
+
+This module provides the main entry point for the agent executor service.
+The implementation follows a flat, modular structure:
+
+Flat Structure:
+    - builder.py: Main GraphBuilder class (entry point)
+    - model_identifier.py: Model identifier creation
+    - subagent_builder.py: Subagent compilation logic
+    - tool_loader.py: Tool loading logic
+
+Usage:
+    from core import GraphBuilder
+
+    builder = GraphBuilder()
+    agent = builder.build_from_definition(definition)
+
+Or use the modular functions directly:
+    from core import (
+        load_tools_from_definition,
+        create_model_identifier,
+        build_subagent
+    )
+"""
+
+# Main API
+from core.builder import GraphBuilder, GraphBuilderError
+from core.model_identifier import create_model_identifier
+from core.subagent_builder import SubAgentCompilationError, build_subagent
+
+# Modular functions
+from core.tool_loader import ToolLoadingError, load_tools_from_definition
+
+__all__ = [
+    # Main API
+    "GraphBuilder",
+    "GraphBuilderError",
+
+    # Modular functions
+    "load_tools_from_definition",
+    "create_model_identifier",
+    "build_subagent",
+
+    # Exceptions
+    "ToolLoadingError",
+    "SubAgentCompilationError"
+]