multichat-sdk 0.2.0__py3-none-any.whl

multichat/_recorder.py

@@ -0,0 +1,729 @@
+"""Conversations and recording: which session a call belongs to, the delta it adds, and the
+background worker that sends deltas, usage and queue tasks to the services in order.
+
+Recording never stands in the way of the provider call: lines wait in the conversation until
+the store takes them (a line replaces the line at the same path, so sending again is safe), and
+a failure is logged on the ``multichat`` logger, never raised into your code.
+"""
+
+from __future__ import annotations
+
+import atexit
+import hashlib
+import logging
+import queue
+import threading
+import time
+import uuid
+import weakref
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from . import convert as cv
+from . import sync as sy
+from ._errors import ServiceError
+from .guardrails import GuardrailError
+from .files import parse_data_url
+from .files import ref as file_ref
+from .services import Services, due_at
+
+log = logging.getLogger("multichat")
+
+#: Block kinds that can be files (docs/v2/files.md).
+MEDIA = ("image", "audio", "video", "document")
+
+ENDPOINT = {cv.OPENAI: ["openai", "v1", "chat", "completions"], cv.ANTHROPIC: ["anthropic", "v1", "messages"]}
+
+#: Request fields that are not part of the provider's JSON body.
+TRANSPORT_KEYS = ("extra_headers", "extra_query", "extra_body", "timeout", "betas")
+
+
+# ------------------------------------------------------------------ public records
+
+
+@dataclass
+class KeepAlive:
+    """Keep Anthropic's prompt cache warm between turns (decision 0006, keep-alive).
+
+    The queue sends the turn's exact request again (``max_tokens`` 1) at send time + TTL - margin,
+    and again a TTL later while the session's enhanced cache extensions last (the queue keeps the
+    count, so it never sends more than the session allows); your next turn cancels the chain.
+    ``count=0`` turns it off. The queue needs your key to
+    send it: ``key_mode="held"`` gives it the key, encrypted and deleted once the task fires;
+    ``key_mode="webhook"`` asks your ``webhook`` to send it instead.
+    """
+
+    key_mode: str = "held"
+    webhook: Optional[str] = None
+    count: int = 1
+    margin_s: float = 30.0
+
+
+@dataclass
+class TurnInfo:
+    """What happened in one turn: where it was recorded, who answered, what was sent, and what
+    the planner would change (``changes``; applied only with ``optimise=True``)."""
+
+    session_id: Optional[str]
+    turn: int
+    model: str = ""
+    answered_by: str = "primary"
+    ms: int = 0
+    usage: Dict[str, int] = field(default_factory=dict)
+    optimised: bool = False
+    changes: List[Dict[str, Any]] = field(default_factory=list)
+    x: Optional[Dict[str, Any]] = None
+    y: Optional[Dict[str, Any]] = None
+    sent: Optional[Dict[str, Any]] = None
+
+
+class Conversation:
+    """One conversation, one store session. Pass it as ``conversation=`` to keep calls together
+    explicitly; without it the SDK matches each call's message list to the conversations it has
+    seen (the longest recorded prefix, or the last recorded reply for trimmed histories)."""
+
+    def __init__(self, session_id: Optional[str] = None, fmt: Optional[str] = None):
+        self.session_id = session_id
+        self.fmt = fmt
+        self.hashes: List[str] = []
+        self.turns = sy.Turns()
+        self.model: Optional[str] = None
+        self.tools_key: Optional[str] = None
+        self.params_key: Optional[str] = None
+        # Whether the store may hold a response.tool_choice: a new conversation has none; an existing
+        # session might. A call without tool_choice then sends null@<sid>.response.tool_choice, so
+        # the choice of an earlier call is not kept for this one.
+        self.tool_choice: Optional[bool] = False if session_id is None else None
+        self.loaded = session_id is None  # an existing session is read from the store on first use
+        self.version: Optional[int] = None  # the store version this conversation's deltas are pinned to
+        self.last: Optional[TurnInfo] = None
+        self.preview: Optional[Dict[str, Any]] = None
+        self.spend: Optional[Dict[str, Any]] = None  # the planner's POST /v2/spend answer (guardrails)
+        self.spend_local = 0.0  # replies priced here since that answer
+        self._pending: List[str] = []
+        self._usage: List[Dict[str, Any]] = []
+        self._keepalives: List[str] = []
+        self._lock = threading.Lock()
+
+    def __repr__(self) -> str:
+        return "Conversation(session_id=%r, turn=%d)" % (self.session_id, self.turns.turn)
+
+    @property
+    def turn(self) -> int:
+        return self.turns.turn
+
+    @property
+    def pending(self) -> int:
+        """Lines not yet in the store."""
+        return len(self._pending)
+
+
+@dataclass
+class Prepared:
+    conv: Conversation
+    turn: int
+    fmt: str
+    model: str
+    body: Dict[str, Any]
+    started: float
+    info: TurnInfo
+
+
+# ------------------------------------------------------------------ hashing and deltas
+
+
+def _strip(m: Any) -> Any:
+    if isinstance(m, dict):
+        return {k: _strip(v) for k, v in m.items() if k not in ("cache", "model", "finish")}
+    if isinstance(m, list):
+        return [_strip(x) for x in m]
+    return m
+
+
+def message_hash(neutral: List[Dict[str, Any]]) -> str:
+    return hashlib.sha256(sy.canonical_json(_strip(neutral)).encode("utf-8")).hexdigest()[:32]
+
+
+def source_messages(fmt: str, body: Dict[str, Any]) -> List[List[Dict[str, Any]]]:
+    """The request's messages, each as its neutral messages (the system prompt first for Anthropic)."""
+    out: List[List[Dict[str, Any]]] = []
+    if fmt == cv.ANTHROPIC:
+        sys_msgs = cv.anthropic_system_to_neutral(body.get("system"))
+        if sys_msgs:
+            out.append(sys_msgs)
+        for m in body.get("messages") or []:
+            out.append(cv.anthropic_message_to_neutral(m))
+    else:
+        for m in body.get("messages") or []:
+            out.append(cv.openai_message_to_neutral(m))
+    return out
+
+
+def find_new(recorded: List[str], hashes: List[str]) -> Optional[int]:
+    """Where the new messages start in ``hashes``, given what ``recorded`` holds; None when the
+    request does not continue it. A full prefix counts first; otherwise the last recorded message
+    found in the request (with the one before it, when present) anchors a trimmed history."""
+    n = len(recorded)
+    if n == 0:
+        return None
+    if n <= len(hashes) and hashes[:n] == recorded:
+        return n
+    last = recorded[-1]
+    for j in range(len(hashes) - 1, -1, -1):
+        if hashes[j] == last and (j == 0 or n < 2 or hashes[j - 1] == recorded[-2]):
+            return j + 1
+    return None
+
+
+def params_lines(fmt: str, body: Dict[str, Any], sid: str) -> List[str]:
+    L = lambda v, *p: sy.line(sid, p, v)  # noqa: E731
+    out: List[str] = []
+    t = body.get("temperature")
+    if isinstance(t, (int, float)):
+        out.append(L(int(t / (2 if fmt == cv.OPENAI else 1) * 100 + 0.5), "params", "temperature"))
+    if isinstance(body.get("top_p"), (int, float)):
+        out.append(L(int(body["top_p"] * 100 + 0.5), "params", "top_p"))
+    if isinstance(body.get("top_k"), int):
+        out.append(L(body["top_k"], "params", "top_k"))
+    mt = body.get("max_completion_tokens") or body.get("max_tokens")
+    if isinstance(mt, int):
+        out.append(L(mt, "params", "max_tokens"))
+    if isinstance(body.get("seed"), int):
+        out.append(L(body["seed"], "params", "seed"))
+    stop = body.get("stop") if fmt == cv.OPENAI else body.get("stop_sequences")
+    for i, s in enumerate([stop] if isinstance(stop, str) else (stop or [])):
+        out.append(L(s, "params", "stop", i))
+    if body.get("reasoning_effort"):
+        out.append(L(body["reasoning_effort"], "params", "reasoning_effort"))
+    th = body.get("thinking") or {}
+    if isinstance(th, dict) and th.get("budget_tokens"):
+        out.append(L(th["budget_tokens"], "params", "reasoning_budget"))
+    if body.get("stream") is not None:
+        out.append(L(bool(body.get("stream")), "response", "stream"))
+    tc = body.get("tool_choice")
+    choice = None
+    if isinstance(tc, str):
+        choice = tc
+    elif isinstance(tc, dict):
+        if fmt == cv.ANTHROPIC:
+            choice = {"any": "required", "tool": "tool:" + str(tc.get("name"))}.get(tc.get("type"), tc.get("type"))
+        else:
+            name = (tc.get("function") or {}).get("name")
+            choice = "tool:" + name if name else None
+    if choice:
+        out.append(L(choice, "response", "tool_choice"))
+    return out
+
+
+def has_cache_markers(body: Any) -> Tuple[bool, int]:
+    """Whether a Messages request asks for caching, and the TTL in seconds (5 minutes, or 1 hour)."""
+    found, ttl = False, 300
+
+    def walk(v: Any) -> None:
+        nonlocal found, ttl
+        if isinstance(v, dict):
+            cc = v.get("cache_control")
+            if isinstance(cc, dict):
+                found = True
+                if cc.get("ttl") == "1h":
+                    ttl = 3600
+            for x in v.values():
+                walk(x)
+        elif isinstance(v, list):
+            for x in v:
+                walk(x)
+
+    walk(body)
+    return found, ttl
+
+
+def request_body(kwargs: Dict[str, Any]) -> Dict[str, Any]:
+    """The provider JSON body a create() call sends: transport options left out, extra_body merged."""
+    body = {k: v for k, v in kwargs.items() if k not in TRANSPORT_KEYS}
+    body = cv.plain(body)
+    extra = kwargs.get("extra_body")
+    if isinstance(extra, dict):
+        body.update(cv.plain(extra))
+    return body
+
+
+# ------------------------------------------------------------------ the background worker
+
+
+class _Worker:
+    """One thread running jobs in order, so deltas reach the store in the order they happened."""
+
+    def __init__(self, on_error: Optional[Callable[[Exception], None]] = None) -> None:
+        self._q: "queue.Queue[Optional[Tuple[Callable[[], Any], Optional[threading.Event]]]]" = queue.Queue()
+        self._thread: Optional[threading.Thread] = None
+        self._lock = threading.Lock()
+        self.on_error = on_error
+        self.off = False  # the account cannot record: queued jobs are dropped
+
+    def submit(self, fn: Callable[[], Any]) -> threading.Event:
+        done = threading.Event()
+        with self._lock:
+            if self._thread is None or not self._thread.is_alive():
+                self._thread = threading.Thread(target=self._run, name="multichat-recorder", daemon=True)
+                self._thread.start()
+        self._q.put((fn, done))
+        return done
+
+    def _run(self) -> None:
+        while True:
+            item = self._q.get()
+            if item is None:
+                return
+            fn, done = item
+            try:
+                if not self.off:
+                    fn()
+            except Exception as e:  # never let one job stop the worker
+                if self.on_error is not None:
+                    self.on_error(e)
+                else:
+                    log.warning("multichat: %s", e)
+            finally:
+                if done is not None:
+                    done.set()
+
+    def drain(self, timeout: float) -> bool:
+        """Waits until every job submitted so far has run."""
+        return self.submit(lambda: None).wait(timeout)
+
+
+#: Statuses with which a multiChat service refuses the account itself (no or a revoked key, no plan,
+#: out of credit): the drop-in clients then stop recording and pass every call to the provider.
+ACCOUNT_STATUSES = (401, 402, 403)
+
+
+def account_refused(e: BaseException) -> bool:
+    return isinstance(e, ServiceError) and e.status_code in ACCOUNT_STATUSES
+
+
+_recorders: "weakref.WeakSet[Recorder]" = weakref.WeakSet()
+
+
+@atexit.register
+def _flush_all() -> None:  # pragma: no cover - runs at interpreter exit
+    for r in list(_recorders):
+        try:
+            r.flush(timeout=5)
+        except Exception:
+            pass
+
+
+class Recorder:
+    """Records the conversations of one client (and its copies) in the store."""
+
+    def __init__(self, services: Services, *, keepalive: Optional[KeepAlive] = None,
+                 provider_key: Optional[Callable[[], Optional[str]]] = None,
+                 provider_base_url: Optional[Callable[[], Optional[str]]] = None, max_conversations: int = 512,
+                 record_files: bool = True):
+        self.services = services
+        # Inline media (data: URLs) go to the provider as written; the store gets a file reference.
+        self.record_files = record_files
+        self._files_off = False  # the store has no files here (503) or keeps nothing (ZDR)
+        self._file_refs: "OrderedDict[Tuple[str, str], str]" = OrderedDict()  # (session, sha256) -> mcfile:<id>
+        self.keepalive = keepalive
+        self.provider_key = provider_key or (lambda: None)
+        self.provider_base_url = provider_base_url or (lambda: None)
+        self.conversations: "OrderedDict[int, Conversation]" = OrderedDict()
+        self.max_conversations = max_conversations
+        self.last: Optional[TurnInfo] = None
+        self.guard: Any = None  # guardrails.Guard: checked before each call (docs/v2/advice.md)
+        self.off = False  # the multiChat account is missing, invalid or out of credit: record nothing
+        self._worker = _Worker(self._failed)
+        self._lock = threading.Lock()
+        _recorders.add(self)
+
+    def _failed(self, e: Exception) -> None:
+        """A recording job failed. When the store refused the account (401, 402, 403: missing,
+        invalid or out of credit; decision 0008), recording stops for this client and every call
+        goes straight to the provider, with one log line; anything else is logged and retried later."""
+        if account_refused(e):
+            self.stop(e)
+            return
+        log.warning("multichat: %s", e)
+
+    def stop(self, why: Any) -> None:
+        """Stops recording for good (the account cannot record); logs once."""
+        if self.off:
+            return
+        self.off = True
+        self._worker.off = True
+        log.warning("multichat: the multiChat account cannot record (%s): calls go straight to the provider, "
+                    "without recording or multiChat features", why)
+
+    # ---------------------------------------------------------------- conversations
+
+    def conversation(self, session_id: Optional[str] = None) -> Conversation:
+        """A new conversation, or an existing session to continue (read from the store on first use)."""
+        conv = Conversation(session_id)
+        self._keep(conv)
+        return conv
+
+    def _keep(self, conv: Conversation) -> None:
+        with self._lock:
+            self.conversations[id(conv)] = conv
+            self.conversations.move_to_end(id(conv))
+            while len(self.conversations) > self.max_conversations:
+                self.conversations.popitem(last=False)
+
+    def _match(self, hashes: List[str], fmt: str) -> Tuple[Optional[Conversation], int]:
+        best, start, best_full = None, 0, False
+        with self._lock:
+            convs = list(self.conversations.values())
+        for conv in convs:
+            if conv.fmt not in (None, fmt) or not conv.hashes:
+                continue
+            at = find_new(conv.hashes, hashes)
+            if at is None:
+                continue
+            full = hashes[:len(conv.hashes)] == conv.hashes
+            if best is None or (full, at) > (best_full, start):
+                best, start, best_full = conv, at, full
+        return best, start
+
+    def _load(self, conv: Conversation) -> None:
+        """Reads an existing session's turn numbers and messages from the store."""
+        conv.loaded = True
+        try:
+            snap = self.services.snapshot(conv.session_id)  # type: ignore[arg-type]
+        except Exception as e:
+            log.warning("multichat: could not read session %s: %s", conv.session_id, e)
+            return
+        conv.version = snap.get("current_version", snap.get("version"))
+        msgs = sy.lines_to_messages(snap.get("lines") or [])
+        last_turn, count = 0, 0
+        for raw in snap.get("lines") or []:
+            p = sy.parse_line(raw)
+            if p and len(p[1]) > 2 and p[1][0] == "history" and p[1][1].isdigit() and p[1][2].isdigit():
+                t, m = int(p[1][1]), int(p[1][2])
+                if t > last_turn:
+                    last_turn, count = t, m + 1
+                elif t == last_turn:
+                    count = max(count, m + 1)
+        conv.turns = sy.Turns(last_turn, count)
+        fmt = conv.fmt or cv.OPENAI
+        conv.hashes = [message_hash([m]) for m in msgs] if fmt == cv.OPENAI else \
+            [message_hash(cv.anthropic_message_to_neutral(a)) for a in cv.neutral_to_anthropic(msgs)[1]]
+
+    # ---------------------------------------------------------------- a turn
+
+    def begin(self, fmt: str, body: Dict[str, Any], handle: Optional[Any] = None) -> Optional[Prepared]:
+        """Finds the call's conversation, queues its new lines, and cancels the last keep-alive."""
+        if self.off:
+            return None
+        try:
+            return self._begin(fmt, body, handle)
+        except GuardrailError:
+            raise  # a limit stops the call before anything is recorded or sent
+        except Exception as e:  # recording must never break the call
+            log.warning("multichat: not recorded: %s", e)
+            return None
+
+    def _begin(self, fmt: str, body: Dict[str, Any], handle: Optional[Any]) -> Prepared:
+        src = source_messages(fmt, body)
+        hashes = [message_hash(n) for n in src]
+        conv: Optional[Conversation]
+        if isinstance(handle, str):
+            handle = self._by_session(handle) or self.conversation(handle)
+        if isinstance(handle, Conversation):
+            conv = handle
+            self._keep(conv)
+            if not conv.loaded:
+                self._load(conv)
+            start = find_new(conv.hashes, hashes)
+            if start is None:
+                start = 0 if not conv.hashes else _after_last_assistant(src)
+        else:
+            conv, start = self._match(hashes, fmt)
+            if conv is None:
+                conv, start = self.conversation(), 0
+        conv.fmt = conv.fmt or fmt
+        if self.guard is not None:
+            self.guard.check(conv, body)
+        model = str(body.get("model") or "")
+        sid = sy.NIL_SID
+        lines: List[str] = []
+        if model and model != conv.model:
+            lines.append(sy.line(sid, ["endpoint"] + ENDPOINT[fmt], model))
+            conv.model = model
+        tools = cv.openai_tools_to_neutral(body.get("tools")) if fmt == cv.OPENAI else cv.anthropic_tools_to_neutral(body.get("tools"))
+        tkey = message_hash(tools) if tools else ""
+        if tkey != (conv.tools_key or ""):
+            if conv.tools_key:
+                lines.append(sy.line(sid, ["tools"], "null"))
+            lines += sy.tool_lines(sid, tools)
+        conv.tools_key = tkey
+        plines = params_lines(fmt, body, sid)
+        has_choice = any(sy.parse_line(x)[1] == ["response", "tool_choice"] for x in plines)  # type: ignore[index]
+        if not has_choice and conv.tool_choice is not False:
+            plines.append(sy.line(sid, ["response", "tool_choice"], "null"))
+        pkey = message_hash(plines)  # type: ignore[arg-type]
+        if pkey != conv.params_key:
+            lines += plines
+            conv.params_key = pkey
+            conv.tool_choice = has_choice
+        for neutral in src[start:]:
+            for m in neutral:
+                t, i = conv.turns.next(m["role"])
+                lines += sy.message_lines(sid, t, i, m)
+        conv.hashes = hashes
+        info = TurnInfo(session_id=conv.session_id, turn=conv.turns.turn, model=model)
+        prep = Prepared(conv=conv, turn=conv.turns.turn, fmt=fmt, model=model, body=body, started=time.monotonic(), info=info)
+        with conv._lock:
+            conv._pending += lines
+        turn = prep.turn
+        self._worker.submit(lambda: self._cancel_keepalives(conv, turn))
+        self._worker.submit(lambda: self._flush(conv))
+        return prep
+
+    def _by_session(self, sid: str) -> Optional[Conversation]:
+        with self._lock:
+            return next((c for c in self.conversations.values() if c.session_id == sid), None)
+
+    def finish(self, prep: Optional[Prepared], response: Dict[str, Any], *, answered_by: str = "primary",
+               fmt: Optional[str] = None, sent: Optional[Dict[str, Any]] = None, preview: bool = False) -> Optional[TurnInfo]:
+        """Records the reply (``response`` in ``fmt``, the primary's format by default) and its usage."""
+        if prep is None:
+            return None
+        try:
+            return self._finish(prep, response, answered_by, fmt or prep.fmt, sent, preview)
+        except Exception as e:
+            log.warning("multichat: reply not recorded: %s", e)
+            return None
+
+    def _finish(self, prep: Prepared, response: Dict[str, Any], answered_by: str, fmt: str,
+                sent: Optional[Dict[str, Any]], preview: bool) -> TurnInfo:
+        conv = prep.conv
+        msg, usage = cv.response_to_neutral(response, fmt)
+        ms = int((time.monotonic() - prep.started) * 1000)
+        t, i = conv.turns.next("assistant")
+        lines = sy.message_lines(sy.NIL_SID, t, i, msg, usage)
+        # The reply as the caller will append it to their history, in the primary's format.
+        as_primary = cv.assistant_message(msg, prep.fmt)
+        nm = cv.openai_message_to_neutral(as_primary) if prep.fmt == cv.OPENAI else cv.anthropic_message_to_neutral(as_primary)
+        conv.hashes = conv.hashes + [message_hash(nm)]
+        info = prep.info
+        info.model, info.answered_by, info.ms, info.usage = msg.get("model") or prep.model, answered_by, ms, usage
+        info.sent = sent or prep.body
+        record = dict(usage, turn=prep.turn, model=info.model, ms=ms, answered_by=answered_by)
+        with conv._lock:
+            conv._pending += lines
+            conv._usage.append(record)
+            # The session may have been created while the provider answered (begin's flush).
+            info.session_id = info.session_id or conv.session_id
+            conv.last = info
+        self.last = info
+        self._worker.submit(lambda: self._flush(conv))
+        if self.guard is not None:
+            self.guard.after(conv, info)
+        if answered_by == "primary" and prep.fmt == cv.ANTHROPIC and self.keepalive and self.keepalive.count > 0:
+            found, ttl = has_cache_markers(info.sent)
+            if found:
+                body = dict(info.sent or {}, max_tokens=1)
+                body.pop("stream", None)
+                self._worker.submit(lambda: self._schedule_keepalive(conv, prep.turn, body, ttl))
+        if preview:
+            self._worker.submit(lambda: self._preview(conv, info, prep.model))
+        return info
+
+    # ---------------------------------------------------------------- jobs (worker thread)
+
+    def _flush(self, conv: Conversation) -> None:
+        for attempt in range(3):
+            try:
+                self._send(conv)
+                return
+            except Exception as e:
+                if account_refused(e):
+                    self.stop(e)  # the account cannot record: no retries, nothing kept
+                    return
+                if attempt == 2:
+                    log.warning("multichat: store unavailable, %d lines kept for the next turn: %s", conv.pending, e)
+                    return
+                time.sleep(0.2 * (attempt + 1))
+
+    def _send(self, conv: Conversation) -> None:
+        with conv._lock:
+            lines = list(conv._pending)
+            usage = list(conv._usage)
+        if not lines and not usage:
+            return
+        if conv.session_id is None:
+            created = self.services.create_session()
+            with conv._lock:
+                conv.session_id = created["session_id"]
+                conv.version = created.get("version")
+                if conv.last is not None:
+                    conv.last.session_id = conv.session_id
+        if lines:
+            orig = lines
+            if self.record_files and not self._files_off:
+                lines = self._record_files(conv, lines)
+                if lines is not orig:
+                    with conv._lock:  # a retry sends the same references, not new uploads
+                        conv._pending[:len(orig)] = lines
+            try:
+                self._delta(conv, sy.readdress(lines, conv.session_id))
+            except ServiceError as e:
+                # A referenced file was deleted meanwhile: upload again from the original bytes.
+                if e.status_code != 400 or "mcfile:" not in str(e) or lines is orig:
+                    raise
+                self._forget_files(conv)
+                lines = self._record_files(conv, orig)
+                self._delta(conv, sy.readdress(lines, conv.session_id))
+            with conv._lock:
+                del conv._pending[:len(lines)]
+        for rec in usage:
+            self.services.usage(conv.session_id, rec)
+            with conv._lock:
+                conv._usage.remove(rec)
+
+    def _record_files(self, conv: Conversation, lines: List[str]) -> List[str]:
+        """Replaces each inline media value (a ``data:`` URL) with the reference of an uploaded file,
+        tied to the conversation's session; a failed upload keeps the bytes in the line. Answers
+        ``lines`` itself when nothing changed."""
+        out, changed = [], False
+        for raw in lines:
+            p = sy.parse_line(raw)
+            if not self._files_off and p and len(p[1]) == 6 and p[1][0] == "history" and p[1][5] in MEDIA:
+                got = parse_data_url(p[2])
+                if got:
+                    r = self._upload(conv, got[0], got[1])
+                    if r:
+                        raw, changed = sy.line(p[0], p[1], r), True
+            out.append(raw)
+        return out if changed else lines
+
+    def _upload(self, conv: Conversation, mime: str, data: bytes) -> Optional[str]:
+        key = (conv.session_id or "", hashlib.sha256(data).hexdigest())
+        with self._lock:
+            if key in self._file_refs:
+                return self._file_refs[key]
+        try:
+            f = self.services.upload_file(data, mime, session=conv.session_id)
+        except ServiceError as e:
+            if e.status_code in (403, 404, 405, 501, 503):
+                self._files_off = True  # no files here: keep recording the bytes inline
+            log.info("multichat: file not uploaded, its bytes stay in the conversation: %s", e)
+            return None
+        except Exception as e:
+            log.info("multichat: file not uploaded, its bytes stay in the conversation: %s", e)
+            return None
+        r = f.get("ref") or file_ref(f["id"])
+        with self._lock:
+            self._file_refs[key] = r
+            while len(self._file_refs) > 1024:
+                self._file_refs.popitem(last=False)
+        return r
+
+    def _forget_files(self, conv: Conversation) -> None:
+        with self._lock:
+            for k in [k for k in self._file_refs if k[0] == (conv.session_id or "")]:
+                del self._file_refs[k]
+
+    def _delta(self, conv: Conversation, lines: List[str]) -> None:
+        """Sends a delta pinned to the version this conversation last saw. When a service wrote a
+        newer version meanwhile (the planner's compacted items, docs/v2/planner.md), the store
+        answers 409 version_conflict: the session is read again and the delta retried once."""
+        try:
+            r = self.services.delta(conv.session_id, lines, version=conv.version)  # type: ignore[arg-type]
+        except ServiceError as e:
+            if e.status_code != 409 or e.code != "version_conflict":
+                raise
+            snap = self.services.snapshot(conv.session_id)  # type: ignore[arg-type]
+            conv.version = snap.get("current_version", snap.get("version"))
+            r = self.services.delta(conv.session_id, lines, version=conv.version)  # type: ignore[arg-type]
+        if isinstance(r, dict) and isinstance(r.get("version"), int):
+            conv.version = r["version"]
+
+    def _cancel_keepalives(self, conv: Conversation, turn: Optional[int] = None) -> None:
+        with conv._lock:
+            names, conv._keepalives = conv._keepalives, []
+        for name in names:
+            try:
+                self.services.cancel_task(name)
+            except Exception as e:
+                log.warning("multichat: could not cancel keep-alive %s: %s", name, e)
+        if names and turn is not None and conv.session_id:
+            # The scheduler's own flip (docs/v2/bitguard.md, path 3), besides the cancel above.
+            try:
+                self.services.signal(conv.session_id, turn, "turn")
+            except Exception as e:
+                log.debug("multichat: signal not sent: %s", e)
+
+    def _schedule_keepalive(self, conv: Conversation, turn: int, body: Dict[str, Any], ttl: int) -> None:
+        ka = self.keepalive
+        if ka is None or conv.session_id is None:
+            return
+        # One task, the first of the chain (count 0): the queue schedules each next one while the
+        # session's extensions remain (docs/v2/queue.md "Keep-alive rules"). Posting more here would
+        # start chains of their own and go past the session's extension count.
+        name = "keepalive-%s-%d" % (conv.session_id, turn)
+        task: Dict[str, Any] = {"name": name, "kind": "keepalive", "session": conv.session_id, "turn": turn,
+                                "due_at": due_at(max(ttl - ka.margin_s, 1)), "request": body, "provider": "anthropic",
+                                "key_mode": ka.key_mode, "count": 0}
+        base = self.provider_base_url()
+        if base:
+            task["base_url"] = base
+        if ka.key_mode == "held":
+            task["key"] = self.provider_key()
+        elif ka.key_mode == "webhook":
+            task["webhook"] = ka.webhook
+        self.services.post_task(task)
+        with conv._lock:
+            conv._keepalives.append(name)
+
+    def _preview(self, conv: Conversation, info: TurnInfo, model: str) -> None:
+        if conv.session_id is None or not conv.fmt:
+            return
+        plan = self.services.assemble(conv.session_id, conv.fmt, model or None)
+        conv.preview = plan
+        info.changes, info.x, info.y = plan.get("changes") or [], plan.get("x"), plan.get("y")
+        if info.changes:
+            saved = sum(int(c.get("tokens_saved") or 0) for c in info.changes)
+            log.info("multichat: optimise=True would make %d change(s) to the next request (about %d tokens saved): %s",
+                     len(info.changes), saved, "; ".join(str(c.get("what")) for c in info.changes))
+
+    # ---------------------------------------------------------------- waiting
+
+    def flush(self, timeout: float = 10.0) -> bool:
+        """Waits until everything queued so far has been sent (or failed and been kept)."""
+        return self._worker.drain(timeout)
+
+    def ensure_session(self, prep: Prepared, timeout: float = 10.0) -> Optional[str]:
+        """Sends the turn's lines now and returns the session ID (None if the store is unreachable)."""
+        self.flush(timeout)
+        return prep.conv.session_id
+
+    def optimised(self, prep: Prepared, timeout: float = 10.0) -> Optional[Dict[str, Any]]:
+        """``optimise=True``: the assembled request for this turn, or None (the call goes as written)."""
+        sid = self.ensure_session(prep, timeout)
+        if sid is None:
+            log.warning("multichat: optimise skipped: the store did not take the turn")
+            return None
+        try:
+            plan = self.services.assemble(sid, prep.fmt, prep.model or None)
+        except Exception as e:
+            log.warning("multichat: optimise skipped: %s", e)
+            return None
+        prep.info.optimised = True
+        prep.info.changes, prep.info.x, prep.info.y = plan.get("changes") or [], plan.get("x"), plan.get("y")
+        prep.conv.preview = plan
+        if prep.info.changes:
+            log.info("multichat: optimised: %s", "; ".join(str(c.get("what")) for c in prep.info.changes))
+        return plan.get("request")
+
+    def new_name(self, kind: str, prep: Prepared) -> str:
+        return "%s-%s-%d-%s" % (kind, prep.conv.session_id, prep.turn, uuid.uuid4().hex[:6])
+
+
+def _after_last_assistant(src: List[List[Dict[str, Any]]]) -> int:
+    for j in range(len(src) - 1, -1, -1):
+        if any(m["role"] == "assistant" for m in src[j]):
+            return j + 1
+    return 0