apsimo 1.3.0__py3-none-any.whl

apsimo/services/instance.py

@@ -0,0 +1,297 @@
+"""User-manager autostart for one validated private instance, without a supervisor."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+import plistlib
+import re
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+
+
+class ServiceError(RuntimeError):
+    pass
+
+
+def _private_write(path, content):
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    fd, name = tempfile.mkstemp(prefix='.service-', dir=path.parent)
+    try:
+        with os.fdopen(fd, 'wb') as stream:
+            stream.write(content)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(name, path)
+    finally:
+        Path(name).unlink(missing_ok=True)
+
+
+def _systemd_quote(value):
+    value = str(value)
+    if any(c in value for c in '\n\r\0'):
+        raise ServiceError('Service paths must not contain line breaks or NUL')
+    return '"' + value.replace('\\', '\\\\').replace('"', '\\"').replace('%', '%%') + '"'
+
+
+def _systemd_path(value):
+    # These scalar settings take the whole path, unlike ExecStart's argv parser.
+    value = str(value)
+    if any(c in value for c in '\n\r\0') or value.rstrip() != value or value.endswith('\\'):
+        raise ServiceError('Unsupported line ending in service path')
+    return value.replace('%', '%%')
+
+
+class InstanceService:
+    def __init__(self, state, hermes_home, *, python=None, platform=None, home=None, runner=None):
+        self.state = Path(state).resolve()
+        self.hermes_home = Path(hermes_home).resolve()
+        # Resolving a venv's python symlink would select the system interpreter.
+        self.python = os.path.abspath(python or sys.executable)
+        self.platform = platform or sys.platform
+        self.home = Path(home or Path.home())
+        suffix = hashlib.sha256(os.fsencode(self.state)).hexdigest()[:20]
+        self.label = 'ai.apsimo.instance.' + suffix
+        if self.platform == 'darwin':
+            self.name = self.label + '.plist'
+            self.link = self.home / 'Library/LaunchAgents' / self.name
+            self.target = f'gui/{os.getuid()}/{self.label}'
+        elif self.platform.startswith('linux'):
+            self.name = 'apsimo-' + suffix + '.service'
+            config = Path(os.environ.get('XDG_CONFIG_HOME') or self.home / '.config')
+            self.link = config / 'systemd/user' / self.name
+            self.target = self.name
+        else:
+            raise ServiceError('Instance autostart supports Linux systemd user services and macOS launchd')
+        # Reuse the exact existing service identity instead of registering a
+        # second writer during a package rename. Fresh instances use Apsimo.
+        legacy_label = 'ai.colony.instance.' + suffix
+        legacy_name = (legacy_label + '.plist' if self.platform == 'darwin'
+                       else 'colony-' + suffix + '.service')
+        legacy_link = self.link.with_name(legacy_name)
+        legacy_definition = self.state / 'service' / legacy_name
+        if (legacy_link.exists() or legacy_link.is_symlink()):
+            if self.link.exists() or self.link.is_symlink():
+                raise ServiceError('Both legacy and canonical instance services exist; reconcile them before selection')
+            self.label, self.name, self.link = legacy_label, legacy_name, legacy_link
+            self.target = (f'gui/{os.getuid()}/{self.label}' if self.platform == 'darwin' else self.name)
+        elif legacy_definition.exists() and not (self.state / 'service' / self.name).exists():
+            self.label, self.name, self.link = legacy_label, legacy_name, legacy_link
+            self.target = (f'gui/{os.getuid()}/{self.label}' if self.platform == 'darwin' else self.name)
+        self.definition = self.state / 'service' / self.name
+        self.backup = self.definition.with_name(self.name + '.previous')
+        self.log = self.state / 'service' / 'sidecar.log'
+        self.runner = runner or subprocess.run
+
+    @classmethod
+    def selected(cls):
+        from apsimo.util.instance import load_environment
+        # A legacy state-dir environment is never sufficient to own a service.
+        if not os.environ.get('COLONY_STATE_DIR'):
+            load_environment()
+        if not os.environ.get('COLONY_STATE_DIR'):
+            raise ServiceError('Select a configured private instance with --instance')
+        os.environ['COLONY_INSTANCE_SELECTED'] = '1'
+        load_environment()
+        state = Path(os.environ['COLONY_STATE_DIR'])
+        manifest = json.loads((state / 'instance.json').read_text())
+        return cls(state, manifest['hermes_home'])
+
+    def _run(self, *args, check=True):
+        try:
+            result = self.runner(list(args), capture_output=True, text=True, timeout=30)
+        except (OSError, subprocess.SubprocessError) as exc:
+            raise ServiceError(f'User service manager unavailable ({type(exc).__name__})') from None
+        if check and result.returncode:
+            raise ServiceError(f'User service command failed: {args[0]} {args[1]} (exit {result.returncode})')
+        return result
+
+    def _manager_ready(self):
+        if self.platform == 'darwin':
+            self._run('launchctl', 'print', f'gui/{os.getuid()}')
+        else:
+            self._run('systemctl', '--user', 'show-environment')
+
+    def _owned(self):
+        if not self.link.exists() and not self.link.is_symlink():
+            return False
+        if not self.link.is_symlink() or self.link.resolve() != self.definition:
+            raise ServiceError(f'Refusing an unowned service definition at {self.link}')
+        if not self.definition.is_file():
+            raise ServiceError('Private service definition is missing; reinstall it before managing the service')
+        return True
+
+    def render(self):
+        arguments = [self.python, '-m', 'apsimo', '--instance', str(self.state), 'start']
+        environment = {'HERMES_HOME': str(self.hermes_home), 'APSIMO_INSTANCE_SERVICE': self.label,
+                       'PYTHONUNBUFFERED': '1'}
+        if self.platform == 'darwin':
+            return plistlib.dumps({'Label': self.label, 'ProgramArguments': arguments,
+                'WorkingDirectory': str(self.state), 'EnvironmentVariables': environment,
+                'RunAtLoad': True, 'KeepAlive': True, 'ThrottleInterval': 5,
+                'ExitTimeOut': 20, 'Umask': 0o077,
+                'StandardOutPath': str(self.log), 'StandardErrorPath': str(self.log)}, sort_keys=True)
+        quote = _systemd_quote
+        return ('[Unit]\nDescription=Apsimo private instance ' + self.label + '\n\n[Service]\nType=exec\n'
+                'WorkingDirectory=' + _systemd_path(self.state) + '\n'
+                # ':' disables dollar-variable substitution; %% escapes specifiers.
+                'ExecStart=:' + ' '.join(quote(arg) for arg in arguments) + '\n'
+                'Environment=' + ' '.join(quote(key + '=' + value) for key, value in environment.items()) + '\n'
+                'Restart=always\nRestartSec=5\nTimeoutStopSec=20\nUMask=0077\n'
+                'StandardOutput=append:' + _systemd_path(self.log) + '\n'
+                'StandardError=append:' + _systemd_path(self.log) + '\n\n[Install]\nWantedBy=default.target\n').encode()
+
+    def status(self):
+        owned = self._owned()
+        self._manager_ready()
+        result = {'instance': str(self.state), 'manager': 'launchd' if self.platform == 'darwin' else 'systemd-user',
+                  'label': self.label, 'definition': str(self.definition), 'installed': owned,
+                  'loaded': False, 'running': False, 'pid': None, 'autostart_scope': 'user-session'}
+        if self.platform == 'darwin':
+            response = self._run('launchctl', 'print', self.target, check=False)
+            result['loaded'] = response.returncode == 0
+            pid = re.search(r'^\s*pid = ([0-9]+)\s*$', response.stdout, re.MULTILINE)
+            if pid:
+                result['pid'], result['running'] = int(pid[1]), True
+        else:
+            response = self._run('systemctl', '--user', 'show', self.name,
+                '--property=LoadState,ActiveState,SubState,MainPID,UnitFileState', '--no-pager', check=False)
+            fields = dict(line.split('=', 1) for line in response.stdout.splitlines() if '=' in line)
+            result.update(state=fields.get('ActiveState', 'unknown'), substate=fields.get('SubState', 'unknown'),
+                          enabled=fields.get('UnitFileState') == 'enabled')
+            result['loaded'] = fields.get('LoadState') == 'loaded'
+            pid = fields.get('MainPID', '0')
+            result['pid'] = int(pid) if pid.isdigit() and int(pid) > 0 else None
+            result['running'] = bool(result['pid'] and fields.get('ActiveState') in {'active', 'activating'})
+        return result
+
+    def install(self):
+        content = self.render()  # Validate every path before writing anything.
+        self._manager_ready()
+        owned = self._owned()
+        previous = self.definition.read_bytes() if self.definition.is_file() else None
+        if previous != content and owned:
+            status = self.status()
+            if status['running'] or (self.platform == 'darwin' and status['loaded']):
+                raise ServiceError('Stop this instance service before changing its Python environment')
+        try:
+            if previous is not None and previous != content:
+                _private_write(self.backup, previous)
+            _private_write(self.definition, content)
+            self.link.parent.mkdir(parents=True, exist_ok=True)
+            if not owned:
+                self.link.symlink_to(self.definition)
+            if not self.log.exists():
+                _private_write(self.log, b'')
+            if self.platform == 'darwin':
+                self._run('launchctl', 'enable', self.target)
+            else:
+                self._run('systemctl', '--user', 'daemon-reload')
+                self._run('systemctl', '--user', 'enable', self.name)
+        except (ServiceError, OSError):
+            # Preserve the previous definition; no instance was started here.
+            if previous is not None:
+                _private_write(self.definition, previous)
+            if not owned and self.link.is_symlink() and self.link.resolve() == self.definition:
+                if self.platform != 'darwin':
+                    self._run('systemctl', '--user', 'disable', self.name, check=False)
+                # A failed enable may have created its exact wanted-by link.
+            if not owned and self.link.is_symlink() and self.link.resolve() == self.definition:
+                self.link.unlink()
+            if previous is None:
+                self.definition.unlink(missing_ok=True)
+            if self.platform != 'darwin':
+                self._run('systemctl', '--user', 'daemon-reload', check=False)
+            raise
+        return self.status()
+
+    def _require_installed(self):
+        if not self._owned():
+            raise ServiceError('Service is not installed for this instance; run apsimo service install')
+        self._manager_ready()
+
+    def healthy(self):
+        import httpx
+        host = os.environ.get('COLONY_SIDECAR_HOST', '127.0.0.1')
+        host = {'0.0.0.0': '127.0.0.1', '::': '::1'}.get(host, host)
+        if ':' in host:
+            host = '[' + host + ']'
+        key = os.environ.get('COLONY_CLIENT_API_KEY') or os.environ.get('COLONY_API_KEY', '')
+        try:
+            response = httpx.get(f'http://{host}:{os.environ.get("COLONY_SIDECAR_PORT", "7777")}/v1/host/health',
+                headers={'Authorization': 'Bearer ' + key}, timeout=1, trust_env=False, follow_redirects=False)
+            return response.status_code == 200 and response.json().get('status') == 'ok'
+        except (httpx.HTTPError, ValueError):
+            return False
+
+    def start(self, *, restart=False, timeout=30):
+        self._require_installed()
+        status = self.status()
+        if not status['running']:
+            host = os.environ.get('COLONY_SIDECAR_HOST', '127.0.0.1')
+            host = {'0.0.0.0': '127.0.0.1', '::': '::1'}.get(host, host)
+            try:
+                with socket.create_connection((host, int(os.environ.get('COLONY_SIDECAR_PORT', '7777'))), timeout=.2):
+                    raise ServiceError('Instance port is already occupied; stop its current process before service start')
+            except OSError:
+                pass
+        if self.platform == 'darwin':
+            if status['loaded']:
+                if restart:
+                    self._run('launchctl', 'kickstart', '-k', self.target)
+            else:
+                self._run('launchctl', 'bootstrap', f'gui/{os.getuid()}', str(self.link))
+        else:
+            self._run('systemctl', '--user', 'restart' if restart else 'start', self.name)
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            result = self.status()
+            if result['running'] and self.healthy():
+                return {**result, 'ready': True}
+            time.sleep(.2)
+        raise ServiceError(f'Service did not become HTTP-ready; inspect {self.log}. It remains installed for recovery.')
+
+    def stop(self):
+        self._require_installed()
+        if self.platform == 'darwin':
+            if self.status()['loaded']:
+                self._run('launchctl', 'bootout', self.target)
+        else:
+            self._run('systemctl', '--user', 'stop', self.name)
+        # launchctl bootout can return while its process is still shutting down.
+        # Do not remove the definition or report a stopped service prematurely.
+        deadline = time.monotonic() + 30
+        while time.monotonic() < deadline:
+            result = self.status()
+            if not result['running'] and (self.platform != 'darwin' or not result['loaded']):
+                return result
+            time.sleep(.1)
+        raise ServiceError('User manager has not finished stopping this instance; its registration is retained')
+
+    def uninstall(self):
+        if not self._owned():
+            return self.status()
+        self.stop()
+        if self.platform != 'darwin':
+            self._run('systemctl', '--user', 'disable', self.name)
+        # systemctl disable may remove this exact link itself.
+        if self.link.is_symlink() and self.link.resolve() == self.definition:
+            self.link.unlink()
+        if self.platform != 'darwin':
+            self._run('systemctl', '--user', 'daemon-reload')
+        return self.status()
+
+
+def manage(action):
+    service = InstanceService.selected()
+    if action == 'restart':
+        result = service.start(restart=True)
+    else:
+        result = getattr(service, action)()
+    if action == 'status':
+        result['ready'] = bool(result['running'] and service.healthy())
+    print(json.dumps(result, sort_keys=True))

apsimo/sessions/__init__.py

@@ -0,0 +1,22 @@
+"""Session isolation — per-contact and per-colony isolated contexts."""
+
+from apsimo.sessions.isolated_session import (
+    IsolatedSession,
+    SessionState,
+    ConversationTurn,
+)
+from apsimo.sessions.store import IsolatedSessionStore, InMemorySessionStore
+from apsimo.sessions.context_loader import SessionContext, SessionContextLoader
+from apsimo.sessions.federation_session import FederationSession, FederationSessionState
+
+__all__ = [
+    "IsolatedSession",
+    "SessionState",
+    "ConversationTurn",
+    "IsolatedSessionStore",
+    "InMemorySessionStore",
+    "SessionContext",
+    "SessionContextLoader",
+    "FederationSession",
+    "FederationSessionState",
+]

apsimo/sessions/config.py

@@ -0,0 +1,13 @@
+"""Session TTL configuration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class SessionTTLConfig:
+    contact_session_ttl_hours: int = 24       # human-contact sessions
+    api_session_ttl_hours: int = 1            # machine/API sessions
+    websocket_idle_ttl_minutes: int = 30      # WebSocket idle timeout
+    cleanup_interval_minutes: int = 15        # background sweep frequency

apsimo/sessions/context_loader.py

@@ -0,0 +1,88 @@
+"""SessionContextLoader — loads all context for a session turn, respecting isolation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from apsimo.intelligence.relationships.trust_tiers import TrustTier
+from apsimo.sessions.isolated_session import IsolatedSession
+
+
+@dataclass
+class SessionContext:
+    """The complete context package loaded for a session turn.
+
+    This object has no method to access other sessions.
+    All fields are scoped to the single contact.
+    """
+    session: IsolatedSession
+    person_node: dict                    # Person node from Neo4j
+    accessible_memories: list           # memories tagged for this tier or lower
+    initiative_history: list            # last N outreach events with this contact
+    relationship_trend: Optional[list]  # 30-day score trend (SHOULD load)
+    anomaly_flags: list                 # current anomaly flags (SHOULD load)
+    style_model: Optional[dict]         # communication style model (SHOULD load)
+
+
+class SessionContextLoader:
+    """Loads all context for a session turn, respecting isolation boundaries."""
+
+    def __init__(
+        self,
+        session_store,
+        graph_client,
+        config,
+    ) -> None:
+        self._sessions = session_store
+        self._graph = graph_client
+        self._config = config
+
+    async def load(self, session_id: str) -> SessionContext:
+        """Load full context for a session. Raises if session not found."""
+        session = await self._sessions.get(session_id)
+        if session is None:
+            raise ValueError(f"Session {session_id!r} not found")
+
+        # MUST load
+        person_node = await self._graph.get_person_node(session.contact_id)
+        accessible_memories = await self._graph.get_memories_for_tier(
+            contact_id=session.contact_id,
+            tier=session.trust_tier,
+            exclude_visibility=["COLONY_ONLY"],  # NEVER load private memories
+        )
+        initiative_history = await self._graph.get_initiative_history(
+            contact_id=session.contact_id,
+            limit=10,
+        )
+
+        # SHOULD load (best-effort)
+        relationship_trend = None
+        anomaly_flags = []
+        style_model = None
+        remaining_tokens = (
+            self._config.context_token_limit - session.context_token_count
+        )
+        if remaining_tokens > 5_000:
+            try:
+                relationship_trend = await self._graph.get_score_trend(
+                    contact_id=session.contact_id, days=30
+                )
+                anomaly_flags = await self._graph.get_anomaly_flags(
+                    contact_id=session.contact_id
+                )
+                style_model = await self._graph.get_style_model(
+                    contact_id=session.contact_id
+                )
+            except Exception:
+                pass  # SHOULD load — failures are non-fatal
+
+        return SessionContext(
+            session=session,
+            person_node=person_node,
+            accessible_memories=accessible_memories,
+            initiative_history=initiative_history,
+            relationship_trend=relationship_trend,
+            anomaly_flags=anomaly_flags,
+            style_model=style_model,
+        )

apsimo/sessions/federation_session.py

@@ -0,0 +1,75 @@
+"""FederationSession — colony-to-colony isolated session."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Optional
+
+
+class FederationSessionState(str, Enum):
+    ACTIVE = "active"
+    IDLE = "idle"
+    ARCHIVED = "archived"
+    TRUST_SUSPENDED = "trust_suspended"
+
+
+@dataclass
+class FederationTurn:
+    turn_id: str
+    role: str               # "local" | "remote"
+    content: str
+    timestamp: datetime
+    gate_decision: Optional[str] = None
+
+
+@dataclass
+class FederationSession:
+    """Colony-to-colony session. Contains ONLY bilateral negotiation content.
+
+    MUST NOT contain:
+    - Content from contact sessions.
+    - Internal deliberation memories (COLONY_ONLY).
+    - Any information about local contacts.
+    """
+    session_id: str
+    local_colony_id: str
+    remote_colony_id: str
+    federated_trust_tier: str           # e.g. "trusted_colony" | "untrusted" | "newly_paired"
+    state: FederationSessionState = FederationSessionState.ACTIVE
+    history: list = field(default_factory=list)
+    mentioned_entities: set = field(default_factory=set)
+    shared_memory_ids: list = field(default_factory=list)  # explicitly consented objects
+    trust_attestations: list = field(default_factory=list)  # on-chain, read-only
+    last_active: datetime = field(default_factory=lambda: datetime.now(tz=timezone.utc))
+
+    @classmethod
+    def create(
+        cls,
+        local_colony_id: str,
+        remote_colony_id: str,
+        federated_trust_tier: str = "newly_paired",
+    ) -> "FederationSession":
+        return cls(
+            session_id=str(uuid.uuid4()),
+            local_colony_id=local_colony_id,
+            remote_colony_id=remote_colony_id,
+            federated_trust_tier=federated_trust_tier,
+        )
+
+    def add_turn(self, role: str, content: str, gate_decision: Optional[str] = None) -> FederationTurn:
+        turn = FederationTurn(
+            turn_id=str(uuid.uuid4()),
+            role=role,
+            content=content,
+            timestamp=datetime.now(tz=timezone.utc),
+            gate_decision=gate_decision,
+        )
+        self.history.append(turn)
+        self.last_active = turn.timestamp
+        return turn
+
+    def get_mentioned_entities_snapshot(self) -> frozenset:
+        return frozenset(self.mentioned_entities)

apsimo/sessions/isolated_session.py

@@ -0,0 +1,98 @@
+"""IsolatedSession — per-contact sealed context."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+from typing import Optional
+
+from apsimo.intelligence.relationships.trust_tiers import TrustTier
+
+
+class SessionState(str, Enum):
+    ACTIVE = "active"
+    IDLE = "idle"
+    ARCHIVED = "archived"
+    SILENCED = "silenced"
+    NEEDS_OWNER_REVIEW = "needs_owner_review"
+    ESCALATION_PENDING = "escalation_pending"
+
+
+@dataclass
+class ConversationTurn:
+    turn_id: str
+    role: str               # "contact" | "colony"
+    content: str
+    timestamp: datetime
+    gate_decision: Optional[str] = None   # result code if this was an outbound turn
+
+
+_DEFAULT_TTL_HOURS = 24
+
+
+@dataclass
+class IsolatedSession:
+    session_id: str
+    contact_id: str
+    gateway: str
+    trust_tier: TrustTier
+    state: SessionState = SessionState.ACTIVE
+    history: list = field(default_factory=list)
+    active_topics: set = field(default_factory=set)
+    mentioned_entities: set = field(default_factory=set)
+    context_start: datetime = field(default_factory=lambda: datetime.now(tz=timezone.utc))
+    context_token_count: int = 0
+    last_active: datetime = field(default_factory=lambda: datetime.now(tz=timezone.utc))
+    relationship_score: float = 0.0
+    owner_guidance: dict = field(default_factory=dict)
+    expires_at: datetime = field(
+        default_factory=lambda: datetime.now(tz=timezone.utc) + timedelta(hours=_DEFAULT_TTL_HOURS)
+    )
+    model_override: Optional[str] = None
+    model_provider_override: Optional[str] = None
+
+    @classmethod
+    def create(
+        cls,
+        contact_id: str,
+        gateway: str,
+        trust_tier: TrustTier,
+        ttl_hours: int = _DEFAULT_TTL_HOURS,
+    ) -> "IsolatedSession":
+        return cls(
+            session_id=str(uuid.uuid4()),
+            contact_id=contact_id,
+            gateway=gateway,
+            trust_tier=trust_tier,
+            expires_at=datetime.now(tz=timezone.utc) + timedelta(hours=ttl_hours),
+        )
+
+    def is_expired(self) -> bool:
+        return datetime.now(tz=timezone.utc) >= self.expires_at
+
+    def extend(self, ttl_hours: int = _DEFAULT_TTL_HOURS) -> None:
+        """Reset expiry on activity (token rotation equivalent for stateful sessions)."""
+        self.expires_at = datetime.now(tz=timezone.utc) + timedelta(hours=ttl_hours)
+        self.last_active = datetime.now(tz=timezone.utc)
+
+    def add_entity(self, entity: str) -> None:
+        """Add an entity to this session's mention set."""
+        self.mentioned_entities.add(entity.lower().strip())
+
+    def get_mentioned_entities_snapshot(self) -> frozenset:
+        """Return an immutable snapshot for gate cross-context checking."""
+        return frozenset(self.mentioned_entities)
+
+    def add_turn(self, role: str, content: str, gate_decision: Optional[str] = None) -> ConversationTurn:
+        turn = ConversationTurn(
+            turn_id=str(uuid.uuid4()),
+            role=role,
+            content=content,
+            timestamp=datetime.now(tz=timezone.utc),
+            gate_decision=gate_decision,
+        )
+        self.history.append(turn)
+        self.last_active = turn.timestamp
+        return turn

apsimo/sessions/reports.py

@@ -0,0 +1,84 @@
+"""Session report store — lightweight in-memory cross-session bridge.
+
+Keeps the last N session summaries per contact. Older reports are evicted.
+This is NOT long-term memory — for that, use the graph store.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, List
+
+
+@dataclass
+class SessionReport:
+    """A summary of a single agent session, written at session end."""
+
+    report_id: str
+    session_id: str
+    contact_id: str
+    started_at: datetime
+    ended_at: datetime | None
+    summary: str
+    topics: List[str]
+    resolutions: List[str]
+    pending: List[str]
+    notified_user: bool
+    metadata: Dict[str, Any]
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+class SessionReportStore:
+    """In-memory store for recent agent session summaries.
+
+    Keeps last *max_per_contact* reports per contact_id. Older reports
+    are evicted on FIFO basis.
+    """
+
+    def __init__(self, max_per_contact: int = 20) -> None:
+        self._reports: Dict[str, List[SessionReport]] = {}
+        self._max_per_contact = max_per_contact
+
+    async def add_report(self, report: SessionReport) -> str:
+        """Store a report. Returns the report_id."""
+        if report.contact_id not in self._reports:
+            self._reports[report.contact_id] = []
+        self._reports[report.contact_id].append(report)
+        # Evict oldest if over limit
+        if len(self._reports[report.contact_id]) > self._max_per_contact:
+            self._reports[report.contact_id] = self._reports[
+                report.contact_id
+            ][-self._max_per_contact :]
+        return report.report_id
+
+    async def get_recent(
+        self,
+        contact_id: str,
+        hours: int = 24,
+        limit: int = 10,
+    ) -> List[SessionReport]:
+        """Return recent reports for a contact, filtered by age and capped."""
+        cutoff = datetime.now(timezone.utc) - timedelta(hours=hours)
+        reports = self._reports.get(contact_id, [])
+        recent = []
+        for r in reports:
+            # Defensive: ensure timezone-aware comparison
+            ended = r.ended_at
+            started = r.started_at
+            if ended is not None and ended.tzinfo is None:
+                ended = ended.replace(tzinfo=timezone.utc)
+            if started.tzinfo is None:
+                started = started.replace(tzinfo=timezone.utc)
+            if (
+                (ended is not None and ended > cutoff)
+                or (ended is None and started > cutoff)
+            ):
+                recent.append(r)
+        return recent[-limit:]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "contacts": len(self._reports),
+            "total_reports": sum(len(v) for v in self._reports.values()),
+        }