fableforge-agent-runtime 0.1.0__py3-none-any.whl

agent_runtime/__init__.py

@@ -0,0 +1,3 @@
+"""AgentRuntime — persistent agent daemon for managing AI agent processes."""
+
+__version__ = "0.1.0"

agent_runtime/cli.py

@@ -0,0 +1,128 @@
+"""CLI interface for agentd — start, stop, create, list, resume."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+
+import click
+
+from .daemon import AgentDaemon
+from .models import SessionCreate
+
+
+@click.group()
+@click.option("--verbose", "-v", is_flag=True, help="Enable verbose logging")
+def app(verbose: bool) -> None:
+    import logging
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+
+
+@app.command()
+@click.option("--host", default="0.0.0.0", help="Bind host")
+@click.option("--port", default=8721, type=int, help="Bind port")
+def start(host: str, port: int) -> None:
+    if AgentDaemon.is_running():
+        click.echo("agentd is already running")
+        sys.exit(1)
+    click.echo(f"Starting agentd on {host}:{port}")
+    daemon = AgentDaemon(host=host, port=port)
+    asyncio.run(daemon.start())
+
+
+@app.command()
+def stop() -> None:
+    if not AgentDaemon.is_running():
+        click.echo("agentd is not running")
+        sys.exit(1)
+    if AgentDaemon.stop_running():
+        click.echo("Stopped agentd")
+    else:
+        click.echo("Failed to stop agentd", err=True)
+        sys.exit(1)
+
+
+@app.command()
+@click.option("--name", required=True, help="Session name")
+@click.option("--model", required=True, help="Model identifier")
+@click.option("--system-prompt", default="", help="System prompt")
+@click.option("--tools", multiple=True, help="Tool names")
+def create(name: str, model: str, system_prompt: str, tools: tuple[str, ...]) -> None:
+    from .session_manager import SessionManager
+    sm = SessionManager()
+    state = sm.create_session(
+        name=name,
+        model=model,
+        config={"system_prompt": system_prompt, "tools": list(tools)},
+    )
+    click.echo(f"Created session: {state.session_id}")
+    click.echo(f"  Name:  {state.name}")
+    click.echo(f"  Model: {state.model}")
+    click.echo(f"  Status: {state.status.value}")
+
+
+@app.command("list")
+def list_sessions() -> None:
+    from .session_manager import SessionManager
+    sm = SessionManager()
+    sessions = sm.list_sessions()
+    if not sessions:
+        click.echo("No sessions found")
+        return
+    click.echo(f"{'ID':<20} {'Name':<20} {'Model':<20} {'Status':<10} {'Created'}")
+    click.echo("-" * 90)
+    for s in sessions:
+        click.echo(
+            f"{s.session_id:<20} {s.name:<20} {s.model:<20} {s.status.value:<10} {s.created_at.isoformat()}"
+        )
+
+
+@app.command()
+@click.argument("session_id")
+@click.option("--checkpoint-id", default=None, help="Resume from specific checkpoint")
+def resume(session_id: str, checkpoint_id: str | None) -> None:
+    from .session_manager import SessionManager
+    sm = SessionManager()
+    try:
+        state = asyncio.run(sm.resume_session(session_id, checkpoint_id=checkpoint_id))
+        click.echo(f"Resumed session: {state.session_id}")
+        click.echo(f"  Status: {state.status.value}")
+        if checkpoint_id:
+            click.echo(f"  From checkpoint: {checkpoint_id}")
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+
+@app.command()
+@click.argument("session_id")
+def pause(session_id: str) -> None:
+    from .session_manager import SessionManager
+    sm = SessionManager()
+    try:
+        state = asyncio.run(sm.pause_session(session_id))
+        click.echo(f"Paused session: {state.session_id}")
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+
+@app.command()
+@click.argument("session_id")
+def stop_session(session_id: str) -> None:
+    from .session_manager import SessionManager
+    sm = SessionManager()
+    try:
+        state = asyncio.run(sm.stop_session(session_id))
+        click.echo(f"Stopped session: {state.session_id}")
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    app()

agent_runtime/daemon.py

@@ -0,0 +1,172 @@
+"""Main daemon process — background agent manager with heartbeat and auto-checkpoint."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import signal
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+from .memory_store import MemoryStore
+from .models import HealthResponse
+from .session_manager import SessionManager
+from .state_serializer import StateSerializer
+
+logger = logging.getLogger(__name__)
+
+PID_DIR = Path.home() / ".agent_runtime"
+PID_FILE = PID_DIR / "agentd.pid"
+
+
+class AgentDaemon:
+    def __init__(
+        self,
+        state_serializer: StateSerializer | None = None,
+        memory_store: MemoryStore | None = None,
+        host: str = "0.0.0.0",
+        port: int = 8721,
+        auto_checkpoint_interval: float = 60.0,
+        session_timeout: float = 3600.0,
+    ) -> None:
+        self._state_serializer = state_serializer or StateSerializer()
+        self._memory_store = memory_store or MemoryStore()
+        self._session_manager = SessionManager(
+            state_serializer=self._state_serializer,
+            memory_store=self._memory_store,
+        )
+        self._host = host
+        self._port = port
+        self._auto_checkpoint_interval = auto_checkpoint_interval
+        self._session_timeout = session_timeout
+        self._start_time = time.monotonic()
+        self._shutdown_event = asyncio.Event()
+        self._heartbeat_task: asyncio.Task | None = None
+        self._cleanup_task: asyncio.Task | None = None
+        self._server_task: asyncio.Task | None = None
+
+    @property
+    def session_manager(self) -> SessionManager:
+        return self._session_manager
+
+    @property
+    def uptime_seconds(self) -> float:
+        return time.monotonic() - self._start_time
+
+    def health(self) -> HealthResponse:
+        active = sum(
+            1
+            for s in self._session_manager.list_sessions()
+            if s.status.value == "running"
+        )
+        return HealthResponse(
+            status="healthy",
+            uptime_seconds=self.uptime_seconds,
+            active_sessions=active,
+        )
+
+    async def start(self) -> None:
+        logger.info("AgentDaemon starting on %s:%d", self._host, self._port)
+        PID_DIR.mkdir(parents=True, exist_ok=True)
+        PID_FILE.write_text(str(os.getpid()))
+
+        loop = asyncio.get_event_loop()
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            loop.add_signal_handler(sig, self._handle_signal, sig)
+
+        self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
+        self._cleanup_task = asyncio.create_task(self._cleanup_loop())
+
+        try:
+            from .server import create_app
+            import uvicorn
+
+            app = create_app(self)
+            config = uvicorn.Config(app, host=self._host, port=self._port, log_level="info")
+            server = uvicorn.Server(config)
+            self._server_task = asyncio.create_task(server.serve())
+            logger.info("AgentDaemon HTTP server started on %s:%d", self._host, self._port)
+            await self._shutdown_event.wait()
+            await self._graceful_shutdown()
+        finally:
+            self._remove_pid()
+
+    async def _graceful_shutdown(self) -> None:
+        logger.info("Starting graceful shutdown...")
+        if self._heartbeat_task and not self._heartbeat_task.done():
+            self._heartbeat_task.cancel()
+        if self._cleanup_task and not self._cleanup_task.done():
+            self._cleanup_task.cancel()
+        if self._server_task and not self._server_task.done():
+            self._server_task.cancel()
+        await self._session_manager.shutdown()
+        logger.info("Graceful shutdown complete")
+
+    def _handle_signal(self, sig: signal.Signals) -> None:
+        logger.info("Received signal %s, initiating shutdown", sig.name)
+        self._shutdown_event.set()
+
+    async def _heartbeat_loop(self) -> None:
+        try:
+            while True:
+                sessions = self._session_manager.list_sessions()
+                for s in sessions:
+                    if s.status.value == "running":
+                        logger.debug("Heartbeat: session %s is running", s.session_id)
+                await asyncio.sleep(10.0)
+        except asyncio.CancelledError:
+            logger.info("Heartbeat loop cancelled")
+
+    async def _cleanup_loop(self) -> None:
+        try:
+            while True:
+                sessions = self._session_manager.list_sessions()
+                for s in sessions:
+                    if s.status.value == "stopped":
+                        checkpoints = self._state_serializer.list_checkpoints(s.session_id)
+                        if len(checkpoints) > 10:
+                            pruned = self._state_serializer.prune_checkpoints(s.session_id, keep_last=5)
+                            logger.info("Cleanup: pruned %d checkpoints for session %s", pruned, s.session_id)
+                await asyncio.sleep(300.0)
+        except asyncio.CancelledError:
+            logger.info("Cleanup loop cancelled")
+
+    def _remove_pid(self) -> None:
+        try:
+            PID_FILE.unlink(missing_ok=True)
+        except OSError:
+            pass
+
+    @staticmethod
+    def is_running() -> bool:
+        if not PID_FILE.exists():
+            return False
+        try:
+            pid = int(PID_FILE.read_text().strip())
+            os.kill(pid, 0)
+            return True
+        except (ProcessLookupError, ValueError, OSError):
+            try:
+                PID_FILE.unlink(missing_ok=True)
+            except OSError:
+                pass
+            return False
+
+    @staticmethod
+    def stop_running() -> bool:
+        if not PID_FILE.exists():
+            return False
+        try:
+            pid = int(PID_FILE.read_text().strip())
+            os.kill(pid, signal.SIGTERM)
+            logger.info("Sent SIGTERM to agentd (pid=%d)", pid)
+            return True
+        except ProcessLookupError:
+            PID_FILE.unlink(missing_ok=True)
+            return False
+        except (ValueError, OSError) as e:
+            logger.error("Failed to stop agentd: %s", e)
+            return False

agent_runtime/memory_store.py

@@ -0,0 +1,244 @@
+"""Persistent memory store with short-term and long-term memory."""
+
+from __future__ import annotations
+
+import json
+import logging
+import math
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from sqlalchemy import (
+    Column,
+    DateTime,
+    Float,
+    Integer,
+    LargeBinary,
+    String,
+    Text,
+    create_engine,
+    text,
+)
+from sqlalchemy.orm import DeclarativeBase, Session, sessionmaker
+
+from .models import MemoryEntry, MemorySearchResult
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_DB_PATH = Path.home() / ".agent_runtime" / "memory.db"
+
+SHORT_TERM_WINDOW = 50
+
+
+class MemBase(DeclarativeBase):
+    pass
+
+
+class LongTermMemoryRow(MemBase):
+    __tablename__ = "long_term_memory"
+
+    key = Column(String(512), primary_key=True)
+    value_json = Column(Text, nullable=False)
+    embedding_blob = Column(LargeBinary, nullable=True)
+    timestamp = Column(DateTime, default=lambda: datetime.now(timezone.utc))
+    access_count = Column(Integer, default=1)
+
+
+class ShortTermMemoryRow(MemBase):
+    __tablename__ = "short_term_memory"
+
+    id = Column(String(64), primary_key=True)
+    session_id = Column(String(64), nullable=False, index=True)
+    role = Column(String(32), nullable=False)
+    content = Column(Text, default="")
+    timestamp = Column(DateTime, default=lambda: datetime.now(timezone.utc))
+
+
+class MemoryConsolidationRow(MemBase):
+    __tablename__ = "memory_consolidations"
+
+    id = Column(String(64), primary_key=True)
+    session_id = Column(String(64), nullable=False, index=True)
+    summary = Column(Text, default="")
+    from_count = Column(Integer, default=0)
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc))
+
+
+class MemoryStore:
+    def __init__(self, db_path: Path | str | None = None) -> None:
+        if db_path is None:
+            db_path = DEFAULT_DB_PATH
+        self.db_path = Path(db_path)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self.engine = create_engine(f"sqlite:///{self.db_path}", echo=False)
+        MemBase.metadata.create_all(self.engine)
+        self._session_factory = sessionmaker(bind=self.engine)
+
+    def _get_session(self) -> Session:
+        return self._session_factory()
+
+    def store(self, key: str, value: Any, embedding: list[float] | None = None) -> None:
+        with self._get_session() as db:
+            row = db.get(LongTermMemoryRow, key)
+            if row is None:
+                row = LongTermMemoryRow(key=key)
+                db.add(row)
+            row.value_json = json.dumps(value, default=str)
+            row.embedding_blob = self._encode_embedding(embedding)
+            row.timestamp = datetime.now(timezone.utc)
+            row.access_count = (row.access_count or 0) + 1
+            db.commit()
+        logger.info("Stored memory key=%s", key)
+
+    def retrieve(self, key: str) -> MemoryEntry | None:
+        with self._get_session() as db:
+            row = db.get(LongTermMemoryRow, key)
+            if row is None:
+                return None
+            row.access_count = (row.access_count or 0) + 1
+            db.commit()
+        return MemoryEntry(
+            key=row.key,
+            value=json.loads(row.value_json),
+            embedding=self._decode_embedding(row.embedding_blob),
+            timestamp=row.timestamp,
+        )
+
+    def search(self, query_embedding: list[float], limit: int = 10) -> list[MemorySearchResult]:
+        results: list[MemorySearchResult] = []
+        with self._get_session() as db:
+            rows = db.query(LongTermMemoryRow).all()
+        for row in rows:
+            emb = self._decode_embedding(row.embedding_blob)
+            if emb is None:
+                continue
+            score = self._cosine_similarity(query_embedding, emb)
+            results.append(
+                MemorySearchResult(
+                    key=row.key,
+                    value=json.loads(row.value_json),
+                    score=score,
+                    timestamp=row.timestamp,
+                )
+            )
+        results.sort(key=lambda r: r.score, reverse=True)
+        return results[:limit]
+
+    def store_short_term(self, session_id: str, role: str, content: str) -> None:
+        with self._get_session() as db:
+            row = ShortTermMemoryRow(
+                id=uuid.uuid4().hex[:16],
+                session_id=session_id,
+                role=role,
+                content=content,
+            )
+            db.add(row)
+            db.commit()
+        self._prune_short_term(session_id)
+
+    def get_short_term(self, session_id: str, last_n: int = SHORT_TERM_WINDOW) -> list[dict[str, Any]]:
+        with self._get_session() as db:
+            rows = (
+                db.query(ShortTermMemoryRow)
+                .filter(ShortTermMemoryRow.session_id == session_id)
+                .order_by(ShortTermMemoryRow.timestamp.desc())
+                .limit(last_n)
+                .all()
+            )
+        rows.reverse()
+        return [{"role": r.role, "content": r.content, "timestamp": r.timestamp.isoformat()} for r in rows]
+
+    def consolidate(self, session_id: str) -> str | None:
+        messages = self.get_short_term(session_id, last_n=SHORT_TERM_WINDOW)
+        if len(messages) < 5:
+            logger.info("Not enough short-term memory to consolidate for %s", session_id)
+            return None
+        summary_parts = []
+        for msg in messages:
+            summary_parts.append(f"[{msg['role']}] {msg['content'][:200]}")
+        summary = "\n".join(summary_parts)
+        consolidation_id = uuid.uuid4().hex[:16]
+        with self._get_session() as db:
+            row = MemoryConsolidationRow(
+                id=consolidation_id,
+                session_id=session_id,
+                summary=summary,
+                from_count=len(messages),
+            )
+            db.add(row)
+            db.commit()
+        self.store(
+            key=f"consolidation:{session_id}:{consolidation_id}",
+            value={"summary": summary, "message_count": len(messages)},
+        )
+        logger.info("Consolidated %d messages for session %s", len(messages), session_id)
+        return consolidation_id
+
+    def list_keys(self, prefix: str = "") -> list[str]:
+        with self._get_session() as db:
+            if prefix:
+                rows = db.query(LongTermMemoryRow.key).filter(
+                    LongTermMemoryRow.key.like(f"{prefix}%")
+                ).all()
+            else:
+                rows = db.query(LongTermMemoryRow.key).all()
+        return [r[0] for r in rows]
+
+    def delete(self, key: str) -> bool:
+        with self._get_session() as db:
+            row = db.get(LongTermMemoryRow, key)
+            if row is None:
+                return False
+            db.delete(row)
+            db.commit()
+        return True
+
+    def _prune_short_term(self, session_id: str) -> None:
+        with self._get_session() as db:
+            count = db.query(ShortTermMemoryRow).filter(
+                ShortTermMemoryRow.session_id == session_id
+            ).count()
+            if count > SHORT_TERM_WINDOW * 2:
+                subq = (
+                    db.query(ShortTermMemoryRow.id)
+                    .filter(ShortTermMemoryRow.session_id == session_id)
+                    .order_by(ShortTermMemoryRow.timestamp.desc())
+                    .limit(SHORT_TERM_WINDOW)
+                    .subquery()
+                )
+                db.execute(
+                    text(
+                        "DELETE FROM short_term_memory "
+                        "WHERE session_id = :sid "
+                        "AND id NOT IN (SELECT id FROM subq)"
+                    ).bindparams(sid=session_id)
+                )
+                db.commit()
+
+    @staticmethod
+    def _encode_embedding(embedding: list[float] | None) -> bytes | None:
+        if embedding is None:
+            return None
+        import struct
+        return struct.pack(f"{len(embedding)}d", *embedding)
+
+    @staticmethod
+    def _decode_embedding(blob: bytes | None) -> list[float] | None:
+        if blob is None:
+            return None
+        import struct
+        count = len(blob) // 8
+        return list(struct.unpack(f"{count}d", blob))
+
+    @staticmethod
+    def _cosine_similarity(a: list[float], b: list[float]) -> float:
+        if len(a) != len(b):
+            return 0.0
+        dot = sum(x * y for x, y in zip(a, b))
+        mag_a = math.sqrt(sum(x * x for x in a))
+        mag_b = math.sqrt(sum(x * x for x in b))
+        if mag_a == 0 or mag_b == 0:
+            return 0.0
+        return dot / (mag_a * mag_b)

agent_runtime/models.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class SessionStatus(str, Enum):
+    CREATED = "created"
+    RUNNING = "running"
+    PAUSED = "paused"
+    STOPPED = "stopped"
+    ERROR = "error"
+
+
+class ToolCall(BaseModel):
+    name: str
+    arguments: dict[str, Any] = Field(default_factory=dict)
+    result: Any = None
+
+
+class Message(BaseModel):
+    role: str
+    content: str = ""
+    tool_calls: list[ToolCall] = Field(default_factory=list)
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+class SessionCreate(BaseModel):
+    name: str
+    model: str
+    system_prompt: str = ""
+    tools: list[str] = Field(default_factory=list)
+
+
+class SessionState(BaseModel):
+    session_id: str = Field(default_factory=lambda: uuid.uuid4().hex[:16])
+    name: str = ""
+    model: str = ""
+    system_prompt: str = ""
+    tools: list[str] = Field(default_factory=list)
+    status: SessionStatus = SessionStatus.CREATED
+    memory: dict[str, Any] = Field(default_factory=dict)
+    messages: list[Message] = Field(default_factory=list)
+    tool_history: list[ToolCall] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+class SessionResume(BaseModel):
+    session_id: str
+    checkpoint_id: str | None = None
+
+
+class MemoryEntry(BaseModel):
+    key: str
+    value: Any
+    embedding: list[float] | None = None
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+class MemorySearchResult(BaseModel):
+    key: str
+    value: Any
+    score: float
+    timestamp: datetime
+
+
+class CheckpointInfo(BaseModel):
+    checkpoint_id: str
+    session_id: str
+    created_at: datetime
+    label: str | None = None
+
+
+class MemoryStoreRequest(BaseModel):
+    key: str
+    value: Any
+
+
+class MemoryRetrieveResponse(BaseModel):
+    key: str
+    value: Any
+    timestamp: datetime
+
+
+class HealthResponse(BaseModel):
+    status: str
+    uptime_seconds: float
+    active_sessions: int