runtm-shared

Canonical contracts for Runtm: manifest schema, types, errors, and shared utilities.

Installation

pip install runtm-shared

Contents

Core Modules

Session & Sandbox Types

Discovery & Requests

Infrastructure

Telemetry

Usage

Types and State Machine

from runtm_shared.types import (
    DeploymentState,
    can_transition,
    MachineTier,
    # Session types
    Session,
    SessionState,
    SessionMode,
    SandboxConfig,
    AgentType,
)

# Check if state transition is valid
if can_transition(DeploymentState.BUILDING, DeploymentState.DEPLOYING):
    # proceed with transition
    pass

Manifest Validation

from runtm_shared.manifest import Manifest

# Load and validate runtm.yaml
manifest = Manifest.from_yaml("runtm.yaml")
print(manifest.name, manifest.template, manifest.runtime)

Error Handling

from runtm_shared.errors import (
    RuntmError,
    ManifestValidationError,
    DeploymentError,
    AuthenticationError,
)

try:
    # ... operation
except ManifestValidationError as e:
    print(f"Invalid manifest: {e}")
    print(f"Recovery: {e.recovery_hint}")

ID Generation

from runtm_shared.ids import generate_deployment_id

# Generate deterministic deployment ID
dep_id = generate_deployment_id(project_name="my-api", user_id="usr_123")
# Returns: dep_abc123...

Session Types

from runtm_shared.types import (
    Session,
    SessionState,
    SessionMode,
    AgentType,
    SandboxConfig,
)

# Create a session config
config = SandboxConfig(
    agent=AgentType.CLAUDE_CODE,
    template="backend-service",
)

# Session states
SessionState.RUNNING
SessionState.STOPPED
SessionState.DESTROYED

# Session modes
SessionMode.AUTOPILOT   # Agent controlled via prompts
SessionMode.INTERACTIVE # User controls agent manually

Discovery Metadata

from runtm_shared.discovery import DiscoveryMetadata

# Load discovery metadata
discovery = DiscoveryMetadata.from_yaml("runtm.discovery.yaml")
print(discovery.description)
print(discovery.tags)
print(discovery.capabilities)

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy runtm_shared

Package Structure

runtm_shared/
├── __init__.py
├── types.py          # Core types and state machine
├── manifest.py       # Manifest schema (Pydantic)
├── errors.py         # Error hierarchy
├── ids.py            # ID generation
├── env.py            # Environment handling
├── discovery.py      # Discovery metadata
├── requests.py       # Agent requests
├── lockfiles.py      # Lockfile validation
├── urls.py           # URL generation
├── redis.py          # Redis utilities
├── deploy_tracking.py # Deployment tracking
├── storage/
│   └── base.py       # Storage interface
├── dns/
│   ├── base.py       # DNS provider interface
│   └── cloudflare.py # Cloudflare implementation
└── telemetry/
    ├── base.py       # Telemetry base
    ├── service.py    # Telemetry service
    └── ...           # Other telemetry modules