@capagents/forgeqe 2.2.1 → 2.2.3

package/py/forgeqe_engine/copilot_gateway.py

@@ -0,0 +1,369 @@
+"""
+GitHub Copilot as an OpenAI-style chat endpoint on this machine, through GitHub's Copilot SDK.
+
+Copilot has no model API for other tools: the SDK runs Copilot "sessions" on the user's seat. The browser engine and
+the desktop agent speak OpenAI chat completions, so this gateway turns each request into one SDK session with no
+tools of its own (the system prompt replaced, screenshots attached, a JSON schema passed on) and answers in the
+OpenAI shape.
+
+  python -m forgeqe_engine copilot-gateway
+    env    COPILOT_GITHUB_TOKEN          the GitHub token (fine-grained with Copilot Requests, or the GitHub CLI's)
+           FORGEQE_COPILOT_GATEWAY_KEY   the one-time key every request must carry as "Bearer <key>"
+    stdout one line: {"port": N, "login": "<account>"} once it listens, or {"error": "..."}
+    stdin  end of input stops it, so it never outlives ForgeQE
+
+It listens on 127.0.0.1 only, compares the key in constant time and refuses requests a web page sends.
+"""
+from __future__ import annotations
+
+import asyncio
+import hmac
+import json
+import os
+import sys
+import tempfile
+import time
+import uuid
+from typing import Any, Dict, List, Optional, TextIO, Tuple
+
+TOKEN_ENV = "COPILOT_GITHUB_TOKEN"
+KEY_ENV = "FORGEQE_COPILOT_GATEWAY_KEY"
+
+MAX_BODY = 32 * 1024 * 1024
+# A screenshot step can take minutes on a slow model; past this the request fails rather than hangs.
+REQUEST_TIMEOUT_S = 300.0
+LOCAL_ORIGINS = ("http://127.0.0.1", "http://localhost", "https://127.0.0.1", "https://localhost")
+
+
+class GatewayError(Exception):
+    def __init__(self, status: int, message: str):
+        super().__init__(message)
+        self.status = status
+        self.message = message
+
+
+# ---------------------------------------------------------------------------------------------------------------------
+# OpenAI chat completions → one Copilot session
+
+
+def _parts(content: Any) -> List[Dict[str, Any]]:
+    if isinstance(content, str):
+        return [{"type": "text", "text": content}]
+    if isinstance(content, list):
+        return [p for p in content if isinstance(p, dict)]
+    return []
+
+
+def _data_url(url: str) -> Optional[Tuple[str, str]]:
+    """data:image/png;base64,AAAA → ("image/png", "AAAA"); None for anything else (remote images are not fetched)."""
+    if not url.startswith("data:") or ";base64," not in url:
+        return None
+    head, data = url[5:].split(";base64,", 1)
+    mime = head.split(";", 1)[0].strip().lower()
+    if not mime.startswith("image/") or not data:
+        return None
+    return mime, data
+
+
+def translate(body: Dict[str, Any]) -> Dict[str, Any]:
+    """The session a chat completions request becomes: {model, system, prompt, attachments, schema, json_only}."""
+    if not isinstance(body, dict):
+        raise GatewayError(400, "The request body must be a JSON object.")
+    model = str(body.get("model") or "").strip()
+    if not model:
+        raise GatewayError(400, "The request names no model.")
+    if body.get("stream"):
+        raise GatewayError(400, "Streaming is not supported by ForgeQE's Copilot gateway.")
+    if body.get("tools") or body.get("functions"):
+        raise GatewayError(400, "Tool calls are not supported by ForgeQE's Copilot gateway yet.")
+    messages = body.get("messages")
+    if not isinstance(messages, list) or not messages:
+        raise GatewayError(400, "The request has no messages.")
+
+    system: List[str] = []
+    turns: List[Tuple[str, List[Dict[str, Any]]]] = []
+    for m in messages:
+        if not isinstance(m, dict):
+            continue
+        role = str(m.get("role") or "user")
+        parts = _parts(m.get("content"))
+        if role in ("system", "developer"):
+            system.extend(str(p.get("text") or "") for p in parts if p.get("type") == "text")
+        else:
+            turns.append((role, parts))
+    if not turns:
+        raise GatewayError(400, "The request has no user message.")
+
+    # Only the latest message's images go to the model; the browser agent sends the current screenshot there.
+    last_with_images = max((i for i, (_, parts) in enumerate(turns) if any(p.get("type") == "image_url" for p in parts)), default=-1)
+    attachments: List[Dict[str, Any]] = []
+    lines: List[str] = []
+    for i, (role, parts) in enumerate(turns):
+        texts: List[str] = []
+        for p in parts:
+            if p.get("type") == "text":
+                texts.append(str(p.get("text") or ""))
+            elif p.get("type") == "image_url":
+                url = p.get("image_url", {}).get("url") if isinstance(p.get("image_url"), dict) else p.get("image_url")
+                img = _data_url(str(url or ""))
+                if img and i == last_with_images:
+                    attachments.append({"type": "blob", "mimeType": img[0], "data": img[1], "displayName": f"screenshot-{len(attachments) + 1}"})
+                    texts.append(f"[image attached: screenshot-{len(attachments)}]")
+                else:
+                    texts.append("[earlier image omitted]")
+        text = "\n".join(t for t in texts if t)
+        lines.append(text if len(turns) == 1 else f"<{role}>\n{text}\n</{role}>")
+    prompt = "\n\n".join(lines)
+    if len(turns) > 1:
+        prompt = "The conversation so far, oldest first. Reply as the assistant to the last message.\n\n" + prompt
+
+    schema = None
+    json_only = False
+    fmt = body.get("response_format")
+    if isinstance(fmt, dict):
+        if fmt.get("type") == "json_schema" and isinstance(fmt.get("json_schema"), dict):
+            schema = fmt["json_schema"].get("schema")
+            if not isinstance(schema, dict):
+                raise GatewayError(400, "response_format.json_schema has no schema.")
+        elif fmt.get("type") == "json_object":
+            json_only = True
+            prompt += "\n\nReply with a single JSON object and nothing else."
+    return {"model": model, "system": "\n\n".join(s for s in system if s), "prompt": prompt, "attachments": attachments, "schema": schema, "json_only": json_only}
+
+
+def completion(model: str, content: str, usage: Dict[str, int]) -> Dict[str, Any]:
+    """An OpenAI chat.completion object."""
+    prompt_tokens = int(usage.get("input", 0))
+    completion_tokens = int(usage.get("output", 0))
+    out: Dict[str, Any] = {
+        "id": f"chatcmpl-{uuid.uuid4().hex}",
+        "object": "chat.completion",
+        "created": int(time.time()),
+        "model": model,
+        "choices": [{"index": 0, "message": {"role": "assistant", "content": content}, "finish_reason": "stop"}],
+        "usage": {"prompt_tokens": prompt_tokens, "completion_tokens": completion_tokens, "total_tokens": prompt_tokens + completion_tokens},
+    }
+    if usage.get("cached"):
+        out["usage"]["prompt_tokens_details"] = {"cached_tokens": int(usage["cached"])}
+    return out
+
+
+def strip_fences(text: str) -> str:
+    """```json … ``` → the JSON inside, for models that wrap structured replies in a code fence."""
+    t = text.strip()
+    if t.startswith("```") and t.endswith("```"):
+        t = t[3:-3]
+        first, _, rest = t.partition("\n")
+        return (rest if first.strip().isalpha() or not first.strip() else t).strip()
+    return text
+
+
+# ---------------------------------------------------------------------------------------------------------------------
+# Requests from this machine only
+
+
+def authorized(headers: Dict[str, str], key: str) -> bool:
+    expected = f"Bearer {key}".encode()
+    got = headers.get("authorization", "").encode()
+    return bool(key) and hmac.compare_digest(got, expected)
+
+
+def local_origin(headers: Dict[str, str]) -> bool:
+    """True when no browser page sent the request: no Origin, or one on this machine."""
+    origin = headers.get("origin")
+    if origin is None:
+        return True
+    o = origin.strip().lower()
+    return any(o == base or o.startswith(base + ":") for base in LOCAL_ORIGINS)
+
+
+# ---------------------------------------------------------------------------------------------------------------------
+# The Copilot SDK
+
+
+class Copilot:
+    def __init__(self, token: str):
+        from copilot import CopilotClient
+
+        # The SDK keeps its state under this folder, apart from the user's own Copilot CLI.
+        home = os.path.join(os.environ.get("FORGEQE_HOME") or os.path.join(os.path.expanduser("~"), ".forgeqe"), "copilot")
+        os.makedirs(home, exist_ok=True)
+        # An empty working folder: the session reads no project files and no custom instructions.
+        self.workdir = tempfile.mkdtemp(prefix="forgeqe-copilot-")
+        self.client = CopilotClient(github_token=token, use_logged_in_user=False, base_directory=home, working_directory=self.workdir, log_level="error")
+
+    async def start(self) -> None:
+        await self.client.start()
+        status = await self.client.get_auth_status()
+        self.login = status.login or ""
+        if not status.isAuthenticated:
+            raise GatewayError(401, "GitHub Copilot did not accept the token: use a fine-grained token with the Copilot Requests permission, or the GitHub CLI's sign-in, for an account with a Copilot seat.")
+
+    async def stop(self) -> None:
+        try:
+            await self.client.stop()
+        except Exception:
+            pass
+
+    async def models(self) -> List[Dict[str, Any]]:
+        out = []
+        for m in await self.client.list_models():
+            supports = getattr(getattr(m, "capabilities", None), "supports", None)
+            out.append({"id": m.id, "object": "model", "owned_by": "github-copilot", "vision": bool(getattr(supports, "vision", False))})
+        return out
+
+    async def complete(self, req: Dict[str, Any]) -> Dict[str, Any]:
+        from copilot.generated.rpc import PermissionDecisionReject
+        from copilot.session_events import AssistantMessageData, AssistantUsageData, SessionErrorData
+
+        usage = {"input": 0, "output": 0, "cached": 0}
+        errors: List[str] = []
+
+        def on_event(event: Any) -> None:
+            data = getattr(event, "data", None)
+            if isinstance(data, AssistantUsageData):
+                usage["input"] += data.input_tokens or 0
+                usage["output"] += data.output_tokens or 0
+                usage["cached"] += data.cache_read_tokens or 0
+            elif isinstance(data, SessionErrorData):
+                errors.append(data.message or data.error_type or "error")
+
+        session = await self.client.create_session(
+            model=req["model"],
+            # The caller's prompt is the whole prompt; without one the session still gets no tools.
+            system_message={"mode": "replace", "content": req["system"] or "You are a helpful assistant."},
+            available_tools=[],
+            on_permission_request=lambda *_: PermissionDecisionReject(),
+            working_directory=self.workdir,
+            skip_custom_instructions=True,
+            enable_config_discovery=False,
+            enable_skills=False,
+            enable_session_store=False,
+            on_event=on_event,
+        )
+        try:
+            reply = await session.send_and_wait(req["prompt"], attachments=req["attachments"] or None, response_schema=req["schema"], timeout=REQUEST_TIMEOUT_S)
+        except TimeoutError:
+            raise GatewayError(504, f"GitHub Copilot did not answer within {int(REQUEST_TIMEOUT_S)} seconds.")
+        finally:
+            try:
+                await session.disconnect()
+            except Exception:
+                pass
+        if errors:
+            msg = errors[-1]
+            raise GatewayError(401 if "auth" in msg.lower() or "401" in msg else 502, f"GitHub Copilot: {msg}")
+        data = getattr(reply, "data", None)
+        if not isinstance(data, AssistantMessageData):
+            raise GatewayError(502, "GitHub Copilot sent no reply.")
+        content = data.content or ""
+        if req["schema"] is not None or req["json_only"]:
+            content = strip_fences(content)
+        return completion(req["model"], content, usage)
+
+
+# ---------------------------------------------------------------------------------------------------------------------
+# A small HTTP/1.1 server: one request per connection
+
+
+def _response(status: int, payload: Dict[str, Any]) -> bytes:
+    body = json.dumps(payload).encode()
+    reason = {200: "OK", 400: "Bad Request", 401: "Unauthorized", 403: "Forbidden", 404: "Not Found", 413: "Payload Too Large", 502: "Bad Gateway", 504: "Gateway Timeout"}.get(status, "Error")
+    head = f"HTTP/1.1 {status} {reason}\r\nContent-Type: application/json\r\nContent-Length: {len(body)}\r\nConnection: close\r\n\r\n"
+    return head.encode() + body
+
+
+def _error(status: int, message: str) -> bytes:
+    return _response(status, {"error": {"message": message, "type": "forgeqe_copilot_gateway"}})
+
+
+async def handle(reader: asyncio.StreamReader, writer: asyncio.StreamWriter, copilot: Any, key: str) -> None:
+    try:
+        try:
+            head = await reader.readuntil(b"\r\n\r\n")
+        except (asyncio.IncompleteReadError, asyncio.LimitOverrunError):
+            return
+        lines = head.decode("latin-1").split("\r\n")
+        method, path = (lines[0].split(" ") + ["", ""])[:2]
+        headers = {}
+        for line in lines[1:]:
+            if ":" in line:
+                k, v = line.split(":", 1)
+                headers[k.strip().lower()] = v.strip()
+        if not local_origin(headers):
+            writer.write(_error(403, "Requests from web pages are refused."))
+            return
+        if not authorized(headers, key):
+            writer.write(_error(401, "Unauthorized"))
+            return
+        path = path.split("?", 1)[0].rstrip("/")
+        if path.startswith("/v1/"):
+            path = path[3:]
+        if method == "GET" and path == "/models":
+            writer.write(_response(200, {"object": "list", "data": await copilot.models()}))
+            return
+        if method != "POST" or path != "/chat/completions":
+            writer.write(_error(404, f"{method} {path} is not served here."))
+            return
+        try:
+            length = int(headers.get("content-length", "0"))
+        except ValueError:
+            length = -1
+        if length < 0 or length > MAX_BODY:
+            writer.write(_error(413, "The request body is too large."))
+            return
+        raw = await reader.readexactly(length)
+        try:
+            body = json.loads(raw.decode("utf-8"))
+        except ValueError:
+            writer.write(_error(400, "The request body is not JSON."))
+            return
+        writer.write(_response(200, await copilot.complete(translate(body))))
+    except GatewayError as e:
+        writer.write(_error(e.status, e.message))
+    except Exception as e:  # The SDK's own errors: report them rather than drop the connection.
+        writer.write(_error(502, f"GitHub Copilot: {type(e).__name__}: {e}"[:2000]))
+    finally:
+        try:
+            await writer.drain()
+            writer.close()
+        except Exception:
+            pass
+
+
+async def serve(out: TextIO, copilot: Any = None) -> int:
+    key = os.environ.get(KEY_ENV, "")
+    token = os.environ.get(TOKEN_ENV, "").strip()
+    if len(key) < 32:
+        out.write(json.dumps({"error": f"{KEY_ENV} must hold the gateway's one-time key."}) + "\n")
+        return 2
+    if copilot is None:
+        if not token:
+            out.write(json.dumps({"error": "No GitHub token for Copilot: run forgeqe auth login copilot."}) + "\n")
+            return 1
+        if token.startswith("ghp_"):
+            out.write(json.dumps({"error": "GitHub Copilot does not take classic tokens (ghp_): use a fine-grained token with the Copilot Requests permission."}) + "\n")
+            return 1
+        try:
+            copilot = Copilot(token)
+            await copilot.start()
+        except GatewayError as e:
+            out.write(json.dumps({"error": e.message}) + "\n")
+            return 1
+        except Exception as e:
+            out.write(json.dumps({"error": f"GitHub Copilot could not start: {type(e).__name__}: {e}"[:1500]}) + "\n")
+            return 1
+    server = await asyncio.start_server(lambda r, w: handle(r, w, copilot, key), host="127.0.0.1", port=0, limit=64 * 1024)
+    port = server.sockets[0].getsockname()[1]
+    out.write(json.dumps({"port": port, "login": getattr(copilot, "login", "")}) + "\n")
+    out.flush()
+    loop = asyncio.get_running_loop()
+    # Stop when ForgeQE closes stdin (or exits).
+    await loop.run_in_executor(None, sys.stdin.read)
+    server.close()
+    await copilot.stop()
+    return 0
+
+
+def main(out: TextIO) -> int:
+    return asyncio.run(serve(out))

package/py/forgeqe_engine/dynamic.py

@@ -0,0 +1,149 @@
+"""
+Data that changes from one run to the next, in what a recording keeps: prices, dates, times, ids and order numbers,
+long numbers and counts in a sentence. A test that spells this run's value out fails on the next run, so the recorder
+keeps the parts that hold and makes the rest a pattern, a variable, or a value made fresh on each run.
+
+- ``parts(text)``: the spans of ``text`` that change, with their kind.
+- ``pattern_of(text)``: a regular expression (JavaScript and Python alike) that the text matches on any run: the stable
+  parts as they are, each changing part by its kind.
+- ``stable_part(text)``: the longest part that holds, for a locator that finds the element by it.
+- ``relative_date(text, today)``: a typed date as days from today, for ``{{$date:+N:FORMAT}}``.
+
+A small number on its own ("1" in a cart badge, "3" items) is not changing data: it is usually what the check is about.
+"""
+from __future__ import annotations
+
+import re
+from datetime import date, datetime, timedelta
+from typing import List, Optional, Tuple
+
+_MONTHS = "jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec|january|february|march|april|june|july|august|september|october|november|december"
+
+# (kind, what finds it, the pattern a test asserts instead). Order matters: the first kind to claim a span keeps it.
+_KINDS: List[Tuple[str, "re.Pattern[str]", str]] = [
+    ("uuid", re.compile(r"\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b", re.I), r"[0-9a-fA-F-]{36}"),
+    ("date", re.compile(r"\b\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2})?(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)?\b"), r"\d{4}-\d{2}-\d{2}(?:[T ][\d:.]+(?:Z|[+-][\d:]+)?)?"),
+    ("date", re.compile(r"\b\d{1,2}[/.]\d{1,2}[/.]\d{2,4}\b"), r"\d{1,2}[/.]\d{1,2}[/.]\d{2,4}"),
+    ("date", re.compile(rf"\b(?:\d{{1,2}}\s+(?:{_MONTHS})\.?,?\s+\d{{4}}|(?:{_MONTHS})\.?\s+\d{{1,2}},?\s+\d{{4}})\b", re.I), r"[\w.]+\s+[\w.]+,?\s+\d{4}"),
+    ("time", re.compile(r"\b\d{1,2}:\d{2}(?::\d{2})?\s?(?:[ap]\.?m\.?)?(?![\d:])", re.I), r"\d{1,2}:\d{2}(?::\d{2})?\s?(?:[aApP]\.?[mM]\.?)?"),
+    ("money", re.compile(r"(?:[$€£¥₹]\s?|\b(?:USD|EUR|GBP|INR|JPY|AUD|CAD)\s?)\d[\d,]*(?:\.\d{1,2})?\b|\b\d[\d,]*(?:\.\d{1,2})?\s?(?:USD|EUR|GBP|INR|JPY|AUD|CAD|€|£)", re.I), r"(?:[$€£¥₹]\s?|[A-Z]{3}\s?)?\d[\d,]*(?:\.\d{1,2})?(?:\s?(?:[A-Z]{3}|€|£))?"),
+    ("id", re.compile(r"(?<![\w-])(?=[A-Z0-9-]*\d)(?=[A-Z0-9-]*[A-Z])[A-Z0-9]{1,6}-[A-Z0-9]{2,}(?:-[A-Z0-9]+)*(?![\w-])"), r"[A-Z0-9]+(?:-[A-Z0-9]+)+"),
+    ("id", re.compile(r"#\d{3,}\b"), r"#\d+"),
+    ("id", re.compile(r"\b(?=[A-Za-z0-9]*\d)(?=[A-Za-z0-9]*[A-Za-z])[A-Za-z0-9]{10,}\b"), r"[A-Za-z0-9]{10,}"),
+    ("number", re.compile(r"\b\d{1,3}(?:,\d{3})+(?:\.\d+)?\b|\b\d{4,}(?:\.\d+)?\b|\b\d+\.\d+\b"), r"\d[\d,]*(?:\.\d+)?"),
+]
+# A count in a sentence: "2,463 properties found", "12 results", "3 items in your cart".
+_COUNT = re.compile(r"\b\d[\d,]*(?=\s+(?:results?|items?|products?|properties|matches|hits|records|rows|orders|reviews|comments|people|days|hours|minutes|seconds|left|available|found|in stock)\b)", re.I)
+_COUNT_PATTERN = r"\d[\d,]*"
+
+
+def _spans(text: str) -> List[Tuple[int, int, str, str]]:
+    """(start, end, kind, the pattern of the matcher that found it), in order."""
+    t = text or ""
+    found: List[Tuple[int, int, str, str]] = []
+
+    def free(a: int, b: int) -> bool:
+        return all(b <= s or a >= e for s, e, _, _ in found)
+
+    for kind, rx, pat in _KINDS:
+        for m in rx.finditer(t):
+            if free(m.start(), m.end()):
+                found.append((m.start(), m.end(), kind, pat))
+    for m in _COUNT.finditer(t):
+        if free(m.start(), m.end()):
+            found.append((m.start(), m.end(), "count", _COUNT_PATTERN))
+    return sorted(found)
+
+
+def parts(text: str) -> List[Tuple[int, int, str]]:
+    """The spans of `text` that change from run to run, in order, as (start, end, kind)."""
+    return [(s, e, k) for s, e, k, _ in _spans(text)]
+
+
+def is_dynamic(text: str) -> bool:
+    return bool(parts(text))
+
+
+def _token_pattern(kind: str, value: str, matched: str) -> str:
+    if kind == "date" and re.fullmatch(r"\d{4}-\d{2}-\d{2}", value):
+        return r"\d{4}-\d{2}-\d{2}"
+    if kind == "money":
+        # Keep the currency the run showed; the amount changes.
+        cur = re.match(r"^([$€£¥₹]|[A-Za-z]{3})\s?", value)
+        amount = r"\d[\d,]*(?:\.\d{1,2})?"
+        if cur:
+            return re.escape(cur.group(1)) + r"\s?" + amount
+        tail = re.search(r"\s?([A-Za-z]{3}|€|£)$", value)
+        return amount + (r"\s?" + re.escape(tail.group(1)) if tail else "")
+    return matched
+
+
+def pattern_of(text: str, anchored: bool = False) -> Optional[str]:
+    """A regular expression the text matches on any run, or None when nothing in it changes."""
+    t = " ".join((text or "").split())
+    spans = _spans(t)
+    if not spans:
+        return None
+    out, at = [], 0
+    for s, e, kind, matched in spans:
+        out.append(re.escape(t[at:s]).replace("\\ ", r"\s+"))
+        out.append(_token_pattern(kind, t[s:e], matched))
+        at = e
+    out.append(re.escape(t[at:]).replace("\\ ", r"\s+"))
+    body = "".join(out)
+    return f"^{body}$" if anchored else body
+
+
+def stable_part(text: str, min_len: int = 3) -> str:
+    """The longest stretch of `text` with nothing that changes in it, trimmed; "" when none is long enough."""
+    t = " ".join((text or "").split())
+    cuts, at = [], 0
+    for s, e, _ in parts(t):
+        cuts.append(t[at:s])
+        at = e
+    cuts.append(t[at:])
+    best = max((c.strip(" ,.:;|/-–·") for c in cuts), key=len, default="")
+    return best if len(best) >= min_len and re.search(r"[A-Za-z]", best) else ""
+
+
+def values(text: str) -> List[str]:
+    """The changing values in `text`, as shown ("$14.15", "A-1042")."""
+    t = " ".join((text or "").split())
+    return [t[s:e] for s, e, _ in parts(t)]
+
+
+_DATE_FORMATS = (("%Y-%m-%d", r"\d{4}-\d{2}-\d{2}"), ("%d/%m/%Y", r"\d{2}/\d{2}/\d{4}"), ("%m/%d/%Y", r"\d{2}/\d{2}/\d{4}"), ("%d.%m.%Y", r"\d{2}\.\d{2}\.\d{4}"))
+MAX_DATE_DAYS = 3660
+
+
+def relative_date(text: str, today: Optional[date] = None) -> Optional[str]:
+    """
+    A typed date, as ``{{$date:+N:FORMAT}}`` (N days from today) when it is the whole value and reads one way only;
+    None otherwise. 03/04/2026 could be either day-first or month-first: it is left as typed.
+    """
+    t = (text or "").strip()
+    today = today or date.today()
+    hits = []
+    for fmt, rx in _DATE_FORMATS:
+        if not re.fullmatch(rx, t):
+            continue
+        try:
+            hits.append((fmt, datetime.strptime(t, fmt).date()))
+        except ValueError:
+            continue
+    if len({d for _, d in hits}) != 1:
+        return None
+    fmt, d = hits[0]
+    days = (d - today).days
+    if abs(days) > MAX_DATE_DAYS:
+        return None
+    return "{{$date:%s%d:%s}}" % ("+" if days >= 0 else "-", abs(days), fmt)
+
+
+def date_from(template: str, today: Optional[date] = None) -> str:
+    """The date a ``{{$date:+N:FORMAT}}`` stands for today (for tests of this module and the replay's own)."""
+    m = re.fullmatch(r"\{\{\$date:([+-])(\d+):([^}]+)\}\}", template)
+    if not m:
+        return template
+    d = (today or date.today()) + timedelta(days=int(m.group(2)) * (1 if m.group(1) == "+" else -1))
+    return d.strftime(m.group(3))