class Agent:
    """Unified entity model. Data in Redis Hash, behavior in Python class."""
 
    def __init__(self, agent_id: str):
        self.agent_id = agent_id
        self._data = None
 
    @property
    def data(self) -> dict:
        """Lazy load from Redis with local cache."""
        if self._data is None:
            self._data = redis.hgetall(f"hermes:agent:{self.agent_id}")
        return self._data
 
    def save(self):
        redis.hmset(f"hermes:agent:{self.agent_id}", self._data)
 
    # Lazy-init handlers (pay only for what you use)
    @lazy_property
    def capabilities(self) -> CapabilityHandler: ...
 
    @lazy_property
    def locks(self) -> LockHandler: ...
 
    @lazy_property
    def channels(self) -> ChannelSubscriptionHandler: ...
 
    # Message delivery (environment-dependent)
    def deliver(self, message: "Message"):
        """
        Receive a message. Behavior depends on runtime context:
        - CLI environment: print to terminal
        - Worker environment: enqueue as ARQ task for the agent's worker
        """
        ...
 
    # Lifecycle hooks (override in subclasses)
    def at_creation(self): ...
    def at_activate(self): ...
    def at_pause(self): ...
    def at_resume(self): ...
    def at_stop(self): ...

class AgentRegistry:
    """In-process cache: {agent_id: Agent}. Auto-populated on first access."""
    _cache: dict[str, Agent] = {}
 
    @classmethod
    def get(cls, agent_id: str) -> Agent:
        if agent_id not in cls._cache:
            cls._cache[agent_id] = Agent(agent_id)
        return cls._cache[agent_id]
 
    @classmethod
    def find(cls, name_or_id: str) -> Agent | None:
        """Find by agent_id, name prefix, or alias. Returns None if not found."""
        ...
 
class ChannelRegistry:
    """Channel lookup by name. Channels are loaded from Redis on first access."""
    _cache: dict[str, Channel] = {}
 
    @classmethod
    def get(cls, name: str) -> Channel:
        if name not in cls._cache:
            cls._cache[name] = Channel(name)
        return cls._cache[name]

class Capability:
    """Single capability item."""
    name: str               # "code", "deploy", "review", "debug"
    metadata: dict           # optional: {"timeout": 300, "max_tokens": 8000}
 
    def match(self, input_str: str) -> bool:
        """Prefix matching (supports abbreviations)."""
        return self.name.startswith(input_str) or input_str.startswith(self.name[:len(input_str)])
 
 
class CapabilitySet:
    """Capability collection supporting four merge operations."""
 
    priority: int           # higher = higher priority
    mergetype: str          # "union" | "intersect" | "replace" | "remove"
    source: str             # origin: "role", "task", "channel", "override", "template"
 
    _caps: dict[str, Capability]
 
    def __add__(self, other: "CapabilitySet") -> "CapabilitySet":
        """Merge two CapabilitySets. Higher priority's mergetype wins."""
        ...

class CapabilityHandler:
    """
    Per-agent handler managing multi-source CapabilitySet merging.
 
    Redis storage:
      Capability sources: SortedSet hermes:agent:{id}:cap_sources (score=priority)
      Per-source caps:    Hash        hermes:agent:{id}:caps:{source}
      Merged cache:       Hash        hermes:agent:{id}:caps_merged (TTL 60s)
    """
 
    def get_merged(self) -> CapabilitySet:
        """Merge all sources from low to high priority."""
        sources = redis.zrange(f"hermes:agent:{self.agent.agent_id}:cap_sources", 0, -1)
        result = CapabilitySet()
        for source_name in sources:
            capset = self._load_source(source_name)
            result = result + capset
        return result
 
    def grant(self, cap_name: str, source: str = "override", **metadata):
        """Dynamically grant capability."""
        ...
 
    def revoke(self, cap_name: str, source: str = "override"):
        """Revoke capability from a source."""
        ...
 
    def grant_source(self, source: str, cap_names: list[str]):
        """Replace entire source (used by template loading)."""
        ...
 
    def check(self, cap_name: str) -> bool:
        """Check if merged set contains capability."""
        merged = self.get_merged()
        return any(c.match(cap_name) for c in merged._caps.values())

# Existing lib/dispatcher.py routing enhanced with capability check
def dispatch_task(task, target_agent):
    if not target_agent.capabilities.check(task.required_cap):
        raise CapabilityDenied(f"Agent lacks: {task.required_cap}")
    await arq_pool.enqueue(task.queue, task.payload)

class LockHandler:
    """
    Per-agent access control.
 
    Redis storage:
      Key: hermes:agent:{id}:locks
      Type: Hash
      Field: access_type -> lock_string
    """
 
    _locks: dict[str, ParsedLock]
 
    def check(self, access_type: str, caller: "Agent", default: bool = False) -> bool:
        """
        Check if caller has access_type permission.
        Fail-closed: unknown access types return default (False).
        """
        if caller.data.get("is_superuser"):
            return True
        parsed = self._locks.get(access_type)
        if parsed is None:
            return default
        results = tuple(func(caller, self.agent, *args, **kwargs)
                        for func, args, kwargs in parsed.func_calls)
        return eval(parsed.eval_template % results)
 
    def set_locks(self, lockstring: str):
        """Parse and store lock string."""
        self._locks = parse_lockstring(lockstring)
        # Persist to Redis
        redis.hmset(f"hermes:agent:{self.agent.agent_id}:locks",
                     {k: v.raw for k, v in self._locks.items()})

class ParsedLock:
    """Pre-compiled lock string."""
    eval_template: str    # "%s and not %s"
    func_calls: list      # [(callable, args, kwargs), ...]
    raw: str              # original string for storage
 
def parse_lockstring(lockstring: str) -> dict[str, ParsedLock]:
    """
    Parse lock string into {access_type: ParsedLock}.
 
    Safety: eval_template only allows and/or/not, pre-validated with
    empty-namespace eval. Only boolean results are ever interpolated.
    """
    ...

class Channel:
    """
    Channel entity.
 
    Redis storage:
      Metadata:    Hash    hermes:channel:{name}
      Subscribers: Set     hermes:channel:{name}:subscribers
      Ban list:    Set     hermes:channel:{name}:banlist
      Mute list:   Set     hermes:channel:{name}:mutelist
      History:     Stream  hermes:channel:{name}:stream  (maxlen=1000)
    """
    name: str
    locks: LockHandler
    send_to_active_only: bool = True
 
    # Hook chain (override in subclasses)
    def at_pre_msg(self, message: "Message") -> "Message | None":
        """Pre-broadcast. Return None to cancel."""
        return message
 
    def at_post_msg(self, message: "Message"):
        """Post-broadcast (default: write to Redis Stream)."""
        ...
 
 
class Message:
    sender_id: str          # agent_id or "user:{user_id}"
    channel: str            # channel name (empty = direct message)
    content: str
    msg_type: str           # "say" | "tell" | "emote" | "system" | "task"
    timestamp: float
    metadata: dict

class ChannelSubscriptionHandler:
    """Per-agent handler managing channel subscriptions."""
 
    def join(self, channel_name: str):
        channel = ChannelRegistry.get(channel_name)
        channel.subscribe(self.agent.agent_id)
 
    def leave(self, channel_name: str):
        channel = ChannelRegistry.get(channel_name)
        channel.unsubscribe(self.agent.agent_id)
 
    def tell(self, target_id: str, content: str):
        """Direct message."""
        target = AgentRegistry.get(target_id)
        if not target.locks.check("message", self.agent):
            raise AccessDenied(f"Cannot message {target_id}")
        target.deliver(Message(sender_id=self.agent.agent_id,
                                content=content, msg_type="tell"))
 
    def get_history(self, channel_name: str, count: int = 20) -> list[Message]:
        """Read channel history from Redis Stream."""
        entries = redis.xrevrange(f"hermes:channel:{channel_name}:stream", count=count)
        return [Message.from_stream(e) for e in entries]

class AgentLifecycle:
    """Per-agent lifecycle manager. State stored in Redis Hash `status` field."""
 
    TRANSITIONS = {
        "created":  {"active"},
        "active":   {"paused", "stopped"},
        "paused":   {"active", "stopped"},
        "stopped":  {"active", "gone"},
    }
 
    def transition(self, target_status: str, **kwargs):
        current = self.agent.data.get("status", "created")
        if target_status not in self.TRANSITIONS.get(current, set()):
            raise InvalidTransition(f"{current} -> {target_status}")
        # Pre-hook
        getattr(self.agent, f"at_{target_status}")(current_status=current, **kwargs)
        # Update Redis
        self.agent.data["status"] = target_status
        self.agent.data["last_active"] = str(time.time())
        self.agent.save()
        # Publish event
        redis.publish(f"hermes:lifecycle:{self.agent.agent_id}",
                      json.dumps({"event": target_status, "ts": time.time()}))

def get_agent_state(agent: Agent) -> dict:
    """Zero-timer state computation from elapsed time."""
    elapsed = time.time() - float(agent.data.get("last_active", 0))
    stages = [
        (0,   "active"),
        (300, "idle"),
        (600, "idle_warning"),
        (900, "auto_pause"),
    ]
    stage = "active"
    for threshold, name in stages:
        if elapsed >= threshold:
            stage = name
    return {"stage": stage, "elapsed": elapsed}

templates:
  base_agent:
    capabilities: [status, message]
    locks: "execute:true(); message:true()"
    max_concurrent_tasks: 1
    timeout: 300
 
  coder:
    inherits: [base_agent]
    capabilities: [code, read, search, test]
    locks: "execute:role(junior); deploy:role(senior); control:owner()"
    max_concurrent_tasks: 2
    timeout: 600
    queue: engineering
 
  senior_coder:
    inherits: [coder]
    capabilities: [deploy, review, mentor]    # appended
    max_concurrent_tasks: 4
    max_tokens: 16000
 
  rate_limited_coder:
    inherits: [rate_limited, senior_coder]    # senior_coder wins on conflict
    timeout: 120
 
  rate_limited:
    rate_limit: "100/60s"
    rate_limit_strategy: sliding_window
 
  dynamic_worker:
    inherits: [base_agent]
    timeout: "callable:hermes.templates.dynamic_timeout()"
    capabilities: "callable:hermes.templates.resolve_caps(${task_type})"

class TemplateEngine:
    """
    Parse templates, resolve inheritance, evaluate callables.
    Cached in Redis Hash hermes:template:{name}.
    """
 
    def resolve(self, template_name: str) -> dict:
        """Resolve template with inheritance into flat config dict."""
        ...
 
    def _resolve_inheritance(self, template: dict) -> dict:
        """
        Multiple inheritance, right-to-left precedence.
        Capabilities lists: deduplication merge (not replace).
        Scalar values: child overrides parent.
        """
        ...
 
    def evaluate_callables(self, template: dict, context: dict = None) -> dict:
        """
        Evaluate callable fields at spawn time.
        "callable:module.func()" -> call function, return value.
        "${var}" -> substitute from context dict.
        """
        ...

def diff_template(old_config, new_config) -> dict:
    """Generate incremental operations: capabilities add/remove, locks changed, etc."""
    ...
 
async def update_agents_from_template(template_name: str):
    """Apply diff to all agents spawned from this template."""
    ...

# Mode 1: Single command (enhanced existing)
hermes spawn coder
hermes tell coder-3 status?
hermes status
 
# Mode 2: REPL (MUD-style continuous session)
$ hermes repl
[hermes] > spawn coder
[hermes] > look
[hermes] > say hello everyone
[hermes] > quit

class Command:
    name: str
    aliases: list[str]
    help_text: str
    lock: str               # e.g. "use:role(admin)"
 
    def at_pre_cmd(self, ctx) -> bool: ...   # True = skip
    def parse(self, ctx): ...
    def func(self, ctx): ...                  # main logic
    def at_post_cmd(self, ctx): ...
 
    def match(self, input_str: str) -> bool:
        """Prefix matching, longest alias first."""
        ...