← Files ClaraARCHIVED FILE

vendor/modules/courseware/chat.py

8.9 KB · Nov 21, 2026 · 00:11 UTC

↓ Download file

"""Revision-bound native course chat handoffs; course state stays authoritative."""

from __future__ import annotations

import importlib
import secrets
import time
from pathlib import Path
from typing import Any

__all__ = ["CourseChats"]


class CourseChats:
    """Use the installed product's existing stores, never a second course profile."""

    def __init__(self, state_root: Path, plugin_root: Path) -> None:
        self.plugin_root = plugin_root
        self.onboarding = importlib.import_module("local_onboarding")
        self.teaching = importlib.import_module("local_teaching")
        self.store = self.onboarding.Store(state_root)
        self.product = self.store.product
        self.read = (
            self.onboarding._read
            if hasattr(self.onboarding, "_read")
            else importlib.import_module("desktop_teaching.onboarding")._read
        )
        self.write = (
            self.onboarding._write
            if hasattr(self.onboarding, "_write")
            else importlib.import_module("desktop_teaching.onboarding")._write
        )

    def state(self, session: str | None) -> tuple[Any, dict[str, Any]]:
        """Load a saved session or the shared introduction without changing progress."""
        if session:
            store = self.teaching.TeachingStore(self.store.root, session)
            return store, store.status()["session"]
        return self.store, self.store.status()

    def prepare(self, args: dict[str, Any]) -> dict[str, Any]:
        """Persist one bounded invitation only after storage and revision checks."""
        self.store.preflight()
        store, state = self.state(args.get("session_id"))
        if state["revision"] != args["revision"]:
            raise ValueError("Stale course revision; reopen the course panel")
        if state.get("phase") == "paused" or (
            state.get("phase") == "complete"
            and (args.get("session_id") or args["kind"] == "onboarding")
        ):
            raise ValueError("Resume the paused course or select a new course first")
        teacher = args["teacher_thread_id"]
        workflow = args["workflow_id"]
        # Exact installed product membership is a mechanical handoff boundary.
        if self.product == "vera":
            self.onboarding.teaching_contract(workflow)
        else:
            importlib.import_module("desktop_teaching.onboarding").teaching_contract(
                self.plugin_root, workflow
            )
        if args.get("session_id"):
            if args["kind"] != "teaching":
                raise ValueError("A repeatable session requires teaching mode")
            if state["workflow_id"] != workflow:
                raise ValueError("The session belongs to another workflow")
        elif args["kind"] == "onboarding":
            first = next(
                (
                    lesson
                    for lesson in state["lessons"]
                    if lesson["status"] != "complete"
                ),
                None,
            )
            if (
                state["phase"] != "teaching"
                or not first
                or first["workflow_id"] != workflow
                or first.get("paused")
            ):
                raise ValueError(
                    "Select the first unfinished, unpaused introduction lesson"
                )
        elif self.teaching.TeachingStore(self.store.root).status()["active_session"]:
            raise ValueError("Resume or pause the existing active session first")
        pair = (
            self.teaching.TeachingStore(self.store.root).status()["pair"]
            if args["kind"] == "teaching" and not args.get("session_id")
            else state.get("pair")
        )
        if pair and pair["teacher_thread_id"] != teacher:
            raise ValueError("Reopen the saved teacher chat before continuing")
        if pair and not args.get("replace_missing_worker", False):
            return {
                "product": self.product,
                "workflow_id": workflow,
                "title": args["title"],
                "action": "resume",
                "worker_thread_id": pair["worker_thread_id"],
                "state_root": str(self.store.root),
                "session_id": args.get("session_id"),
                "teacher_thread_id": teacher,
            }
        token = secrets.token_hex(24)
        invitation = {
            **args,
            "token": token,
            "expires": time.time() + 1800,
            "claimed_thread_id": None,
        }
        with self.store._lock():
            if self.state(args.get("session_id"))[1]["revision"] != args["revision"]:
                raise ValueError("Course changed; reopen the course panel")
            self.write(self.store.root / "chat-invitation.json", invitation)
        return {
            "product": self.product,
            "workflow_id": workflow,
            "title": args["title"],
            "action": "new",
            "invitation": token,
            "state_root": str(self.store.root),
            "teacher_thread_id": teacher,
        }

    def claim(self, token: str, thread_id: str) -> dict[str, Any]:
        """Bind the actual new native thread, then validate its current assignment."""
        self.store.preflight()
        path = self.store.root / "chat-invitation.json"
        with self.store._lock():
            invitation = self.read(path)
            if (
                not secrets.compare_digest(invitation["token"], token)
                or invitation["expires"] < time.time()
            ):
                raise ValueError(
                    "Invitation expired or replaced; return to the teacher"
                )
            claimed = invitation["claimed_thread_id"]
            if claimed and not invitation.get("bound"):
                raise ValueError(
                    "Previous binding was interrupted; reopen the course panel"
                )
            if claimed and claimed != thread_id:
                raise ValueError("Invitation already belongs to another working chat")
            if thread_id == invitation["teacher_thread_id"]:
                raise ValueError("Teacher and working chats must be distinct")
            if not claimed:
                state = self.state(invitation.get("session_id"))[1]
                if state["revision"] != invitation["revision"]:
                    raise ValueError(
                        "Course changed; return to the teacher for a fresh invitation"
                    )
                # Reserve before releasing the lock. A failed binding stays blocked,
                # never launches a duplicate chat or silently resets the course.
                invitation["claimed_thread_id"] = thread_id
                self.write(path, invitation)
        pair = {
            "teacher_thread_id": invitation["teacher_thread_id"],
            "worker_thread_id": thread_id,
        }
        session = invitation.get("session_id")
        if not invitation.get("bound"):
            store, state = self.state(session)
            if state["revision"] != invitation["revision"]:
                raise ValueError("Course changed during binding; return to the teacher")
            if invitation["kind"] == "onboarding":
                result = store.change("pair", state["revision"], pair)
                result = self.store.change(
                    "start",
                    result["revision"],
                    {"workflow_id": invitation["workflow_id"]},
                )
            elif not session:
                result = self.teaching.TeachingStore(self.store.root).begin(
                    {
                        "workflow_id": invitation["workflow_id"],
                        "title": invitation["title"],
                        "goal": invitation["goal"],
                        "mode": invitation.get("mode", "show"),
                        "pair": pair,
                    }
                )
                session = result["session"]["session_id"]
            else:
                store.change("pair", state["revision"], pair)
            invitation.update(bound=True, session_id=session)
            with self.store._lock():
                latest = self.read(path)
                if latest["token"] != token:
                    raise ValueError("Invitation changed; return to the teacher")
                self.write(path, invitation)
        store, state = self.state(session)
        lesson = (
            state
            if session
            else next(
                item
                for item in state["lessons"]
                if item["workflow_id"] == invitation["workflow_id"]
            )
        )
        result = store.worker(
            thread_id, invitation["workflow_id"], lesson["worker_token"]
        )
        result["instruction"] = (
            "Working chat bound and storage verified. Read workflow_contract.skill_path. Perform only the teacher's bounded assignment; return actual artifacts and status. Only the teacher records progress."
        )
        return result

SHA-256: d9c3f73fc3cd91b9eafc6a058e1a9f09388c166d9268a60082ec3201b4d94b2b