agenthandler 0.92.0__py3-none-any.whl

agenthandler/session.py

@@ -0,0 +1,391 @@
+"""Session manager — lifecycle management for long-running agent sessions.
+
+Wraps a Supervisor + StateStore and adds start / pause / resume / stop.
+
+Security invariants:
+- Policy is IMMUTABLE after start(). resume() always rebuilds the Supervisor
+  from the original policy stored at creation time — never from agent-controlled
+  checkpoint data. An agent cannot weaken its own supervision.
+- Policy integrity is verified via HMAC checksum on resume. If the stored
+  policy has been tampered with, resume is rejected.
+- Payload is UNTRUSTED. It is validated for size/serializability on write, and
+  agents consuming it after resume should treat it like user input.
+- Audit entries are persisted to the store so they survive crashes.
+- Per-session locking prevents race conditions on concurrent lifecycle operations.
+
+Usage:
+    from agenthandler import SessionManager, MemoryStore
+
+    store = MemoryStore()
+    mgr = SessionManager(store)
+
+    session_id = mgr.start("my-agent", {"max_iterations": 10, "tool_timeout": 30})
+    sv = mgr.get_supervisor(session_id)
+    # ... use sv.call() in your agent loop ...
+
+    mgr.pause(session_id)    # agent will raise AgentPaused on next call()
+    mgr.resume(session_id)   # rehydrate and continue
+    mgr.stop(session_id)     # mark complete
+"""
+
+import hashlib
+import hmac
+import json
+
+# Key for HMAC policy checksum — not a secret (it's in the source),
+# but prevents casual tampering of the SQLite file.  For real security,
+# set AGENTHANDLER_POLICY_KEY env var.
+import os
+import threading
+from typing import Any, Dict, List, Optional
+
+from .approval import ApprovalQueue
+from .audit import AuditLog, MemoryAuditSink
+from .errors import AgentHandlerError
+from .observe import Observer
+from .policy import Policy
+from .store import Checkpoint, SessionStatus, StateStore, new_session_id, validate_payload
+from .supervisor import Supervisor
+
+_POLICY_HMAC_KEY = os.environ.get(
+    "AGENTHANDLER_POLICY_KEY", "agenthandler-policy-integrity"
+).encode()
+
+
+def _policy_checksum(policy_dict: Dict[str, Any]) -> str:
+    """Compute an HMAC checksum for a policy dict."""
+    serialized = json.dumps(policy_dict, sort_keys=True, default=str).encode()
+    return hmac.new(_POLICY_HMAC_KEY, serialized, hashlib.sha256).hexdigest()
+
+
+class SessionManager:
+    """Lifecycle manager for agent sessions backed by a StateStore.
+
+    Keeps active Supervisors in memory and persists state to the store.
+    After a crash, create a new SessionManager with the same store and
+    call resume() to pick up where you left off.
+
+    Thread-safe: uses per-session locks for lifecycle operations to prevent
+    race conditions from concurrent pause/resume/stop calls.
+    """
+
+    def __init__(
+        self,
+        store: StateStore,
+        pre_guardrails: Optional[List[Any]] = None,
+        post_guardrails: Optional[List[Any]] = None,
+        pricing: Optional[Any] = None,
+    ):
+        from .observe import PricingTable
+
+        self._store = store
+        self._supervisors: Dict[str, Supervisor] = {}
+        self._audit_sinks: Dict[str, MemoryAuditSink] = {}
+        self._original_policies: Dict[str, Dict[str, Any]] = {}
+        self._stateless_sessions: set[str] = set()
+        self._approval_queue = ApprovalQueue()
+        # Default to the built-in pricing table so costs work out of the box.
+        self._observer = Observer(pricing=pricing or PricingTable.default())
+        self._pre_guardrails: List[Any] = pre_guardrails or []
+        self._post_guardrails: List[Any] = post_guardrails or []
+        self._lock = threading.Lock()  # protects the dicts above
+        self._session_locks: Dict[str, threading.Lock] = {}  # per-session locks
+
+    def _get_session_lock(self, session_id: str) -> threading.Lock:
+        """Get or create a per-session lock."""
+        with self._lock:
+            if session_id not in self._session_locks:
+                self._session_locks[session_id] = threading.Lock()
+            return self._session_locks[session_id]
+
+    @property
+    def approval_queue(self) -> ApprovalQueue:
+        """The shared approval queue for all sessions."""
+        return self._approval_queue
+
+    @property
+    def observer(self) -> Observer:
+        """The shared observer for all sessions."""
+        return self._observer
+
+    def start(
+        self,
+        agent_id: str,
+        policy_dict: Optional[Dict[str, Any]] = None,
+        payload: Optional[Dict[str, Any]] = None,
+        stateless: bool = False,
+    ) -> str:
+        """Start a new agent session.
+
+        Args:
+            agent_id: Identifier for the agent type.
+            policy_dict: Policy configuration (passed to Policy.from_dict).
+                         This is stored immutably — the agent can never change it.
+            payload: Opaque JSON the agent can stash intermediate work in.
+                     Treated as untrusted data. Validated for size limits.
+            stateless: If True, the session lives in memory only — no
+                       checkpoints written to the store, no crash recovery.
+                       You still get supervision, audit, and pause/stop controls.
+
+        Returns:
+            session_id for the new session.
+        """
+        sid = new_session_id()
+        safe_policy_dict = policy_dict or {}
+        policy = Policy.from_dict(safe_policy_dict)
+
+        # Validate payload before storing
+        safe_payload = validate_payload(payload or {})
+
+        sink = MemoryAuditSink()
+        audit = AuditLog(sid, sinks=[sink])
+
+        sv = Supervisor(
+            policy,
+            audit=audit,
+            store=None if stateless else self._store,
+            session_id=sid,
+            agent_id=agent_id,
+            approval_queue=self._approval_queue,
+            observer=self._observer,
+            pre_guardrails=self._pre_guardrails,
+            post_guardrails=self._post_guardrails,
+        )
+
+        # Store the ORIGINAL policy — this is immutable for the session's lifetime
+        frozen_policy = policy.to_dict()
+        checksum = _policy_checksum(frozen_policy)
+
+        checkpoint = Checkpoint(
+            session_id=sid,
+            agent_id=agent_id,
+            status=SessionStatus.RUNNING,
+            token_limit=policy.token_budget,
+            iteration_limit=policy.max_iterations,
+            policy_dict=frozen_policy,
+            payload=safe_payload,
+            stateless=stateless,
+            policy_checksum=checksum,
+        )
+        self._store.save_checkpoint(checkpoint)
+
+        with self._lock:
+            self._supervisors[sid] = sv
+            self._audit_sinks[sid] = sink
+            self._original_policies[sid] = frozen_policy
+            if stateless:
+                self._stateless_sessions.add(sid)
+
+        return sid
+
+    def pause(self, session_id: str) -> None:
+        """Pause an agent session. The Supervisor will raise AgentPaused on next call()."""
+        session_lock = self._get_session_lock(session_id)
+        with session_lock:
+            cp = self._store.load_checkpoint(session_id)
+            if cp is None:
+                raise AgentHandlerError.session_not_found(session_id)
+
+            cp.status = SessionStatus.PAUSED
+            self._persist_audit(session_id, cp)
+            self._store.save_checkpoint(cp)
+
+            with self._lock:
+                sv = self._supervisors.get(session_id)
+            if sv is not None:
+                sv.paused = True
+
+    def resume(self, session_id: str) -> Supervisor:
+        """Resume a paused or previously-crashed session.
+
+        Rehydrates a Supervisor from the last checkpoint. Policy is always
+        rebuilt from the ORIGINAL immutable policy stored at start() — never
+        from any agent-modified data in the checkpoint.
+
+        Policy integrity is verified via HMAC checksum — if the stored policy
+        has been tampered with, resume is rejected.
+
+        Stateless sessions cannot be resumed after a crash — their state
+        only exists in memory.
+
+        Returns:
+            The restored Supervisor, ready for use.
+        """
+        session_lock = self._get_session_lock(session_id)
+        with session_lock:
+            cp = self._store.load_checkpoint(session_id)
+            if cp is None:
+                raise AgentHandlerError.session_not_found(session_id)
+
+            # Stateless sessions can be unpaused (supervisor still in memory)
+            # but cannot be recovered after a crash
+            with self._lock:
+                in_memory = session_id in self._supervisors
+            if cp.stateless and not in_memory:
+                raise AgentHandlerError(
+                    "session_not_recoverable",
+                    f"Session {session_id} is stateless and cannot be resumed after a crash",
+                )
+
+            # Crash loop protection
+            policy = Policy.from_dict(cp.policy_dict)
+            if cp.resume_count >= policy.max_resumes:
+                cp.status = SessionStatus.FAILED
+                cp.failure_reason = (
+                    f"Crash loop: resumed {cp.resume_count} times (limit: {policy.max_resumes})"
+                )
+                self._store.save_checkpoint(cp)
+                raise AgentHandlerError.max_resumes_exceeded(
+                    session_id, cp.resume_count, policy.max_resumes
+                )
+
+            # Policy integrity check — verify HMAC checksum
+            with self._lock:
+                original = self._original_policies.get(session_id)
+            if original is None:
+                original = cp.policy_dict
+            if cp.policy_checksum:
+                expected = _policy_checksum(original)
+                if not hmac.compare_digest(cp.policy_checksum, expected):
+                    cp.status = SessionStatus.FAILED
+                    cp.failure_reason = "Policy integrity check failed — possible tampering"
+                    self._store.save_checkpoint(cp)
+                    raise AgentHandlerError(
+                        "policy_tampered",
+                        f"Session {session_id}: policy checksum mismatch. "
+                        "The stored policy may have been tampered with.",
+                    )
+
+            cp.resume_count += 1
+            cp.status = SessionStatus.RUNNING
+            self._store.save_checkpoint(cp)
+
+        sink = MemoryAuditSink()
+        audit = AuditLog(session_id, sinks=[sink])
+
+        sv = Supervisor.restore_from_checkpoint(
+            cp,
+            audit=audit,
+            store=self._store,
+            policy_override=original,
+            approval_queue=self._approval_queue,
+            observer=self._observer,
+            pre_guardrails=self._pre_guardrails,
+            post_guardrails=self._post_guardrails,
+        )
+        sv.paused = False
+
+        with self._lock:
+            self._supervisors[session_id] = sv
+            self._audit_sinks[session_id] = sink
+            self._original_policies[session_id] = original
+
+        return sv
+
+    def stop(self, session_id: str) -> None:
+        """Stop an agent session. Calls supervisor.finish() and marks stopped."""
+        session_lock = self._get_session_lock(session_id)
+        with session_lock:
+            cp = self._store.load_checkpoint(session_id)
+            if cp is None:
+                raise AgentHandlerError.session_not_found(session_id)
+
+            with self._lock:
+                sv = self._supervisors.get(session_id)
+
+            if sv is not None:
+                sv.finish()
+
+            cp.status = SessionStatus.STOPPED
+            if sv is not None:
+                data = sv.to_checkpoint_data()
+                cp.iterations = data["iterations"]
+                cp.tokens_used = data["tokens_used"]
+
+            self._persist_audit(session_id, cp)
+
+            with self._lock:
+                self._supervisors.pop(session_id, None)
+                self._audit_sinks.pop(session_id, None)
+                self._original_policies.pop(session_id, None)
+
+            self._store.save_checkpoint(cp)
+
+    def restart(self, session_id: str) -> str:
+        """Restart a stopped or failed session with the same policy and agent ID.
+
+        Creates a fresh session using the original policy from the old session.
+        The old session is preserved for audit purposes.
+
+        Returns:
+            The new session_id.
+        """
+        session_lock = self._get_session_lock(session_id)
+        with session_lock:
+            cp = self._store.load_checkpoint(session_id)
+            if cp is None:
+                raise AgentHandlerError.session_not_found(session_id)
+
+            with self._lock:
+                self._supervisors.pop(session_id, None)
+                self._audit_sinks.pop(session_id, None)
+                self._original_policies.pop(session_id, None)
+                self._stateless_sessions.discard(session_id)
+
+        return self.start(
+            agent_id=cp.agent_id,
+            policy_dict=cp.policy_dict,
+            stateless=cp.stateless,
+        )
+
+    def status(self, session_id: str) -> Optional[Checkpoint]:
+        """Get the current checkpoint for a session."""
+        return self._store.load_checkpoint(session_id)
+
+    def list_sessions(self) -> List[Checkpoint]:
+        """List all sessions."""
+        return self._store.list_sessions()
+
+    def get_supervisor(self, session_id: str) -> Optional[Supervisor]:
+        """Get the active Supervisor for a session (None if not in memory)."""
+        with self._lock:
+            return self._supervisors.get(session_id)
+
+    def get_audit_entries(self, session_id: str) -> list[Dict[str, Any]]:
+        """Get audit log entries for a session (in-memory + persisted)."""
+        cp = self._store.load_checkpoint(session_id)
+        persisted = cp.audit_log if cp is not None else []
+
+        with self._lock:
+            sink = self._audit_sinks.get(session_id)
+        in_memory = [e.to_dict() for e in sink.entries] if sink is not None else []
+
+        return persisted + in_memory
+
+    def update_payload(self, session_id: str, payload: Dict[str, Any]) -> None:
+        """Update the opaque payload for a session.
+
+        The payload is validated for size limits and serializability.
+        Treat payload as UNTRUSTED — it may contain agent-controlled data.
+        """
+        session_lock = self._get_session_lock(session_id)
+        with session_lock:
+            cp = self._store.load_checkpoint(session_id)
+            if cp is None:
+                raise AgentHandlerError.session_not_found(session_id)
+            cp.payload = validate_payload(payload)
+            self._store.save_checkpoint(cp)
+
+    def delete_expired(self, max_age_seconds: float) -> int:
+        """Delete sessions older than max_age_seconds."""
+        if hasattr(self._store, "delete_expired"):
+            count: int = self._store.delete_expired(max_age_seconds)
+            return count
+        return 0
+
+    def _persist_audit(self, session_id: str, cp: Checkpoint) -> None:
+        """Flush in-memory audit entries into the checkpoint for persistence."""
+        with self._lock:
+            sink = self._audit_sinks.get(session_id)
+        if sink is not None:
+            cp.audit_log = cp.audit_log + [e.to_dict() for e in sink.entries]

agenthandler/skill.py

@@ -0,0 +1,265 @@
+"""Skill definitions — framework-agnostic skill format with file-based CRUD."""
+
+import json
+import os
+import re
+import threading
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class ToolParameter:
+    """A parameter on a tool."""
+
+    name: str
+    type: str = "string"
+    description: str = ""
+    required: bool = False
+    default: Any = None
+
+
+@dataclass
+class ToolDefinition:
+    """A tool that a skill can use."""
+
+    name: str
+    description: str = ""
+    parameters: List[ToolParameter] = field(default_factory=list)
+
+
+@dataclass
+class Skill:
+    """A complete skill definition — what the agent does, how, and within what limits.
+
+    This is the agenthandler-native skill format. It can be converted to/from
+    POML, JSON, YAML, or any other format your agent framework uses.
+    """
+
+    name: str
+    description: str
+    triggers: List[str] = field(default_factory=list)
+    version: str = "1.0"
+
+    # What the agent should do
+    role: str = ""
+    task: str = ""
+    instructions: List[str] = field(default_factory=list)
+    examples: List[Dict[str, str]] = field(default_factory=list)
+    output_format: str = ""
+
+    # What tools are available
+    tools: List[ToolDefinition] = field(default_factory=list)
+
+    # Supervision limits (maps directly to Policy.from_dict)
+    supervision: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to a plain dictionary."""
+        d = asdict(self)
+        # Drop empty/default fields for cleaner output
+        return {k: v for k, v in d.items() if v}
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Skill":
+        """Create a Skill from a dictionary."""
+        tools = []
+        for t in d.get("tools", []):
+            params = [ToolParameter(**p) for p in t.get("parameters", [])]
+            tools.append(
+                ToolDefinition(
+                    name=t["name"],
+                    description=t.get("description", ""),
+                    parameters=params,
+                )
+            )
+
+        return cls(
+            name=d["name"],
+            description=d.get("description", ""),
+            triggers=d.get("triggers", []),
+            version=d.get("version", "1.0"),
+            role=d.get("role", ""),
+            task=d.get("task", ""),
+            instructions=d.get("instructions", []),
+            examples=d.get("examples", []),
+            output_format=d.get("output_format", ""),
+            tools=tools,
+            supervision=d.get("supervision", {}),
+        )
+
+    def to_poml(self) -> str:
+        """Render as POML format (compatible with moneypenny and other POML loaders)."""
+        lines = ["<!--"]
+        lines.append("metadata:")
+        lines.append(f"  description: {self.description}")
+        if self.triggers:
+            lines.append(f"  triggers: {', '.join(self.triggers)}")
+        if self.version:
+            lines.append(f"  version: {self.version}")
+
+        if self.tools:
+            lines.append("")
+            lines.append("tools:")
+            for tool in self.tools:
+                lines.append(f"  - name: {tool.name}")
+                if tool.description:
+                    lines.append(f"    description: {tool.description}")
+                if tool.parameters:
+                    lines.append("    parameters:")
+                    for p in tool.parameters:
+                        lines.append(f"      {p.name}:")
+                        lines.append(f"        type: {p.type}")
+                        if p.description:
+                            lines.append(f"        description: {p.description}")
+                        if p.required:
+                            lines.append("        required: true")
+                        if p.default is not None:
+                            lines.append(f"        default: {p.default}")
+
+        if self.supervision:
+            lines.append("")
+            lines.append("supervision:")
+            for k, v in self.supervision.items():
+                if isinstance(v, list):
+                    lines.append(f"  {k}:")
+                    for item in v:
+                        lines.append(f"    - {item}")
+                else:
+                    lines.append(f"  {k}: {v}")
+
+        lines.append("-->")
+        lines.append("")
+
+        if self.role:
+            lines.append(f"<role>\n{self.role}\n</role>")
+            lines.append("")
+
+        if self.task:
+            lines.append(f"<task>\n{self.task}\n</task>")
+            lines.append("")
+
+        if self.instructions:
+            lines.append("<instruction>")
+            for inst in self.instructions:
+                lines.append(f"- {inst}")
+            lines.append("</instruction>")
+            lines.append("")
+
+        for ex in self.examples:
+            lines.append("<example>")
+            if "user" in ex:
+                lines.append(f"User: {ex['user']}")
+            if "assistant" in ex:
+                lines.append(f"Assistant: {ex['assistant']}")
+            lines.append("</example>")
+            lines.append("")
+
+        if self.output_format:
+            lines.append(f"<output_format>\n{self.output_format}\n</output_format>")
+            lines.append("")
+
+        return "\n".join(lines)
+
+    def to_json(self, indent: int = 2) -> str:
+        """Serialize to JSON."""
+        return json.dumps(self.to_dict(), indent=indent, default=str)
+
+
+def _slugify(name: str) -> str:
+    """Convert a skill name to a safe filename slug."""
+    s = name.lower().strip()
+    s = re.sub(r"[^a-z0-9]+", "_", s)
+    return s.strip("_")
+
+
+class SkillStore:
+    """File-based CRUD for skills. Each skill is a JSON file on disk.
+
+    Usage:
+        store = SkillStore("~/.agenthandler/skills")
+        store.save(skill)
+        skill = store.get("web_research")
+        all_skills = store.list()
+        store.delete("web_research")
+    """
+
+    def __init__(self, directory: str):
+        self._dir = Path(os.path.expanduser(directory))
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+
+    @property
+    def directory(self) -> Path:
+        return self._dir
+
+    def _path(self, name: str) -> Path:
+        return self._dir / f"{_slugify(name)}.json"
+
+    def save(self, skill: Skill) -> Path:
+        """Save a skill to disk. Overwrites if exists. Returns file path."""
+        path = self._path(skill.name)
+        with self._lock:
+            path.write_text(skill.to_json())
+        return path
+
+    def get(self, name: str) -> Optional[Skill]:
+        """Load a skill by name. Returns None if not found."""
+        path = self._path(name)
+        if not path.exists():
+            return None
+        with self._lock:
+            data = json.loads(path.read_text())
+        return Skill.from_dict(data)
+
+    def list(self) -> List[Dict[str, str]]:
+        """List all skills (name + description). Lightweight — doesn't load full skills."""
+        skills = []
+        with self._lock:
+            for path in sorted(self._dir.glob("*.json")):
+                try:
+                    data = json.loads(path.read_text())
+                    skills.append(
+                        {
+                            "name": data.get("name", path.stem),
+                            "description": data.get("description", ""),
+                            "version": data.get("version", ""),
+                        }
+                    )
+                except (json.JSONDecodeError, KeyError):
+                    continue
+        return skills
+
+    def delete(self, name: str) -> bool:
+        """Delete a skill. Returns True if deleted, False if not found."""
+        path = self._path(name)
+        with self._lock:
+            if path.exists():
+                path.unlink()
+                return True
+        return False
+
+    def exists(self, name: str) -> bool:
+        """Check if a skill exists."""
+        return self._path(name).exists()
+
+    def export_poml(self, name: str) -> Optional[str]:
+        """Export a skill as POML format. Returns None if not found."""
+        skill = self.get(name)
+        if skill is None:
+            return None
+        return skill.to_poml()
+
+    def export_all_poml(self, output_dir: str) -> List[Path]:
+        """Export all skills as .poml files to a directory."""
+        out = Path(os.path.expanduser(output_dir))
+        out.mkdir(parents=True, exist_ok=True)
+        paths = []
+        for info in self.list():
+            skill = self.get(info["name"])
+            if skill:
+                path = out / f"{_slugify(skill.name)}.poml"
+                path.write_text(skill.to_poml())
+                paths.append(path)
+        return paths