relaypy 0.1.0__tar.gz

relaypy-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/ruff-action@v3
+
+  type-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: pip install mypy
+      - run: mypy src/
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/ -v --cov=src
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: pip install bandit
+      - run: bandit -r src/ -x tests/

relaypy-0.1.0/ADR.md

@@ -0,0 +1,41 @@
+# ADR: thegent-cli-share
+
+## ADR-001: Python over Rust for CLI Coordination Layer
+
+**Status**: Accepted
+
+**Context**: thegent-cli-share needs to coordinate Python-based agent processes. Implementation language choices: Rust (for performance), Python (for ecosystem fit), Go.
+
+**Decision**: Python, implemented as a library that other Python agent processes import directly.
+
+**Rationale**: thegent agents are Python processes. A Python library is directly importable without IPC overhead. Rust would require a separate daemon process. Python asyncio is sufficient for coordination at the expected scale (< 100 concurrent agents).
+
+**Consequences**: Coordination is in-process for single-host deployments. Multi-host coordination would require a separate service layer (future work).
+
+---
+
+## ADR-002: File-Based State Store for Coordination Primitives
+
+**Status**: Accepted
+
+**Context**: Distributed locks, task queues, and command caches need a shared state store. Options: Redis, PostgreSQL, filesystem with fcntl locks.
+
+**Decision**: Filesystem-based state store using atomic file operations and fcntl advisory locks for single-host deployments.
+
+**Rationale**: No external service dependency. thegent is a local developer tool; Redis/PostgreSQL is overkill. fcntl locks are reliable on Linux/macOS. Filesystem state is inspectable for debugging.
+
+**Consequences**: Not suitable for multi-host deployments without a storage backend swap. Backend is abstracted via a `StateStore` protocol for future Redis adapter.
+
+---
+
+## ADR-003: CQRS for Command and Query Separation
+
+**Status**: Accepted
+
+**Context**: Coordination operations are a mix of state-mutating commands (enqueue, acquire_lock) and queries (get_task_status, list_in_flight). Mixing these leads to complex APIs.
+
+**Decision**: Separate command and query interfaces following CQRS pattern. `CommandBus` for mutations, `QueryBus` for reads.
+
+**Rationale**: Clean separation simplifies testing (queries are read-only and easier to mock). Aligns with thegent hexagonal architecture standard.
+
+**Consequences**: More initial API surface. Justified by the complexity of the coordination domain.

relaypy-0.1.0/CLAUDE.md

@@ -0,0 +1,29 @@
+# CLAUDE.md - Development Guidelines for thegent-cli-share
+
+## Project Overview
+
+CLI share system for thegent
+
+## Key Files
+
+-  - Project overview
+- See project-specific directories
+
+## Development Commands
+
+```bash
+cargo build && cargo test
+```
+
+## Architecture Principles
+
+- **SOLID** - Single Responsibility, Dependency Inversion
+- **DRY** - Shared abstractions
+- **PoLA** - Descriptive error types
+
+## Phenotype Org Rules
+
+- UTF-8 encoding only in all text files
+- Worktree discipline: canonical repo stays on `main`
+- CI completeness: fix all CI failures before merging
+- Never commit agent directories (`.claude/`, `.codex/`, `.cursor/`)

relaypy-0.1.0/FUNCTIONAL_REQUIREMENTS.md

@@ -0,0 +1,37 @@
+# Functional Requirements: thegent-cli-share
+
+## FR-CLI-001: Command Identity
+FR-CLI-001a: The library SHALL compute a deterministic command ID by hashing: command string, working directory, and environment variables.
+FR-CLI-001b: Command IDs SHALL be stable across agent processes on the same machine.
+
+## FR-CLI-002: Command Deduplication
+FR-CLI-002a: When an agent submits a command, the library SHALL check if an identical command is already in-flight.
+FR-CLI-002b: If a duplicate in-flight command exists, the submitting agent SHALL wait for the in-flight result instead of executing again.
+FR-CLI-002c: Idempotent commands SHALL have their results cached for a configurable TTL (default: 60 seconds).
+FR-CLI-002d: Non-idempotent commands (marked with `idempotent=False`) SHALL never be deduplicated.
+
+## FR-CLI-003: Task Queue
+FR-CLI-003a: The library SHALL provide `enqueue(task, priority)` and `dequeue() -> Task` operations.
+FR-CLI-003b: Tasks with higher priority SHALL be dequeued before lower-priority tasks.
+FR-CLI-003c: An idle agent SHALL be able to steal tasks from other agents' assigned queues.
+FR-CLI-003d: A failed task SHALL be moved to the dead letter queue after `max_retries` attempts.
+
+## FR-CLI-004: Task Dependencies
+FR-CLI-004a: Tasks SHALL support a `depends_on: list[TaskId]` field.
+FR-CLI-004b: A task SHALL not be dequeued until all its dependencies have completed successfully.
+FR-CLI-004c: Circular dependencies SHALL be detected at enqueue time and rejected with an error.
+
+## FR-CLI-005: Distributed Lock
+FR-CLI-005a: `acquire_lock(resource_id, timeout)` SHALL block until the lock is acquired or timeout expires.
+FR-CLI-005b: Locks SHALL have a mandatory TTL to prevent deadlock from crashed lock holders.
+FR-CLI-005c: Lock acquisition and release SHALL be logged to the audit log.
+
+## FR-CLI-006: Smart Merge
+FR-CLI-006a: When two agents attempt to write the same file, the library SHALL detect the conflict.
+FR-CLI-006b: The library SHALL attempt a three-way merge using the common ancestor as base.
+FR-CLI-006c: If three-way merge fails (conflict), the operation SHALL be flagged for operator review.
+
+## FR-CLI-007: Audit Log
+FR-CLI-007a: Every coordination operation SHALL be logged with: timestamp, agent_id, operation_type, resource_id, outcome.
+FR-CLI-007b: The audit log SHALL be queryable by agent_id and time range.
+FR-CLI-007c: The audit log SHALL be durable (written to disk, not only in-memory).

relaypy-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: relaypy
+Version: 0.1.0
+Summary: CLI share system - command deduplication, task queue, smart merge
+Author-email: Koosha Pari <kooshapari@kooshapari.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: watchfiles>=0.21.0
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7.0; extra == 'dev'
+Requires-Dist: mypy>=1.5.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# thegent-cli-share
+
+CLI share system for multi-agent orchestration - command deduplication, task queue, smart merge, and coordination.
+
+## Architecture
+
+This crate follows **Hexagonal Architecture** (Ports & Adapters) with **Clean Architecture** layers.
+
+## xDD Methodologies Applied
+
+- **TDD**: Tests written first
+- **DDD**: Bounded contexts for command cache, task queue, smart merge
+- **SOLID**: Single responsibility per module
+- **CQRS**: Separate command and query interfaces
+- **EDA**: Domain events for state changes
+
+## Domain Services
+
+### Command Deduplication
+Prevents duplicate command execution across agents using SHM-based locks.
+
+### Task Queue
+Maildir-style queue for distributed task processing.
+
+### Smart Merge
+Mergiraf-style AST-aware merging for conflict resolution.
+
+### Coordination
+HLC-based distributed coordination.
+
+## Installation
+
+```bash
+pip install thegent-cli-share
+```
+
+## CLI Usage
+
+```bash
+# Command deduplication
+thegent-cli-share lock-acquire <cmd_hash>
+thegent-cli-share lock-release <cmd_hash> --pid <pid>
+thegent-cli-share lock-list
+
+# Task queue
+thegent-cli-share queue-enqueue <command> --priority high
+thegent-cli-share queue-list
+```
+
+## Python API
+
+```python
+from thegent_cli_share.adapters.dedup import InMemoryLockAdapter
+
+adapter = InMemoryLockAdapter()
+lock = adapter.acquire("cmd_hash", pid=1234)
+```
+
+## License
+
+MIT

relaypy-0.1.0/PRD.md

@@ -0,0 +1,44 @@
+# PRD: thegent-cli-share — CLI Coordination for Multi-Agent Orchestration
+
+## Overview
+`thegent-cli-share` is a Python library providing multi-agent CLI coordination primitives: command deduplication, task queue management, smart merge, and agent synchronization for the thegent system.
+
+## Problem Statement
+When multiple thegent agents run concurrently, they may issue duplicate CLI commands, create conflicting file edits, or deadlock on shared resources. `thegent-cli-share` prevents these problems by providing a shared coordination layer.
+
+## Goals
+1. Prevent duplicate command execution across concurrent agents
+2. Provide a shared task queue for work distribution
+3. Smart merge: detect and resolve conflicting file edits
+4. Agent-to-agent synchronization primitives (locks, semaphores, barriers)
+5. Audit log for all coordinated operations
+
+## Epics
+
+### E1: Command Deduplication
+- E1.1: Command identity hashing (deterministic ID for equivalent commands)
+- E1.2: In-flight command registry (prevent duplicate execution)
+- E1.3: Result caching (share results of idempotent commands)
+- E1.4: TTL-based cache invalidation
+
+### E2: Task Queue
+- E2.1: Priority queue with agent-assigned work items
+- E2.2: Work stealing for idle agents
+- E2.3: Task dependency graph (DAG) with execution ordering
+- E2.4: Dead letter queue for failed tasks
+
+### E3: Smart Merge
+- E3.1: Detect concurrent edits to the same file
+- E3.2: Three-way merge for text files
+- E3.3: Conflict escalation to human/operator when auto-merge fails
+- E3.4: Merge audit log
+
+### E4: Synchronization Primitives
+- E4.1: Distributed lock (mutex for critical sections)
+- E4.2: Semaphore (rate limiting concurrent operations)
+- E4.3: Barrier (coordinate multiple agents to a sync point)
+
+### E5: Audit Log
+- E5.1: Structured event log for all coordination operations
+- E5.2: Agent identity tracking per operation
+- E5.3: Queryable log for debugging coordination issues

relaypy-0.1.0/README.md

@@ -0,0 +1,61 @@
+# thegent-cli-share
+
+CLI share system for multi-agent orchestration - command deduplication, task queue, smart merge, and coordination.
+
+## Architecture
+
+This crate follows **Hexagonal Architecture** (Ports & Adapters) with **Clean Architecture** layers.
+
+## xDD Methodologies Applied
+
+- **TDD**: Tests written first
+- **DDD**: Bounded contexts for command cache, task queue, smart merge
+- **SOLID**: Single responsibility per module
+- **CQRS**: Separate command and query interfaces
+- **EDA**: Domain events for state changes
+
+## Domain Services
+
+### Command Deduplication
+Prevents duplicate command execution across agents using SHM-based locks.
+
+### Task Queue
+Maildir-style queue for distributed task processing.
+
+### Smart Merge
+Mergiraf-style AST-aware merging for conflict resolution.
+
+### Coordination
+HLC-based distributed coordination.
+
+## Installation
+
+```bash
+pip install thegent-cli-share
+```
+
+## CLI Usage
+
+```bash
+# Command deduplication
+thegent-cli-share lock-acquire <cmd_hash>
+thegent-cli-share lock-release <cmd_hash> --pid <pid>
+thegent-cli-share lock-list
+
+# Task queue
+thegent-cli-share queue-enqueue <command> --priority high
+thegent-cli-share queue-list
+```
+
+## Python API
+
+```python
+from thegent_cli_share.adapters.dedup import InMemoryLockAdapter
+
+adapter = InMemoryLockAdapter()
+lock = adapter.acquire("cmd_hash", pid=1234)
+```
+
+## License
+
+MIT

relaypy-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "relaypy"
+version = "0.1.0"
+description = "CLI share system - command deduplication, task queue, smart merge"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Koosha Pari", email = "kooshapari@kooshapari.com" }
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    "watchfiles>=0.21.0",
+    "pydantic>=2.0.0",
+    "rich>=13.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "pytest-asyncio>=0.21.0",
+    "ruff>=0.1.0",
+    "mypy>=1.5.0",
+    "bandit>=1.7.0",
+    "pre-commit>=3.0.0",
+]
+
+[project.scripts]
+thegent-share = "thegent_cli_share.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/thegent_cli_share"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

relaypy-0.1.0/src/thegent_cli_share/__init__.py

@@ -0,0 +1,87 @@
+"""thegent-cli-share - CLI share system with hexagonal architecture.
+
+CLI Share System Architecture:
+- Command deduplication (cmd_share)
+- Task queue (Maildir-style)
+- Smart merge (Mergiraf)
+- Request coalescing (Singleflight)
+- Coordination (HLC, OCC, leases)
+
+xDD Methodologies Applied:
+- TDD: Tests with pytest
+- BDD: Behavior-driven with pytest-bdd
+- DDD: Domain-driven design with bounded contexts
+- SOLID: Single responsibility per module
+- CQRS: Separate commands and queries
+- EDA: Event-driven architecture
+- Hexagonal: Ports and adapters pattern
+"""
+
+__version__ = "0.1.0"
+
+from .domain.entities import (
+    CommandLock,
+    TaskQueueItem,
+    MergeCandidate,
+    CoordinationState,
+)
+from .domain.value_objects import (
+    CommandHash,
+    LockStatus,
+    QueuePriority,
+    MergeStrategy,
+)
+from .domain.events import (
+    CliShareEvent,
+    TaskEvent,
+    MergeEvent,
+    CoordinationEvent,
+)
+from .application.commands import (
+    AcquireLockCommand,
+    ReleaseLockCommand,
+    EnqueueTaskCommand,
+    MergeCommand,
+)
+from .application.queries import (
+    GetLockQuery,
+    ListLocksQuery,
+    GetQueueDepthQuery,
+    GetMergeCandidatesQuery,
+)
+from .ports.driven import (
+    LockPort,
+    QueuePort,
+    MergePort,
+    CoordinationPort,
+)
+
+__all__ = [
+    # Domain
+    "CommandLock",
+    "TaskQueueItem",
+    "MergeCandidate",
+    "CoordinationState",
+    "CommandHash",
+    "LockStatus",
+    "QueuePriority",
+    "MergeStrategy",
+    "CliShareEvent",
+    "TaskEvent",
+    "MergeEvent",
+    "CoordinationEvent",
+    # Application
+    "AcquireLockCommand",
+    "ReleaseLockCommand",
+    "EnqueueTaskCommand",
+    "MergeCommand",
+    "GetLockQuery",
+    "ListLocksQuery",
+    "GetQueueDepthQuery",
+    "GetMergeCandidatesQuery",
+    # Ports
+    "LockPort",
+    "QueuePort",
+    "MergePort",
+    "CoordinationPort",
+]

relaypy-0.1.0/src/thegent_cli_share/cli.py

@@ -0,0 +1,112 @@
+"""CLI interface for thegent-cli-share."""
+
+import sys
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from thegent_cli_share import __version__
+from thegent_cli_share.adapters.dedup import InMemoryLockAdapter
+from thegent_cli_share.adapters.queue import InMemoryQueueAdapter
+
+app = typer.Typer(help="CLI share system - command deduplication and task queue")
+console = Console()
+
+# Global adapters (in-memory for CLI)
+_lock_adapter = InMemoryLockAdapter()
+_queue_adapter = InMemoryQueueAdapter()
+
+
+@app.command()
+def lock_acquire(
+    cmd_hash: str = typer.Argument(..., help="Command hash to lock"),
+    pid: int = typer.Option(0, help="Process ID"),
+    output_path: Optional[str] = typer.Option(None, help="Output file path"),
+) -> None:
+    """Acquire a command lock."""
+    try:
+        lock = _lock_adapter.acquire(cmd_hash, pid, output_path)
+        console.print(f"[green]Lock acquired:[/green] {lock.cmd_hash} (PID: {lock.pid})")
+    except ValueError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+
+@app.command()
+def lock_release(
+    cmd_hash: str = typer.Argument(..., help="Command hash to release"),
+    pid: int = typer.Option(..., help="Process ID"),
+) -> None:
+    """Release a command lock."""
+    try:
+        _lock_adapter.release(cmd_hash, pid)
+        console.print(f"[green]Lock released:[/green] {cmd_hash}")
+    except ValueError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+
+@app.command(name="lock-list")
+def lock_list() -> None:
+    """List all active locks."""
+    locks = _lock_adapter.list_all()
+    if not locks:
+        console.print("[yellow]No active locks[/yellow]")
+        return
+
+    table = Table(title="Active Locks")
+    table.add_column("Command Hash", style="cyan")
+    table.add_column("PID", style="magenta")
+    table.add_column("Status", style="green")
+
+    for lock in locks:
+        table.add_row(lock.cmd_hash, str(lock.pid), lock.status.value)
+
+    console.print(table)
+
+
+@app.command()
+def queue_enqueue(
+    command: str = typer.Argument(..., help="Command to enqueue"),
+    priority: str = typer.Option("normal", help="Priority: low, normal, high, critical"),
+) -> None:
+    """Enqueue a task."""
+    item = _queue_adapter.enqueue(command, priority)
+    console.print(f"[green]Task enqueued:[/green] {item.id} ({priority})")
+
+
+@app.command(name="queue-list")
+def queue_list() -> None:
+    """List all queued tasks."""
+    items = _queue_adapter.list_all()
+    if not items:
+        console.print("[yellow]Queue is empty[/yellow]")
+        return
+
+    table = Table(title=f"Task Queue ({len(items)} items)")
+    table.add_column("ID", style="cyan")
+    table.add_column("Command", style="white")
+    table.add_column("Priority", style="yellow")
+    table.add_column("Status", style="green")
+
+    for item in items:
+        table.add_row(str(item.id), item.command[:50], item.priority.value, item.status)
+
+    console.print(table)
+
+
+@app.command()
+def version() -> None:
+    """Show version information."""
+    console.print(f"thegent-cli-share [cyan]{__version__}[/cyan]")
+
+
+def main() -> None:
+    """Main entry point."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

relaypy-0.1.0/src/thegent_cli_share/domain/__init__.py

@@ -0,0 +1 @@
+"""Init file for domain module."""

relaypy-0.1.0/src/thegent_cli_share/domain/entities.py

@@ -0,0 +1,156 @@
+"""Domain entities - core business objects with identity.
+
+DDD (Domain-Driven Design) Principles:
+- Entities have unique identity
+- Value objects are immutable
+- Domain events are immutable facts
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field
+
+
+class LockStatus(str, Enum):
+    """Lock status for command deduplication."""
+    UNLOCKED = "unlocked"
+    LOCKED = "locked"
+    COMPLETED = "completed"
+    TIMED_OUT = "timed_out"
+
+
+class QueuePriority(str, Enum):
+    """Task queue priority levels."""
+    LOW = "low"
+    NORMAL = "normal"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+class MergeStrategy(str, Enum):
+    """Merge strategies for smart merge."""
+    AUTO = "auto"
+    THEIRS = "theirs"
+    OURS = "ours"
+    MANUAL = "manual"
+
+
+class CommandLock(BaseModel):
+    """Command lock entity for deduplication.
+
+    Implements the cmd_share functionality - ensures only one
+    instance of a command runs at a time.
+    """
+    cmd_hash: str = Field(description="Unique command hash")
+    pid: int = Field(default=0, description="Process ID holding lock")
+    status: LockStatus = Field(default=LockStatus.UNLOCKED)
+    output_path: Optional[str] = Field(default=None)
+    start_time: Optional[datetime] = Field(default=None)
+    timeout_seconds: int = Field(default=3600)
+
+    @property
+    def is_locked(self) -> bool:
+        return self.pid != 0 and self.status == LockStatus.LOCKED
+
+    def acquire(self, pid: int, output_path: Optional[str] = None) -> None:
+        """Acquire the lock for a process."""
+        if self.is_locked and self.pid != pid:
+            raise ValueError(f"Lock held by PID {self.pid}")
+        self.pid = pid
+        self.status = LockStatus.LOCKED
+        self.output_path = output_path
+        self.start_time = datetime.now()
+
+    def release(self, pid: int) -> None:
+        """Release the lock."""
+        if self.pid != pid:
+            raise ValueError(f"Lock held by PID {self.pid}, cannot release")
+        self.pid = 0
+        self.status = LockStatus.UNLOCKED
+        self.start_time = None
+
+    def complete(self, pid: int) -> None:
+        """Mark the command as completed."""
+        if self.pid != pid:
+            raise ValueError("Cannot complete - not lock owner")
+        self.status = LockStatus.COMPLETED
+
+
+class TaskQueueItem(BaseModel):
+    """Task queue item for Maildir-style queue."""
+    id: UUID = Field(default_factory=uuid4)
+    command: str = Field(description="Command to execute")
+    priority: QueuePriority = Field(default=QueuePriority.NORMAL)
+    created_at: datetime = Field(default_factory=datetime.now)
+    started_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+    status: str = Field(default="pending")
+    cwd: Optional[str] = None
+    env: dict[str, str] = Field(default_factory=dict)
+    result: Optional[dict] = None
+
+    @property
+    def is_pending(self) -> bool:
+        return self.status == "pending"
+
+    @property
+    def is_running(self) -> bool:
+        return self.status == "running"
+
+    @property
+    def is_completed(self) -> bool:
+        return self.status == "completed"
+
+    def start(self) -> None:
+        """Mark task as started."""
+        self.status = "running"
+        self.started_at = datetime.now()
+
+    def complete(self, result: dict) -> None:
+        """Mark task as completed."""
+        self.status = "completed"
+        self.completed_at = datetime.now()
+        self.result = result
+
+
+class MergeCandidate(BaseModel):
+    """Merge candidate for smart merge."""
+    id: UUID = Field(default_factory=uuid4)
+    base_commit: str = Field(description="Base commit SHA")
+    theirs_commit: str = Field(description="Their branch commit")
+    ours_commit: str = Field(description="Our branch commit")
+    strategy: MergeStrategy = Field(default=MergeStrategy.AUTO)
+    conflict_count: int = Field(default=0)
+    auto_mergeable: bool = Field(default=False)
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
+class CoordinationState(BaseModel):
+    """Coordination state for distributed locking."""
+    resource_id: str = Field(description="Resource being coordinated")
+    owner_id: Optional[str] = Field(default=None)
+    lease_expires_at: Optional[datetime] = None
+    version: int = Field(default=0)
+    hlc_timestamp: int = Field(default=0)
+
+    @property
+    def is_owned(self) -> bool:
+        return self.owner_id is not None
+
+    def acquire_lease(self, owner_id: str, duration_seconds: int) -> None:
+        """Acquire a lease on the resource."""
+        from datetime import timedelta
+        self.owner_id = owner_id
+        self.lease_expires_at = datetime.now() + timedelta(seconds=duration_seconds)
+        self.version += 1
+
+    def release_lease(self, owner_id: str) -> None:
+        """Release the lease."""
+        if self.owner_id != owner_id:
+            raise ValueError("Not the lease owner")
+        self.owner_id = None
+        self.lease_expires_at = None
+        self.version += 1

relaypy-0.1.0/src/thegent_cli_share/domain/events.py

@@ -0,0 +1,69 @@
+"""Domain events - immutable facts representing state changes.
+
+Event Sourcing Principles:
+- Events are immutable
+- Append-only log
+- Reconstruct state by replaying events
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+from dataclasses import dataclass
+
+
+class EventType(str, Enum):
+    """Event type enumeration."""
+    LOCK_ACQUIRED = "lock_acquired"
+    LOCK_RELEASED = "lock_released"
+    LOCK_COMPLETED = "lock_completed"
+    LOCK_TIMEOUT = "lock_timeout"
+    TASK_ENQUEUED = "task_enqueued"
+    TASK_STARTED = "task_started"
+    TASK_COMPLETED = "task_completed"
+    TASK_FAILED = "task_failed"
+    MERGE_STARTED = "merge_started"
+    MERGE_COMPLETED = "merge_completed"
+    MERGE_CONFLICT = "merge_conflict"
+    COORD_LEASE_ACQUIRED = "coord_lease_acquired"
+    COORD_LEASE_RELEASED = "coord_lease_released"
+
+
+@dataclass(frozen=True)
+class CliShareEvent:
+    """Base event for CLI share operations."""
+    event_type: EventType
+    timestamp: datetime
+    cmd_hash: str
+    pid: Optional[int] = None
+    metadata: Optional[dict] = None
+
+
+@dataclass(frozen=True)
+class TaskEvent:
+    """Event for task queue operations."""
+    event_type: EventType
+    timestamp: datetime
+    task_id: str
+    metadata: Optional[dict] = None
+
+
+@dataclass(frozen=True)
+class MergeEvent:
+    """Event for merge operations."""
+    event_type: EventType
+    timestamp: datetime
+    base_commit: str
+    branch_name: str
+    conflict_count: int = 0
+    metadata: Optional[dict] = None
+
+
+@dataclass(frozen=True)
+class CoordinationEvent:
+    """Event for coordination operations."""
+    event_type: EventType
+    timestamp: datetime
+    resource_id: str
+    owner_id: str
+    metadata: Optional[dict] = None

relaypy-0.1.0/src/thegent_cli_share/domain/value_objects.py

@@ -0,0 +1,81 @@
+"""Domain value objects - immutable objects defined by their attributes.
+
+Value Object Principles:
+- Immutable (no setters, create new instances)
+- No identity (two VOs with same values are equal)
+- Self-validating
+"""
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class CommandHash:
+    """Immutable command hash for deduplication."""
+    value: str
+    algorithm: str = "sha256"
+
+    def __str__(self) -> str:
+        return self.value
+
+    def __len__(self) -> int:
+        return len(self.value)
+
+
+@dataclass(frozen=True)
+class TaskMetadata:
+    """Immutable task metadata."""
+    command: str
+    cwd: str
+    env: tuple[tuple[str, str], ...]
+    timeout_seconds: int = 3600
+
+    def with_timeout(self, seconds: int) -> "TaskMetadata":
+        """Create new TaskMetadata with different timeout."""
+        return TaskMetadata(
+            command=self.command,
+            cwd=self.cwd,
+            env=self.env,
+            timeout_seconds=seconds,
+        )
+
+
+@dataclass(frozen=True)
+class MergeConflict:
+    """Immutable merge conflict information."""
+    file_path: str
+    line_start: int
+    line_end: int
+    ours_content: str
+    theirs_content: str
+
+    @property
+    def conflict_range(self) -> str:
+        return f"{self.line_start}-{self.line_end}"
+
+
+@dataclass(frozen=True)
+class HealthScore:
+    """Health score for system monitoring."""
+    overall: float
+    components: tuple[tuple[str, float], ...]
+
+    @classmethod
+    def from_components(cls, **kwargs: float) -> "HealthScore":
+        """Create health score from components."""
+        components = tuple(kwargs.items())
+        if not components:
+            return cls(overall=1.0, components=())
+        overall = sum(v for _, v in components) / len(components)
+        return cls(overall=overall, components=components)
+
+    def is_healthy(self) -> bool:
+        return self.overall >= 0.8
+
+    def is_degraded(self) -> bool:
+        return 0.5 <= self.overall < 0.8
+
+    def is_unhealthy(self) -> bool:
+        return self.overall < 0.5

relaypy-0.1.0/src/thegent_cli_share/ports/driven.py

@@ -0,0 +1,84 @@
+"""Driven ports - interfaces for infrastructure adapters.
+
+Hexagonal Architecture: Ports define how the domain interacts with external systems.
+"""
+
+from typing import Protocol, Optional
+from ..domain.entities import CommandLock, TaskQueueItem, MergeCandidate, CoordinationState
+from ..domain.value_objects import CommandHash
+
+
+class LockPort(Protocol):
+    """Port for command lock operations."""
+    
+    def acquire(self, cmd_hash: CommandHash, pid: int, output_path: Optional[str] = None) -> CommandLock:
+        """Acquire a command lock."""
+        ...
+    
+    def release(self, cmd_hash: CommandHash, pid: int) -> None:
+        """Release a command lock."""
+        ...
+    
+    def get(self, cmd_hash: CommandHash) -> Optional[CommandLock]:
+        """Get lock status."""
+        ...
+    
+    def list_all(self) -> list[CommandLock]:
+        """List all locks."""
+        ...
+
+
+class QueuePort(Protocol):
+    """Port for task queue operations."""
+    
+    def enqueue(self, item: TaskQueueItem) -> TaskQueueItem:
+        """Add item to queue."""
+        ...
+    
+    def dequeue(self) -> Optional[TaskQueueItem]:
+        """Remove and return next item."""
+        ...
+    
+    def peek(self) -> Optional[TaskQueueItem]:
+        """View next item without removing."""
+        ...
+    
+    def length(self) -> int:
+        """Get queue length."""
+        ...
+    
+    def clear(self) -> None:
+        """Clear the queue."""
+        ...
+
+
+class MergePort(Protocol):
+    """Port for merge operations."""
+    
+    def find_conflicts(self, base: str, theirs: str, ours: str) -> list[MergeCandidate]:
+        """Find merge conflicts between branches."""
+        ...
+    
+    def merge(self, base: str, theirs: str, strategy: str = "auto") -> dict:
+        """Perform merge with given strategy."""
+        ...
+    
+    def apply_resolution(self, candidate_id: str, resolution: dict) -> None:
+        """Apply conflict resolution."""
+        ...
+
+
+class CoordinationPort(Protocol):
+    """Port for distributed coordination."""
+    
+    def acquire_lease(self, resource_id: str, owner_id: str, duration_seconds: int) -> CoordinationState:
+        """Acquire a lease on a resource."""
+        ...
+    
+    def release_lease(self, resource_id: str, owner_id: str) -> None:
+        """Release a lease."""
+        ...
+    
+    def check_lease(self, resource_id: str) -> Optional[CoordinationState]:
+        """Check lease status."""
+        ...

relaypy-0.1.0/tests/__init__.py

@@ -0,0 +1 @@
+"""Init file for thegent-cli-share."""

relaypy-0.1.0/tests/test_thegent_cli_share.py

@@ -0,0 +1,103 @@
+"""Tests for thegent-cli-share."""
+
+import pytest
+from thegent_cli_share.adapters.dedup import InMemoryLockAdapter, CommandLock
+from thegent_cli_share.adapters.queue import InMemoryQueueAdapter, QueueItem, Priority
+
+
+class TestCommandLock:
+    """Tests for CommandLock entity."""
+
+    def test_create_lock(self) -> None:
+        """Test creating a new command lock."""
+        lock = CommandLock(cmd_hash="test_hash", pid=0)
+        assert lock.cmd_hash == "test_hash"
+        assert lock.pid == 0
+
+    def test_acquire_lock(self) -> None:
+        """Test acquiring a lock."""
+        adapter = InMemoryLockAdapter()
+        lock = adapter.acquire("test_hash", 1234)
+        assert lock.cmd_hash == "test_hash"
+        assert lock.pid == 1234
+        assert lock.is_locked()
+
+    def test_release_lock(self) -> None:
+        """Test releasing a lock."""
+        adapter = InMemoryLockAdapter()
+        adapter.acquire("test_hash", 1234)
+        adapter.release("test_hash", 1234)
+        assert not adapter.get("test_hash").is_locked()
+
+    def test_cannot_acquire_locked(self) -> None:
+        """Test that we cannot acquire a locked command."""
+        adapter = InMemoryLockAdapter()
+        adapter.acquire("test_hash", 1234)
+        with pytest.raises(ValueError, match="already locked"):
+            adapter.acquire("test_hash", 5678)
+
+
+class TestTaskQueue:
+    """Tests for TaskQueue."""
+
+    def test_enqueue(self) -> None:
+        """Test enqueuing a task."""
+        adapter = InMemoryQueueAdapter()
+        item = adapter.enqueue("echo 'hello'")
+        assert item.command == "echo 'hello'"
+        assert item.status == "queued"
+
+    def test_dequeue(self) -> None:
+        """Test dequeuing a task."""
+        adapter = InMemoryQueueAdapter()
+        adapter.enqueue("task1")
+        adapter.enqueue("task2")
+        item = adapter.dequeue()
+        assert item.command == "task1"
+        assert item.status == "dequeued"
+
+    def test_priority_ordering(self) -> None:
+        """Test that high priority items are dequeued first."""
+        adapter = InMemoryQueueAdapter()
+        adapter.enqueue("low", priority=Priority.LOW)
+        adapter.enqueue("high", priority=Priority.HIGH)
+        adapter.enqueue("normal", priority=Priority.NORMAL)
+        item = adapter.dequeue()
+        assert item.command == "high"
+
+
+class TestCoordination:
+    """Tests for CoordinationService."""
+
+    def test_edit_intent(self) -> None:
+        """Test EditIntent creation and checking."""
+        from thegent_cli_share.domain.entities import EditIntent
+
+        intent = EditIntent(
+            agent_id="agent1",
+            file_path="/path/to/file",
+            start_line=10,
+            end_line=20,
+        )
+        assert intent.file_path == "/path/to/file"
+        assert intent.start_line == 10
+        assert intent.end_line == 20
+        assert intent.conflicts_with(intent)  # Same range conflicts
+
+    def test_edit_intent_no_conflict(self) -> None:
+        """Test that non-overlapping edits don't conflict."""
+        from thegent_cli_share.domain.entities import EditIntent
+
+        intent1 = EditIntent(
+            agent_id="agent1",
+            file_path="/path/to/file",
+            start_line=10,
+            end_line=20,
+        )
+        intent2 = EditIntent(
+            agent_id="agent2",
+            file_path="/path/to/file",
+            start_line=30,
+            end_line=40,
+        )
+        assert not intent1.conflicts_with(intent2)