apsimo 1.3.0__py3-none-any.whl

apsimo/__init__.py

@@ -0,0 +1,38 @@
+"""Apsimo cognition server for agent runtimes.
+
+A standalone FastAPI server that agent hosts (Hermes plugin, MCP harnesses,
+REST integrations) mount via the ``/v1/host`` API surface.
+"""
+
+from pathlib import Path
+import os
+from .environment import apply_environment_aliases
+
+apply_environment_aliases()
+
+try:  # single source of truth: the installed package metadata (pyproject)
+    from importlib.metadata import version as _pkg_version
+    __version__ = _pkg_version("apsimo")
+except Exception:  # editable/unbuilt checkouts without installed metadata
+    __version__ = "0.0.0+unknown"
+
+
+def get_state_dir() -> Path:
+    """Return the selected state directory without moving existing state.
+    
+    Priority:
+    1. APSIMO_STATE_DIR or legacy COLONY_STATE_DIR (explicit override)
+    2. ~/.colony/data (retained unconfigured-library compatibility default)
+
+    Guided setup selects its explicit private instance directory. This fallback
+    stays aligned with older independently configured storage readers.
+    
+    Creates the directory if it doesn't exist.
+    """
+    explicit = os.environ.get("APSIMO_STATE_DIR") or os.environ.get("COLONY_STATE_DIR")
+    if explicit:
+        path = Path(explicit)
+    else:
+        path = Path.home() / ".colony" / "data"
+    path.mkdir(parents=True, exist_ok=True)
+    return path

apsimo/__main__.py

@@ -0,0 +1,6 @@
+"""Run the same CLI used by the installed ``apsimo`` command."""
+from apsimo.cli import main
+
+
+if __name__ == "__main__":
+    main()

apsimo/agent/__init__.py

@@ -0,0 +1,6 @@
+"""Colony Agent SDK — Python client for remote agents."""
+
+from .client import AgentClient
+from .models import AgentConfig, NodeCertificate
+
+__all__ = ["AgentClient", "AgentConfig", "NodeCertificate"]

apsimo/agent/client.py

@@ -0,0 +1,276 @@
+"""Colony Agent Client — WebSocket client for remote agents.
+
+Usage:
+    from colony.agent import AgentClient
+
+    client = AgentClient(config_path="~/.colony/agent.json")
+
+    @client.on_initiative
+    async def handle_initiative(initiative):
+        print(f"Received: {initiative['description']}")
+        await client.acknowledge(initiative["id"])
+        result = await process_initiative(initiative)
+        await client.complete(initiative["id"], result=result)
+
+    await client.start()
+"""
+
+import asyncio
+import json
+import time
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional
+
+import websockets
+
+from .models import AgentConfig
+
+
+class AgentClient:
+    """WebSocket client for remote Colony agents.
+
+    Handles:
+    - WebSocket connection with auth
+    - Heartbeat loop
+    - Initiative delivery
+    - Reconnection with exponential backoff
+    """
+
+    def __init__(
+        self,
+        config_path: str = "~/.colony/agent.json",
+        config: Optional[AgentConfig] = None,
+    ) -> None:
+        """Initialize agent client.
+
+        Args:
+            config_path: Path to agent config file
+            config: Optional pre-loaded config (skips file read)
+        """
+        if config:
+            self.config = config
+        else:
+            config_file = Path(config_path).expanduser()
+            if not config_file.exists():
+                raise FileNotFoundError(f"Agent config not found: {config_file}")
+            self.config = AgentConfig.parse_file(config_file)
+
+        self._ws: Optional[websockets.WebSocketClientProtocol] = None
+        self._running = False
+        self._seq = 0
+        self._pending_acks: Dict[int, asyncio.Future] = {}
+        self._handlers: Dict[str, Callable] = {
+            "initiative": None,
+            "config": None,
+            "disconnect": None,
+        }
+
+        # Reconnection state
+        self._reconnect_delay = 1.0
+        self._max_reconnect_delay = 60.0
+
+    def on_initiative(self, handler: Callable) -> Callable:
+        """Register initiative handler."""
+        self._handlers["initiative"] = handler
+        return handler
+
+    def on_config(self, handler: Callable) -> Callable:
+        """Register config update handler."""
+        self._handlers["config"] = handler
+        return handler
+
+    def on_disconnect(self, handler: Callable) -> Callable:
+        """Register disconnect handler."""
+        self._handlers["disconnect"] = handler
+        return handler
+
+    async def start(self) -> None:
+        """Connect to Colony and start message loop."""
+        if not self.config.websocket_url:
+            raise ValueError("No websocket_url in config (local mode?)")
+
+        self._running = True
+
+        while self._running:
+            try:
+                await self._connect()
+                await self._message_loop()
+            except Exception as e:
+                if not self._running:
+                    break
+                print(f"Connection error: {e}, reconnecting in {self._reconnect_delay}s...")
+                await asyncio.sleep(self._reconnect_delay)
+                self._reconnect_delay = min(
+                    self._reconnect_delay * 2,
+                    self._max_reconnect_delay,
+                )
+
+    async def stop(self) -> None:
+        """Disconnect from Colony."""
+        self._running = False
+        if self._ws:
+            await self._ws.close()
+
+    async def _connect(self) -> None:
+        """Establish WebSocket connection with auth."""
+        headers = {}
+        if self.config.node_cert:
+            # Sign challenge with node cert
+            headers["Authorization"] = f"Bearer {self.config.node_cert.signature}"
+        headers["X-Agent-Id"] = self.config.agent_id
+
+        self._ws = await websockets.connect(
+            self.config.websocket_url,
+            extra_headers=headers,
+            ping_interval=30,
+            ping_timeout=10,
+        )
+        self._reconnect_delay = 1.0  # Reset on successful connection
+        print(f"Connected to Colony: {self.config.websocket_url}")
+
+        # Start heartbeat task
+        asyncio.create_task(self._heartbeat_loop())
+
+    async def _message_loop(self) -> None:
+        """Process incoming messages."""
+        if not self._ws:
+            return
+
+        async for message in self._ws:
+            try:
+                data = json.loads(message)
+                await self._handle_message(data)
+            except json.JSONDecodeError:
+                print(f"Invalid JSON: {message}")
+            except Exception as e:
+                print(f"Error handling message: {e}")
+
+    async def _handle_message(self, data: Dict[str, Any]) -> None:
+        """Handle incoming message."""
+        msg_type = data.get("type")
+        seq = data.get("seq")
+
+        # Handle ACKs for our messages
+        if msg_type == "ack" and seq in self._pending_acks:
+            self._pending_acks[seq].set_result(data)
+            return
+
+        # Handle initiative delivery
+        if msg_type == "initiative":
+            if self._handlers["initiative"]:
+                await self._handlers["initiative"](data.get("initiative", {}))
+            # Auto-ack receipt
+            await self._send_ack(seq)
+
+        # Handle config update
+        elif msg_type == "config":
+            if self._handlers["config"]:
+                await self._handlers["config"](data.get("config", {}))
+
+        # Handle disconnect notice
+        elif msg_type == "disconnect":
+            if self._handlers["disconnect"]:
+                await self._handlers["disconnect"](data.get("reason", "unknown"))
+            await self.stop()
+
+        # Handle ping
+        elif msg_type == "ping":
+            await self._send({"type": "pong", "seq": seq})
+
+    async def _heartbeat_loop(self) -> None:
+        """Send periodic heartbeats."""
+        # The colony side tracks current_assignments via the agents table
+        # (incremented/decremented when initiatives are assigned/completed),
+        # so the heartbeat does not need to carry it — the server only uses
+        # this message to update last_seen_at.
+        while self._running and self._ws:
+            try:
+                await self._send({
+                    "type": "heartbeat",
+                    "status": "online",
+                })
+                await asyncio.sleep(30)
+            except Exception:
+                break
+
+    async def _send(self, message: Dict[str, Any]) -> bool:
+        """Send message with sequencing."""
+        if not self._ws:
+            return False
+
+        self._seq += 1
+        message["seq"] = self._seq
+
+        try:
+            await self._ws.send(json.dumps(message))
+            return True
+        except Exception as e:
+            print(f"Send error: {e}")
+            return False
+
+    async def _send_ack(self, seq: Optional[int]) -> None:
+        """Send acknowledgment."""
+        await self._send({"type": "ack", "ack_seq": seq})
+
+    # --- Public API ---
+
+    async def acknowledge(self, initiative_id: str) -> bool:
+        """Acknowledge initiative receipt."""
+        return await self._send({
+            "type": "initiative_ack",
+            "initiative_id": initiative_id,
+        })
+
+    async def complete(
+        self,
+        initiative_id: str,
+        result: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> bool:
+        """Mark initiative as completed."""
+        return await self._send({
+            "type": "initiative_complete",
+            "initiative_id": initiative_id,
+            "result": result,
+            "result_metadata": metadata or {},
+        })
+
+    async def fail(
+        self,
+        initiative_id: str,
+        reason: str,
+        retry: bool = True,
+    ) -> bool:
+        """Mark initiative as failed."""
+        return await self._send({
+            "type": "initiative_fail",
+            "initiative_id": initiative_id,
+            "reason": reason,
+            "retry": retry,
+        })
+
+    async def delegate(
+        self,
+        initiative_id: str,
+        reason: str,
+        target_agent_id: Optional[str] = None,
+    ) -> bool:
+        """Delegate initiative to another agent."""
+        return await self._send({
+            "type": "initiative_delegate",
+            "initiative_id": initiative_id,
+            "reason": reason,
+            "target_agent_id": target_agent_id,
+        })
+
+    async def update_status(
+        self,
+        status: str = "online",
+        current_assignments: int = 0,
+    ) -> bool:
+        """Update agent status."""
+        return await self._send({
+            "type": "status_update",
+            "status": status,
+            "current_assignments": current_assignments,
+        })

apsimo/agent/models.py

@@ -0,0 +1,46 @@
+"""Agent SDK models."""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class NodeCertificate(BaseModel):
+    """Node certificate structure."""
+
+    colony_id: str
+    node_id: str
+    public_key: Optional[str] = None  # node_public_key_ed25519 in spec
+    issued_at: str  # ISO timestamp
+    expires_at: Optional[str] = None  # ISO timestamp
+    signature: str
+
+
+class AgentConfig(BaseModel):
+    """Agent configuration file schema.
+
+    This is the structure saved to ~/.colony/agent.json after
+    running `colony agent connect`.
+    """
+
+    agent_id: str
+    node_id: str
+    colony_id: str
+    websocket_url: Optional[str] = None  # For remote mode
+    name: str
+    capabilities: List[str] = Field(default_factory=list)
+    is_primary: bool = False
+    max_concurrent: int = 5
+    node_cert: Optional[NodeCertificate] = None
+    connection_mode: str = "remote"
+    registered_at: Optional[str] = None  # ISO timestamp
+
+    # Optional fields
+    priority: int = 1
+    excluded_types: List[str] = Field(default_factory=list)
+    included_types: List[str] = Field(default_factory=list)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+    class Config:
+        extra = "allow"  # Forward compatibility

apsimo/agents/__init__.py

@@ -0,0 +1,20 @@
+"""Multi-agent support for Colony.
+
+Provides:
+- AgentStore: Registry of connected agents
+- InviteStore: Setup code management
+- WebSocketManager: Remote agent connections
+"""
+
+from .models import Agent, AgentStatus, AgentMetadata
+from .store import AgentStore, InviteStore
+from .websocket import WebSocketManager
+
+__all__ = [
+    "Agent",
+    "AgentStatus",
+    "AgentMetadata",
+    "AgentStore",
+    "InviteStore",
+    "WebSocketManager",
+]

apsimo/agents/models.py

@@ -0,0 +1,264 @@
+"""Agent data models for multi-agent Colony.
+
+Defines:
+- AgentStatus enum
+- AgentMetadata schema
+- Agent dataclass
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class AgentStatus(str, Enum):
+    """Agent status values."""
+
+    ONLINE = "online"
+    OFFLINE = "offline"
+    BUSY = "busy"
+    SUSPENDED = "suspended"
+    REVOKED = "revoked"
+
+    def is_active(self) -> bool:
+        """Can this agent receive assignments?"""
+        return self in (AgentStatus.ONLINE, AgentStatus.BUSY)
+
+    def can_reconnect(self) -> bool:
+        """Can this agent reconnect to Colony?"""
+        return self != AgentStatus.REVOKED
+
+
+@dataclass
+class AgentMetadata:
+    """Structured metadata about an agent's environment.
+
+    Standard fields:
+    - hostname: Machine hostname
+    - platform: OS platform (darwin, linux, windows)
+    - version: Colony version
+    - harness: Which harness (openclaw, claude-code, codex, crush)
+    - {harness}_version: Harness version
+    - python_version: Python version (for Python-based harnesses)
+    - started_at: ISO timestamp when agent started
+    - tz: IANA timezone
+    """
+
+    hostname: Optional[str] = None
+    platform: Optional[str] = None
+    version: Optional[str] = None
+    harness: Optional[str] = None
+    started_at: Optional[str] = None
+    tz: Optional[str] = None
+    last_connection_ip: Optional[str] = None
+    last_connection_ip_ts: Optional[str] = None
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "AgentMetadata":
+        """Create from dict, handling unknown fields."""
+        known = {
+            "hostname",
+            "platform",
+            "version",
+            "harness",
+            "started_at",
+            "tz",
+            "last_connection_ip",
+            "last_connection_ip_ts",
+        }
+        return cls(
+            hostname=data.get("hostname"),
+            platform=data.get("platform"),
+            version=data.get("version"),
+            harness=data.get("harness"),
+            started_at=data.get("started_at"),
+            tz=data.get("tz"),
+            last_connection_ip=data.get("last_connection_ip"),
+            last_connection_ip_ts=data.get("last_connection_ip_ts"),
+            extra={k: v for k, v in data.items() if k not in known},
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dict for JSON serialization."""
+        result = {}
+        if self.hostname:
+            result["hostname"] = self.hostname
+        if self.platform:
+            result["platform"] = self.platform
+        if self.version:
+            result["version"] = self.version
+        if self.harness:
+            result["harness"] = self.harness
+        if self.started_at:
+            result["started_at"] = self.started_at
+        if self.tz:
+            result["tz"] = self.tz
+        if self.last_connection_ip:
+            result["last_connection_ip"] = self.last_connection_ip
+        if self.last_connection_ip_ts:
+            result["last_connection_ip_ts"] = self.last_connection_ip_ts
+        result.update(self.extra)
+        return result
+
+    def get_harness_version(self) -> Optional[str]:
+        """Get harness-specific version field."""
+        if not self.harness:
+            return None
+        return self.extra.get(f"{self.harness}_version")
+
+
+@dataclass
+class Agent:
+    """A connected agent (Hermes host, Claude Code, worker daemon, etc.).
+
+    Attributes:
+        agent_id: Unique identifier (UUID)
+        node_id: Device node ID
+        colony_id: Parent Colony ID
+        name: Human-readable name (e.g., "node-a", "workstation")
+        connection_mode: "local" (HTTP) or "remote" (WebSocket)
+        gateway_url: For local mode, URL to push initiatives
+        websocket_connected: For remote mode, is WebSocket active?
+        capabilities: What can this agent do? (messaging, calendar, coding)
+        is_primary: Preferred for user-facing initiatives
+        priority: 0=backup, 1=normal, 2=high
+        max_concurrent: Max simultaneous initiative assignments
+        max_initiatives_per_hour: Rate limit
+        excluded_types: Initiative types to skip
+        included_types: Only these types (if set)
+        status: Current status
+        current_assignments: Count of active assignments
+        last_seen_at: Last heartbeat/disconnect time
+        metadata: Environment info
+        registered_at: When agent was registered
+        node_cert: Signed certificate (JSON)
+    """
+
+    agent_id: str
+    node_id: str
+    colony_id: str
+    name: str
+    connection_mode: str = "local"
+    gateway_url: Optional[str] = None
+    websocket_connected: bool = False
+    capabilities: List[str] = field(default_factory=list)
+    is_primary: bool = False
+    priority: int = 1
+    max_concurrent: int = 5
+    max_initiatives_per_hour: int = 10
+    excluded_types: List[str] = field(default_factory=list)
+    included_types: List[str] = field(default_factory=list)
+    status: str = "offline"
+    current_assignments: int = 0
+    last_seen_at: Optional[datetime] = None
+    metadata: AgentMetadata = field(default_factory=AgentMetadata)
+    registered_at: Optional[datetime] = None
+    node_cert: Optional[Dict[str, Any]] = None
+
+    @property
+    def load(self) -> float:
+        """Current load as ratio (0.0-1.0)."""
+        if self.max_concurrent <= 0:
+            return 1.0
+        return self.current_assignments / self.max_concurrent
+
+    @property
+    def has_capacity(self) -> bool:
+        """Can accept more assignments?"""
+        return (
+            self.status in ("online", "busy")
+            and self.current_assignments < self.max_concurrent
+        )
+
+    def can_handle_type(self, initiative_type: str) -> bool:
+        """Check if agent can handle this initiative type."""
+        # Excluded types take priority
+        if initiative_type in self.excluded_types:
+            return False
+
+        # If included_types is set, must be in list
+        if self.included_types and initiative_type not in self.included_types:
+            return False
+
+        return True
+
+    def has_capability(self, capability: str) -> bool:
+        """Check if agent has a specific capability."""
+        return capability in self.capabilities
+
+    def has_capabilities(self, capabilities: List[str]) -> bool:
+        """Check if agent has all specified capabilities."""
+        return all(cap in self.capabilities for cap in capabilities)
+
+    @classmethod
+    def from_row(cls, row: dict) -> "Agent":
+        """Create from SQLite row dict."""
+        import json
+
+        metadata_raw = row.get("metadata", "{}")
+        if isinstance(metadata_raw, str):
+            metadata_dict = json.loads(metadata_raw)
+        else:
+            metadata_dict = metadata_raw
+
+        capabilities_raw = row.get("capabilities", "[]")
+        if isinstance(capabilities_raw, str):
+            capabilities = json.loads(capabilities_raw)
+        else:
+            capabilities = capabilities_raw
+
+        excluded_raw = row.get("excluded_types", "[]")
+        if isinstance(excluded_raw, str):
+            excluded_types = json.loads(excluded_raw)
+        else:
+            excluded_types = excluded_raw
+
+        included_raw = row.get("included_types", "[]")
+        if isinstance(included_raw, str):
+            included_types = json.loads(included_raw)
+        else:
+            included_types = included_raw
+
+        node_cert_raw = row.get("node_cert")
+        if node_cert_raw and isinstance(node_cert_raw, str):
+            node_cert = json.loads(node_cert_raw)
+        else:
+            node_cert = node_cert_raw
+
+        return cls(
+            agent_id=row["agent_id"],
+            node_id=row["node_id"],
+            colony_id=row["colony_id"],
+            name=row["name"],
+            connection_mode=row.get("connection_mode", "local"),
+            gateway_url=row.get("gateway_url"),
+            websocket_connected=bool(row.get("websocket_connected", 0)),
+            capabilities=capabilities,
+            is_primary=bool(row.get("is_primary", 0)),
+            priority=row.get("priority", 1),
+            max_concurrent=row.get("max_concurrent", 5),
+            max_initiatives_per_hour=row.get("max_initiatives_per_hour", 10),
+            excluded_types=excluded_types,
+            included_types=included_types,
+            status=row.get("status", "offline"),
+            current_assignments=row.get("current_assignments", 0),
+            last_seen_at=_parse_datetime(row.get("last_seen_at")),
+            metadata=AgentMetadata.from_dict(metadata_dict),
+            registered_at=_parse_datetime(row.get("registered_at")),
+            node_cert=node_cert,
+        )
+
+
+def _parse_datetime(value: Optional[str]) -> Optional[datetime]:
+    """Parse ISO datetime string."""
+    if not value:
+        return None
+    try:
+        # Handle both with and without timezone
+        if value.endswith("Z"):
+            value = value[:-1] + "+00:00"
+        return datetime.fromisoformat(value)
+    except (ValueError, TypeError):
+        return None