ltcai 3.6.0 → 4.0.1

package/latticeai/core/model_compat.py

@@ -16,7 +16,7 @@ import logging
 import re
 import threading
 import time
-from dataclasses import dataclass, field, asdict
+from dataclasses import dataclass, asdict
 from typing import Any, Dict, List, Optional, Tuple
 
 logger = logging.getLogger(__name__)

package/latticeai/core/model_resolution.py

@@ -19,7 +19,6 @@
 from __future__ import annotations
 
 import logging
-import re
 from dataclasses import dataclass, field, asdict
 from enum import Enum
 from typing import Any, Dict, List, Optional

package/latticeai/core/multi_agent.py

@@ -14,7 +14,7 @@ from datetime import datetime
 from typing import Any, Callable, Dict, List, Optional
 
 
-MULTI_AGENT_VERSION = "3.6.0"
+MULTI_AGENT_VERSION = "4.0.1"
 
 AGENT_ROLES = ("researcher", "planner", "executor", "reviewer", "release")
 CORE_PIPELINE = ("planner", "executor", "reviewer")
@@ -279,10 +279,13 @@ class AgentRunResult:
     retry_history: List[Dict[str, Any]] = field(default_factory=list)
     plan_review: Dict[str, Any] = field(default_factory=dict)
     memory_snapshots: List[Dict[str, Any]] = field(default_factory=list)
+    # "simulation" = deterministic LLM-free runner; "llm" = model-driven (v4 runtime).
+    mode: str = "simulation"
 
     def as_dict(self) -> Dict[str, Any]:
         return {
             "agent_id": self.agent_id,
+            "mode": self.mode,
             "status": self.status,
             "output": self.output,
             "timeline": self.timeline,
@@ -403,7 +406,221 @@ def default_role_runner(
             ctx.output = ctx.output or f"Released outcome for: {ctx.goal}"
             return {"role": role, "released": True, "summary": ctx.output}
 
-        return {"role": role, "status": "noop"}
+        return {
+            "role": role,
+            "status": "skipped",
+            "reason": "this role has no deterministic behaviour (custom agents require a loaded model)",
+        }
+
+    return runner
+
+
+def _extract_json_object(raw: str) -> Dict[str, Any]:
+    """Parse one JSON object out of an LLM response (fences/prose tolerated)."""
+    import json as _json
+    import re as _re
+
+    text = str(raw or "").strip()
+    fenced = _re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, flags=_re.DOTALL)
+    if fenced:
+        text = fenced.group(1)
+    elif not text.startswith("{"):
+        start, end = text.find("{"), text.rfind("}")
+        if start >= 0 and end > start:
+            text = text[start : end + 1]
+    parsed = _json.loads(text)
+    if not isinstance(parsed, dict):
+        raise ValueError("model returned JSON that is not an object")
+    return parsed
+
+
+def llm_role_runner(
+    *,
+    generate: Callable[..., str],
+    planner_prompt: str,
+    critic_prompt: str,
+    context_provider: Optional[Callable[[str], List[str]]] = None,
+    workflow_runner: Optional[Callable[..., Any]] = None,
+    plugin_runner: Optional[Callable[..., Any]] = None,
+    custom_agents: Optional[Dict[str, Dict[str, Any]]] = None,
+) -> Callable[[str, OrchestrationContext], Dict[str, Any]]:
+    """Model-driven role runner — the real Multi-Agent Runtime (T7b).
+
+    ``generate(message, context, max_tokens, temperature) -> str`` is a
+    synchronous bridge to the loaded model. Honesty contract (design-review
+    amendment): when the model responds but its plan/critique cannot be
+    parsed, the RUN FAILS with the raw output preserved in the records —
+    it never silently falls back to fabricated deterministic artifacts.
+    """
+    base = default_role_runner(
+        workflow_runner=workflow_runner,
+        plugin_runner=plugin_runner,
+        context_provider=context_provider,
+    )
+
+    def _fail(ctx: OrchestrationContext, role: str, reason: str, raw: str) -> Dict[str, Any]:
+        ctx.inputs["__llm_failure__"] = {"role": role, "reason": reason, "raw": raw[:2000]}
+        ctx.review = {
+            "outcome": "reject",
+            "verdict": "fail",
+            "reason": f"{role}: {reason}",
+            "raw_output": raw[:2000],
+            "reviewed_at": _now(),
+        }
+        return {"role": role, "status": "error", "reason": reason, "raw": raw[:2000]}
+
+    def runner(role: str, ctx: OrchestrationContext) -> Dict[str, Any]:
+        failure = ctx.inputs.get("__llm_failure__")
+
+        custom = (custom_agents or {}).get(role)
+        if custom is not None:
+            # Executable registry entry (T7e): the agent's persisted config
+            # (system_prompt, max_tokens, temperature) is actually loaded.
+            cfg = custom.get("config") or {}
+            system = str(
+                cfg.get("system_prompt")
+                or custom.get("description")
+                or f"You are {custom.get('name') or role}."
+            )
+            try:
+                out = str(generate(
+                    ctx.output or ctx.goal,
+                    context=system,
+                    max_tokens=int(cfg.get("max_tokens") or 1024),
+                    temperature=float(cfg.get("temperature") or 0.2),
+                ))
+            except Exception as exc:
+                return _fail(ctx, role, f"custom agent generation failed ({exc})", "")
+            ctx.output = out
+            return {"role": role, "agent": custom.get("name"), "status": "ok",
+                    "output": out[:2000]}
+
+        if role == "planner":
+            research = "\n".join(f"- {item}" for item in (ctx.research or [])[:8])
+            raw = generate(
+                "Produce a JSON execution plan for this goal. Respond with one JSON "
+                'object: {"goal": str, "steps": [{"description": str}, ...]} and nothing else.',
+                context=f"{planner_prompt}\n\nGoal: {ctx.goal}\n\nKnown context:\n{research}",
+                max_tokens=1024,
+                temperature=0.1,
+            )
+            try:
+                parsed = _extract_json_object(str(raw))
+            except Exception as exc:
+                return _fail(ctx, role, f"plan output unparseable ({exc})", str(raw))
+            steps = []
+            for i, step in enumerate(parsed.get("steps") or []):
+                description = step.get("description") if isinstance(step, dict) else str(step)
+                steps.append({"index": i, "description": str(description or f"Step {i + 1}"), "status": "planned"})
+            if not steps:
+                return _fail(ctx, role, "model returned a plan with no steps", str(raw))
+            if ctx.inputs.get("workflow"):
+                steps[0]["workflow"] = ctx.inputs.get("workflow")
+            if ctx.inputs.get("plugin"):
+                steps[0]["plugin"] = ctx.inputs.get("plugin")
+            ctx.plan = steps
+            ctx.plan_id = f"plan-{abs(hash((ctx.goal, len(steps)))) % 10_000_000}"
+            ctx.plan_review = {
+                "plan_id": ctx.plan_id,
+                "outcome": "approve",
+                "reason": "model-generated plan parsed and bounded",
+                "reviewed_at": _now(),
+            }
+            return {"role": role, "plan_id": ctx.plan_id, "steps": len(steps), "plan": steps, "plan_review": ctx.plan_review}
+
+        if role == "executor":
+            if failure:
+                return {"role": role, "status": "error", "reason": f"skipped — {failure['role']} failed"}
+            results = []
+            for step in ctx.plan:
+                outcome: Dict[str, Any] = {"index": step["index"], "description": step["description"]}
+                wf = step.get("workflow")
+                pl = step.get("plugin")
+                if wf and workflow_runner is not None:
+                    try:
+                        outcome["workflow_result"] = workflow_runner(wf, ctx)
+                        ctx.workflow_outputs.append(outcome["workflow_result"])
+                    except Exception as exc:
+                        outcome["workflow_error"] = str(exc)
+                if pl and plugin_runner is not None:
+                    try:
+                        outcome["plugin_result"] = plugin_runner(pl, ctx)
+                        ctx.plugin_outputs.append(outcome["plugin_result"])
+                    except Exception as exc:
+                        outcome["plugin_error"] = str(exc)
+                try:
+                    outcome["result"] = str(generate(
+                        f"Execute this step and return the concrete result only.\n"
+                        f"Goal: {ctx.goal}\nStep: {step['description']}",
+                        context="",
+                        max_tokens=1024,
+                        temperature=0.2,
+                    ))[:4000]
+                except Exception as exc:
+                    outcome["error"] = str(exc)
+                if outcome.get("workflow_error") or outcome.get("plugin_error") or outcome.get("error"):
+                    step["status"] = "failed"
+                    outcome["status"] = "error"
+                else:
+                    step["status"] = "done"
+                    outcome["status"] = "done"
+                results.append(outcome)
+            ctx.executed = results
+            done = [r for r in results if r.get("status") == "done"]
+            ctx.output = "\n\n".join(str(r.get("result") or "") for r in done).strip() or (
+                f"Completed {len(done)}/{len(results)} step(s) for: {ctx.goal}"
+            )
+            return {"role": role, "executed": len(results), "results": results}
+
+        if role == "reviewer":
+            if failure:
+                # Fail-closed: an upstream unparseable model output means this
+                # run is failed, with the raw output preserved — never rescued
+                # by a rubber-stamp review.
+                ctx.review = {
+                    "outcome": "reject",
+                    "verdict": "fail",
+                    "reason": f"{failure['role']} output unparseable",
+                    "raw_output": failure.get("raw"),
+                    "reviewed_at": _now(),
+                }
+                return {"role": role, **ctx.review}
+            raw = generate(
+                "Review this execution. Respond with one JSON object: "
+                '{"approve": bool, "reason": str} and nothing else.',
+                context=(
+                    f"{critic_prompt}\n\nGoal: {ctx.goal}\n\n"
+                    f"Steps: {[s.get('status') for s in ctx.plan]}\n\nOutput:\n{(ctx.output or '')[:3000]}"
+                ),
+                max_tokens=512,
+                temperature=0.1,
+            )
+            try:
+                parsed = _extract_json_object(str(raw))
+                approve = bool(parsed.get("approve"))
+                reason = str(parsed.get("reason") or "")
+            except Exception as exc:
+                ctx.review = {
+                    "outcome": "reject",
+                    "verdict": "fail",
+                    "reason": f"critic output unparseable ({exc})",
+                    "raw_output": str(raw)[:2000],
+                    "reviewed_at": _now(),
+                }
+                return {"role": role, **ctx.review}
+            ctx.review = {
+                "outcome": "approve" if approve else "retry",
+                "verdict": "pass" if approve else "retry",
+                "reason": reason or ("model approved the result" if approve else "model requested a retry"),
+                "confidence": 0.9 if approve else 0.4,
+                "notes": [],
+                "reviewed_at": _now(),
+            }
+            return {"role": role, **ctx.review}
+
+        # researcher / release / anything else: the deterministic behaviour is
+        # real work (memory recall, bookkeeping) — reuse it.
+        return base(role, ctx)
 
     return runner
 
@@ -411,8 +628,21 @@ def default_role_runner(
 class MultiAgentOrchestrator:
     """Drives a role pipeline with handoff, planning, review, and retry."""
 
-    def __init__(self, role_runner: Optional[Callable[[str, OrchestrationContext], Dict[str, Any]]] = None):
+    def __init__(
+        self,
+        role_runner: Optional[Callable[[str, OrchestrationContext], Dict[str, Any]]] = None,
+        mode: str = "simulation",
+        custom_agents: Optional[Dict[str, Dict[str, Any]]] = None,
+    ):
         self.role_runner = role_runner or default_role_runner()
+        # Executable registry entries (T7e): a requested role may be a
+        # registered custom agent id; its config (system_prompt, …) is
+        # actually loaded at run time — registration is no longer a UI illusion.
+        self.custom_agents = dict(custom_agents or {})
+        # Honest execution-mode label persisted on every run record. The
+        # built-in runner never calls a model, so the default is "simulation";
+        # an LLM-backed runner must declare mode="llm" explicitly.
+        self.mode = mode
 
     def _run_role(self, role: str, ctx: OrchestrationContext) -> Dict[str, Any]:
         started = _now()
@@ -473,7 +703,10 @@ class MultiAgentOrchestrator:
             workspace_id=workspace_id,
             inputs=inputs or {},
         )
-        pipeline = [r for r in (roles or list(CORE_PIPELINE)) if r in AGENT_ROLES]
+        pipeline = [
+            r for r in (roles or list(CORE_PIPELINE))
+            if r in AGENT_ROLES or r in self.custom_agents
+        ]
         if not pipeline:
             pipeline = list(CORE_PIPELINE)
         max_retries = max(0, int(max_retries or 0))
@@ -558,4 +791,5 @@ class MultiAgentOrchestrator:
             retry_history=ctx.retry_history,
             plan_review=ctx.plan_review,
             memory_snapshots=ctx.memory_snapshots,
+            mode=self.mode,
         )

package/latticeai/core/policy.py

@@ -0,0 +1,54 @@
+"""Enforced community RBAC policy for Lattice AI."""
+
+from __future__ import annotations
+
+from typing import Dict, Iterable, List, Set
+
+
+ROLE_CAPABILITIES: Dict[str, Set[str]] = {
+    "owner": {"all"},
+    "admin": {
+        "admin:users",
+        "admin:roles",
+        "admin:policies",
+        "admin:audit",
+        "admin:security",
+        "workspace:read",
+        "workspace:write",
+        "workspace:manage",
+        "workspace:members",
+        "chat",
+        "search",
+        "files",
+        "pipeline",
+    },
+    "member": {"workspace:read", "workspace:write", "chat", "search", "files", "pipeline"},
+    "user": {"workspace:read", "workspace:write", "chat", "search", "files", "pipeline"},
+    "viewer": {"workspace:read", "chat", "search"},
+}
+
+
+def normalize_role(role: str) -> str:
+    role = str(role or "user").lower()
+    return role if role in ROLE_CAPABILITIES else "user"
+
+
+def capabilities_for_role(role: str) -> List[str]:
+    caps = ROLE_CAPABILITIES.get(normalize_role(role), ROLE_CAPABILITIES["user"])
+    return sorted(caps)
+
+
+def role_has_capability(role: str, capability: str) -> bool:
+    caps = ROLE_CAPABILITIES.get(normalize_role(role), ROLE_CAPABILITIES["user"])
+    return "all" in caps or capability in caps
+
+
+def require_capability(role: str, capability: str) -> None:
+    if not role_has_capability(role, capability):
+        raise PermissionError(f"role '{normalize_role(role)}' lacks capability '{capability}'")
+
+
+def policy_matrix(roles: Iterable[str] | None = None) -> List[Dict[str, object]]:
+    selected = list(roles or ROLE_CAPABILITIES.keys())
+    return [{"role": normalize_role(role), "caps": capabilities_for_role(role)} for role in selected]
+

package/latticeai/core/realtime.py

@@ -28,6 +28,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import threading
 from datetime import datetime
 from typing import Any, AsyncIterator, Dict, List, Optional, Set
 
@@ -47,7 +48,7 @@ def sse_format(event: Dict[str, Any]) -> str:
 
 
 class _Subscriber:
-    __slots__ = ("id", "queue", "workspace_scope", "user", "joined_at")
+    __slots__ = ("id", "queue", "workspace_scope", "user", "joined_at", "loop")
 
     def __init__(self, sub_id: str, workspace_scope: Optional[Set[str]], user: Optional[str]):
         self.id = sub_id
@@ -55,6 +56,10 @@ class _Subscriber:
         self.workspace_scope = workspace_scope
         self.user = user
         self.joined_at = _now()
+        try:
+            self.loop: Optional[asyncio.AbstractEventLoop] = asyncio.get_running_loop()
+        except RuntimeError:
+            self.loop = None
 
     def accepts(self, workspace_id: Optional[str]) -> bool:
         # ``None`` scope = see everything the local user can (personal/unscoped).
@@ -73,6 +78,7 @@ class RealtimeBus:
         self._feed: List[Dict[str, Any]] = []
         self._presence: Dict[str, Dict[str, Any]] = {}
         self._seq = 0
+        self._lock = threading.RLock()
 
     # ── publishing ────────────────────────────────────────────────────────
 
@@ -82,34 +88,41 @@ class RealtimeBus:
         Safe to call from sync code (e.g. the store's timeline hook). Never
         raises and never blocks the caller.
         """
-        self._seq += 1
-        enriched = {
-            "seq": self._seq,
-            "received_at": _now(),
-            "area": event.get("area", "workspace"),
-            "event_type": event.get("event_type", "event"),
-            "workspace_id": event.get("workspace_id"),
-            "payload": event.get("payload", {}),
-            **{k: v for k, v in event.items() if k not in {"area", "event_type", "workspace_id", "payload"}},
-        }
-        self._feed.append(enriched)
-        if len(self._feed) > _FEED_LIMIT:
-            self._feed = self._feed[-_FEED_LIMIT:]
-
-        workspace_id = enriched.get("workspace_id")
-        for sub in list(self._subscribers.values()):
-            if not sub.accepts(workspace_id):
-                continue
-            try:
-                sub.queue.put_nowait(enriched)
-            except asyncio.QueueFull:
-                try:
-                    sub.queue.get_nowait()  # drop oldest
-                    sub.queue.put_nowait(enriched)
-                except Exception:
-                    pass
+        with self._lock:
+            self._seq += 1
+            enriched = {
+                "seq": self._seq,
+                "received_at": _now(),
+                "area": event.get("area", "workspace"),
+                "event_type": event.get("event_type", "event"),
+                "workspace_id": event.get("workspace_id"),
+                "payload": event.get("payload", {}),
+                **{k: v for k, v in event.items() if k not in {"area", "event_type", "workspace_id", "payload"}},
+            }
+            self._feed.append(enriched)
+            if len(self._feed) > _FEED_LIMIT:
+                self._feed = self._feed[-_FEED_LIMIT:]
+
+            workspace_id = enriched.get("workspace_id")
+            subscribers = [sub for sub in self._subscribers.values() if sub.accepts(workspace_id)]
+        for sub in subscribers:
+            if sub.loop is not None and sub.loop.is_running():
+                sub.loop.call_soon_threadsafe(self._enqueue, sub, enriched)
+            else:
+                self._enqueue(sub, enriched)
         return enriched
 
+    @staticmethod
+    def _enqueue(sub: _Subscriber, event: Dict[str, Any]) -> None:
+        try:
+            sub.queue.put_nowait(event)
+        except asyncio.QueueFull:
+            try:
+                sub.queue.get_nowait()  # drop oldest
+                sub.queue.put_nowait(event)
+            except Exception:
+                pass
+
     # The store calls ``event_sink(event)`` positionally; expose a stable alias.
     def __call__(self, event: Dict[str, Any]) -> Dict[str, Any]:
         return self.publish(event)
@@ -118,11 +131,13 @@ class RealtimeBus:
 
     def add_subscriber(self, sub_id: str, *, workspace_scope: Optional[Set[str]] = None, user: Optional[str] = None) -> _Subscriber:
         sub = _Subscriber(sub_id, workspace_scope, user)
-        self._subscribers[sub_id] = sub
+        with self._lock:
+            self._subscribers[sub_id] = sub
         return sub
 
     def remove_subscriber(self, sub_id: str) -> None:
-        self._subscribers.pop(sub_id, None)
+        with self._lock:
+            self._subscribers.pop(sub_id, None)
 
     async def stream(self, sub: _Subscriber, *, heartbeat: float = 15.0) -> AsyncIterator[str]:
         """Yield SSE frames for a subscriber until the client disconnects.
@@ -146,7 +161,8 @@ class RealtimeBus:
     # ── feed + presence ─────────────────────────────────────────────────────
 
     def recent(self, *, limit: int = 50, workspace_scope: Optional[Set[str]] = None) -> List[Dict[str, Any]]:
-        events = self._feed
+        with self._lock:
+            events = list(self._feed)
         if workspace_scope is not None:
             events = [e for e in events if e.get("workspace_id") is None or e.get("workspace_id") in workspace_scope]
         return list(reversed(events[-max(1, min(limit, _FEED_LIMIT)):]))
@@ -159,32 +175,37 @@ class RealtimeBus:
             "joined_at": _now(),
             "last_seen": _now(),
         }
-        self._presence[client_id] = record
+        with self._lock:
+            self._presence[client_id] = record
         self.publish({"area": "presence", "event_type": "join", "workspace_id": workspace_id, "payload": {"user": user, "client_id": client_id}})
         return record
 
     def heartbeat(self, client_id: str) -> Optional[Dict[str, Any]]:
-        record = self._presence.get(client_id)
-        if record:
-            record["last_seen"] = _now()
-        return record
+        with self._lock:
+            record = self._presence.get(client_id)
+            if record:
+                record["last_seen"] = _now()
+            return record
 
     def leave(self, client_id: str) -> None:
-        record = self._presence.pop(client_id, None)
+        with self._lock:
+            record = self._presence.pop(client_id, None)
         if record:
             self.publish({"area": "presence", "event_type": "leave", "workspace_id": record.get("workspace_id"), "payload": {"client_id": client_id}})
 
     def presence(self, *, workspace_scope: Optional[Set[str]] = None) -> List[Dict[str, Any]]:
-        records = list(self._presence.values())
+        with self._lock:
+            records = list(self._presence.values())
         if workspace_scope is not None:
             records = [r for r in records if r.get("workspace_id") is None or r.get("workspace_id") in workspace_scope]
         return records
 
     def stats(self) -> Dict[str, Any]:
-        return {
-            "version": REALTIME_VERSION,
-            "subscribers": len(self._subscribers),
-            "presence": len(self._presence),
-            "feed_size": len(self._feed),
-            "transport": "sse",
-        }
+        with self._lock:
+            return {
+                "version": REALTIME_VERSION,
+                "subscribers": len(self._subscribers),
+                "presence": len(self._presence),
+                "feed_size": len(self._feed),
+                "transport": "sse",
+            }

package/latticeai/core/security.py

@@ -6,7 +6,7 @@ import re
 import secrets
 import threading
 import time
-from typing import Dict, List, Optional
+from typing import Dict, List
 
 from fastapi import HTTPException
 

package/latticeai/core/sessions.py

@@ -1,5 +1,12 @@
-"""File-backed session store with sliding-window TTL."""
+"""File-backed session store with sliding-window TTL.
 
+v4: bearer tokens are stored **hashed** (sha256) at rest — a process that can
+read ``sessions.json`` must not be able to hijack every session. Pre-v4 files
+holding raw tokens are migrated transparently on load (sessions survive the
+upgrade; the raw token never touches disk again).
+"""
+
+import hashlib
 import json
 import logging
 import os
@@ -13,6 +20,16 @@ SESSION_TTL = 60 * 60 * 24  # 24 hours
 SESSION_REFRESH_THRESHOLD = 60 * 15  # only persist if >15 min since last bump
 _lock = threading.Lock()
 
+_HEX64 = frozenset("0123456789abcdef")
+
+
+def _hash_token(token: str) -> str:
+    return hashlib.sha256((token or "").encode("utf-8")).hexdigest()
+
+
+def _looks_hashed(key: str) -> bool:
+    return len(key) == 64 and set(key) <= _HEX64
+
 
 def _sessions_file(data_dir: Optional[Path] = None) -> Path:
     d = data_dir or Path(os.getenv("LATTICEAI_DATA_DIR") or (Path.home() / ".ltcai"))
@@ -25,7 +42,19 @@ def load_sessions(data_dir: Optional[Path] = None) -> Dict[str, tuple]:
         f = _sessions_file(data_dir)
         if f.exists():
             raw = json.loads(f.read_text())
-            return {k: tuple(v) for k, v in raw.items()}
+            sessions: Dict[str, tuple] = {}
+            migrated = False
+            for key, value in raw.items():
+                if _looks_hashed(key):
+                    sessions[key] = tuple(value)
+                else:
+                    # Pre-v4 entry: the key IS the raw bearer token. Re-key it
+                    # under its hash so the plaintext stops living on disk.
+                    sessions[_hash_token(key)] = tuple(value)
+                    migrated = True
+            if migrated:
+                persist_sessions(sessions, data_dir)
+            return sessions
     except Exception as e:
         logging.warning("load_sessions failed (starting empty): %s", e)
     return {}
@@ -38,35 +67,62 @@ def persist_sessions(sessions: Dict[str, tuple], data_dir: Optional[Path] = None
         logging.warning("persist_sessions failed: %s", e)
 
 
+def _entry_subject(entry: tuple) -> Optional[str]:
+    return entry[0] if entry else None
+
+
+def _entry_email(entry: tuple) -> Optional[str]:
+    if len(entry) >= 3 and entry[2]:
+        return entry[2]
+    return entry[0] if entry else None
+
+
+def _entry_created_at(entry: tuple) -> float:
+    if len(entry) >= 2:
+        return float(entry[1])
+    return 0.0
+
+
 class SessionStore:
     def __init__(self, data_dir: Optional[Path] = None):
         self._data_dir = data_dir
         self._sessions: Dict[str, tuple] = load_sessions(data_dir)
 
-    def create(self, email: str) -> str:
+    def create(self, subject: str, *, email: Optional[str] = None) -> str:
         token = secrets.token_urlsafe(32)
         with _lock:
-            self._sessions[token] = (email, time.time())
+            self._sessions[_hash_token(token)] = (subject, time.time(), email or subject)
             persist_sessions(self._sessions, self._data_dir)
         return token
 
     def get_email(self, token: str) -> Optional[str]:
+        entry = self._get_entry(token)
+        return _entry_email(entry) if entry else None
+
+    def get_subject(self, token: str) -> Optional[str]:
+        entry = self._get_entry(token)
+        return _entry_subject(entry) if entry else None
+
+    def _get_entry(self, token: str) -> Optional[tuple]:
         now = time.time()
+        key = _hash_token(token)
         with _lock:
-            entry = self._sessions.get(token)
+            entry = self._sessions.get(key)
             if entry is None:
                 return None
-            email, created_at = entry
+            created_at = _entry_created_at(entry)
             if now - created_at > SESSION_TTL:
-                self._sessions.pop(token, None)
+                self._sessions.pop(key, None)
                 persist_sessions(self._sessions, self._data_dir)
                 return None
             if now - created_at > SESSION_REFRESH_THRESHOLD:
-                self._sessions[token] = (email, now)
+                refreshed = (_entry_subject(entry), now, _entry_email(entry))
+                self._sessions[key] = refreshed
                 persist_sessions(self._sessions, self._data_dir)
-            return email
+                return refreshed
+            return entry
 
     def invalidate(self, token: str) -> None:
         with _lock:
-            self._sessions.pop(token, None)
+            self._sessions.pop(_hash_token(token), None)
             persist_sessions(self._sessions, self._data_dir)