ltcai 11.2.0 → 11.4.0

package/latticeai/core/file_generation/repair.py

@@ -0,0 +1,114 @@
+"""Deterministic scaffolds — step 5, the last resort after the retries.
+
+The user asked for a file, so the request must still end in a well-formed file
+of the target type, never an error. Nothing here calls a model: whatever the
+model did produce is salvaged where it can be, and honestly labelled where it
+cannot.
+"""
+
+from __future__ import annotations
+
+import ast
+import html as html_lib
+import json
+import re
+
+from .extraction import _ext, _slice_html_document, _slice_json_document
+from .validation import looks_like_refusal
+
+
+def repair_file_content(content: str, target_path: str, user_request: str) -> str:
+    """Turn whatever the model produced into a valid file of the target type.
+
+    This is the last resort after retries: the user asked for a file, so the
+    request must still end in a well-formed file, never an error.
+    """
+    ext = _ext(target_path)
+    salvage = content.strip()
+    if looks_like_refusal(salvage):
+        salvage = ""
+
+    if ext in (".html", ".htm"):
+        return _repair_html(salvage, user_request)
+    if ext == ".json":
+        sliced = _slice_json_document(salvage)
+        if sliced is not None:
+            return sliced
+        return json.dumps(
+            {"request": user_request, "content": salvage},
+            ensure_ascii=False,
+            indent=2,
+        )
+    if ext == ".py" and salvage:
+        # The repair guarantee for Python is parseability: unparseable output
+        # is preserved honestly as a commented-out draft, never as a broken
+        # module the user has to debug.
+        try:
+            ast.parse(salvage)
+            return salvage
+        except SyntaxError:
+            commented = "\n".join(f"# {line}" for line in salvage.splitlines())
+            return (
+                f"# TODO: model produced invalid Python for: {user_request}\n"
+                "# The draft below is preserved as comments — fix and uncomment.\n"
+                f"{commented}\n"
+            )
+    if salvage:
+        return salvage
+    # Nothing usable at all — leave an honest placeholder in the right format.
+    comment = {
+        ".py": "# TODO: model produced no usable content for: ",
+        ".js": "// TODO: model produced no usable content for: ",
+        ".jsx": "// TODO: model produced no usable content for: ",
+        ".ts": "// TODO: model produced no usable content for: ",
+        ".tsx": "// TODO: model produced no usable content for: ",
+        ".css": "/* TODO: model produced no usable content for: ",
+        ".sh": "# TODO: model produced no usable content for: ",
+        ".sql": "-- TODO: model produced no usable content for: ",
+    }.get(ext, "")
+    if ext == ".css":
+        return f"{comment}{user_request} */\n"
+    if comment:
+        return f"{comment}{user_request}\n"
+    return f"{user_request}\n"
+
+
+def _repair_html(salvage: str, user_request: str) -> str:
+    lower = salvage.lower()
+    if "<html" in lower or "<!doctype" in lower:
+        # A real document that is merely truncated — close it.
+        doc = _slice_html_document(salvage)
+        low = doc.lower()
+        if "</body>" not in low and "<body" in low:
+            doc += "\n</body>"
+        if "</html>" not in low:
+            doc += "\n</html>"
+        return doc
+    if re.search(r"<\w+[^>]*>", salvage):
+        body = salvage  # an HTML fragment — embed as-is
+    elif salvage:
+        body = "\n".join(
+            f"  <p>{html_lib.escape(line)}</p>"
+            for line in salvage.splitlines()
+            if line.strip()
+        )
+    else:
+        body = f"  <p>{html_lib.escape(user_request)}</p>"
+    title = html_lib.escape(user_request[:60] or "Generated page")
+    return (
+        "<!DOCTYPE html>\n"
+        "<html lang=\"ko\">\n"
+        "<head>\n"
+        "  <meta charset=\"utf-8\">\n"
+        "  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n"
+        f"  <title>{title}</title>\n"
+        "  <style>\n"
+        "    body { font-family: system-ui, sans-serif; margin: 2rem auto; "
+        "max-width: 720px; line-height: 1.6; padding: 0 1rem; }\n"
+        "  </style>\n"
+        "</head>\n"
+        "<body>\n"
+        f"{body}\n"
+        "</body>\n"
+        "</html>"
+    )

package/latticeai/core/file_generation/sanitize.py

@@ -0,0 +1,61 @@
+"""The single write-side guarantee for model-produced file content.
+
+``sanitize_write_content`` is the one door every write entry point goes
+through — the direct chat path, the agent JSON loop, the tools layer — so a
+fenced or chatty payload can never be persisted verbatim no matter which
+surface produced it.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Tuple
+
+from .extraction import extract_file_content
+from .repair import repair_file_content
+from .validation import validate_file_content
+
+# Extensions the Brain UI can render inline (preview) after creation.
+PREVIEWABLE_EXTENSIONS = frozenset({
+    ".html", ".htm", ".md", ".markdown", ".txt", ".json", ".css", ".js",
+    ".csv", ".py", ".yaml", ".yml", ".xml", ".sql", ".sh",
+    ".jsx", ".ts", ".tsx", ".vue", ".svelte",
+})
+
+
+def sanitize_write_content(
+    target_path: str,
+    content: Any,
+    user_request: str = "",
+) -> Tuple[str, Dict[str, Any]]:
+    """Single write-side guarantee for model-produced file content.
+
+    The direct chat path already runs the full generate→validate→repair
+    pipeline, but the agent JSON loop historically wrote ``args.content``
+    verbatim — weak models routinely put fenced/chatty payloads there. This
+    conservative sanitizer closes that gap for *any* write entry point:
+
+    1. content that already validates is returned byte-for-byte unchanged
+       (trusted/user-authored content is never mangled);
+    2. otherwise the extraction pass strips fences/think-blocks/chat noise
+       and is used only when the extracted payload validates;
+    3. otherwise deterministic repair guarantees a structurally valid file.
+
+    Empty content is left untouched (creating an empty file is a legitimate,
+    intentional action — e.g. ``__init__.py``). Returns ``(content, meta)``
+    where meta is ``{"sanitized": bool, "repaired": bool, "reason": str}``.
+    """
+    raw = str(content or "")
+    if not raw.strip():
+        return raw, {"sanitized": False, "repaired": False, "reason": "empty"}
+    ok, reason = validate_file_content(raw, target_path)
+    if ok:
+        return raw, {"sanitized": False, "repaired": False, "reason": "ok"}
+    extracted = extract_file_content(raw, target_path)
+    if extracted:
+        extracted_ok, _ = validate_file_content(extracted, target_path)
+        if extracted_ok:
+            return extracted, {"sanitized": True, "repaired": False, "reason": reason}
+    repaired = repair_file_content(
+        extracted or raw, target_path, user_request or f"content for {target_path}"
+    )
+    return repaired, {"sanitized": True, "repaired": True, "reason": reason}

package/latticeai/core/file_generation/validation.py

@@ -0,0 +1,201 @@
+"""Per-extension structural checks — step 3 of the pipeline.
+
+Answers one question about an already-extracted payload: *is this a file of the
+requested type?* HTML document shape, JSON parses, CSS has rule blocks, Python
+parses, braced code is balanced, components close their blocks — and, for prose
+types with no grammar to check, that the reply is not merely talk about the
+file.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import re
+from typing import List, Tuple
+
+from .extraction import _ext
+
+_REFUSAL_RE = re.compile(
+    r"(i can('|no)?t|i'?m (sorry|unable)|as an ai|cannot assist"
+    r"|죄송(하지만|합니다)|할 수 없|불가능합니다|도와드릴 수 없)",
+    re.IGNORECASE,
+)
+
+
+def looks_like_refusal(content: str) -> bool:
+    head = content[:300]
+    return bool(_REFUSAL_RE.search(head)) and len(content) < 600
+
+
+# Braced code types validated structurally (balanced delimiters, no fences).
+_BRACED_CODE_EXTENSIONS = frozenset({".js", ".jsx", ".ts", ".tsx"})
+# Single-file components validated by their block tags being closed.
+_COMPONENT_EXTENSIONS = frozenset({".vue", ".svelte"})
+
+
+def _strip_code_literals(text: str) -> str:
+    """Remove string literals and comments so delimiter counting stays honest.
+
+    A cheap single-pass scanner (not a parser): quotes ('', "", ``), line
+    comments (//) and block comments (/* */) commonly contain lone braces
+    that would otherwise false-flag valid JS/TS as unbalanced.
+    """
+    out: List[str] = []
+    i, n = 0, len(text)
+    while i < n:
+        ch = text[i]
+        nxt = text[i + 1] if i + 1 < n else ""
+        if ch == "\\":
+            i += 2  # escaped char (inside or outside a literal — always skip)
+            continue
+        if ch in ("'", '"', "`"):
+            quote = ch
+            i += 1
+            while i < n:
+                if text[i] == "\\":
+                    i += 2
+                    continue
+                if text[i] == quote:
+                    i += 1
+                    break
+                i += 1
+            continue
+        if ch == "/" and nxt == "/":
+            while i < n and text[i] != "\n":
+                i += 1
+            continue
+        if ch == "/" and nxt == "*":
+            end = text.find("*/", i + 2)
+            i = n if end < 0 else end + 2
+            continue
+        out.append(ch)
+        i += 1
+    return "".join(out)
+
+
+def _check_balanced_delimiters(content: str) -> Tuple[bool, str]:
+    """Lenient count-based balance check for braced code (js/ts family).
+
+    Only *counts* are compared, never ordering, so valid-but-unusual code is
+    not rejected; a truncated file with a dangling ``{`` still fails.
+    """
+    stripped = _strip_code_literals(content)
+    for opener, closer, label in (("{", "}", "braces"), ("(", ")", "parentheses"), ("[", "]", "brackets")):
+        if stripped.count(opener) != stripped.count(closer):
+            return False, f"unbalanced {label} ({opener}{closer}) — the file looks truncated"
+    return True, "ok"
+
+
+def _check_component_blocks(content: str) -> Tuple[bool, str]:
+    """Vue/Svelte SFC sanity: every opened block tag must be closed."""
+    lower = content.lower()
+    for tag in ("template", "script", "style"):
+        opened = len(re.findall(rf"<{tag}(?:\s[^>]*)?>", lower))
+        closed = lower.count(f"</{tag}>")
+        if opened != closed:
+            return False, f"<{tag}> block is not closed — the component looks truncated"
+    return True, "ok"
+
+
+def validate_file_content(content: str, target_path: str) -> Tuple[bool, str]:
+    """Structural sanity check per file type. Returns (ok, reason)."""
+    if not content.strip():
+        return False, "empty output"
+    if looks_like_refusal(content):
+        return False, "the reply was a refusal/chat message, not file content"
+
+    ext = _ext(target_path)
+    if ext in (".html", ".htm"):
+        lower = content.lower()
+        if "<html" not in lower and "<!doctype" not in lower:
+            return False, "not a complete HTML document (missing <!DOCTYPE html>/<html>)"
+        if "</html>" not in lower:
+            return False, "HTML document is truncated (missing </html>)"
+        # A document that merely *contains* html somewhere is not a valid
+        # file payload: fenced/chat-wrapped replies must fail here so the
+        # extraction pass gets a chance to slice out the real document.
+        stripped = content.lstrip()
+        if not (stripped.lower().startswith("<!doctype") or stripped.lower().startswith("<html")):
+            return False, "HTML document is wrapped in prose or fences"
+        if "```" in content:
+            return False, "output still contains Markdown fences"
+        return True, "ok"
+    if ext == ".json":
+        try:
+            json.loads(content)
+        except (ValueError, TypeError) as exc:
+            return False, f"invalid JSON: {exc}"
+        return True, "ok"
+    if ext == ".css":
+        if "```" in content:
+            return False, "output still contains Markdown fences"
+        if "{" not in content or "}" not in content:
+            return False, "no CSS rule blocks found"
+        return True, "ok"
+    if ext == ".py":
+        if "```" in content:
+            return False, "output still contains Markdown fences"
+        try:
+            ast.parse(content)
+        except SyntaxError as exc:
+            return False, f"invalid Python syntax: {exc.msg} (line {exc.lineno})"
+        return True, "ok"
+    if ext in _BRACED_CODE_EXTENSIONS:
+        if "```" in content:
+            return False, "output still contains Markdown fences"
+        return _check_balanced_delimiters(content)
+    if ext in _COMPONENT_EXTENSIONS:
+        if "```" in content:
+            return False, "output still contains Markdown fences"
+        return _check_component_blocks(content)
+    if ext in (".sh", ".sql"):
+        if "```" in content:
+            return False, "output still contains Markdown fences"
+        return True, "ok"
+    # Prose types (.md, .txt, .csv, …) have no grammar to check, which used to
+    # mean *nothing* was checked: a 1–4B model that answered "Sure! Here is the
+    # document you asked for:" and stopped had its sentence saved as the file,
+    # because the fence stripper only removes conversational lines it can
+    # recognise and the length guard on `looks_like_refusal` lets a wordy
+    # refusal through. The two checks below are the only ones that generalise
+    # without inventing a grammar: it must not still be wearing fences, and it
+    # must not be *only* an answer about the file.
+    if "```" in content:
+        return False, "output still contains Markdown fences"
+    if _looks_like_commentary(content):
+        return False, "the reply talks about the file instead of being the file"
+    return True, "ok"
+
+
+# Openers that mean "I am about to give you the thing" — if the whole reply is
+# one of these, the thing never arrived.
+_COMMENTARY_RE = re.compile(
+    r"^\s*("
+    r"(sure|of course|certainly|okay|ok|alright|here|below|the following)\b"
+    r"|i('ve| have| will|'ll)\b"
+    r"|(물론|네[,!. ]|알겠|다음은|아래(는|의)?|요청하신|원하시는)"
+    r")",
+    re.IGNORECASE,
+)
+
+
+def _looks_like_commentary(content: str) -> bool:
+    """True when the reply reads as an answer *about* a file, not the file.
+
+    Deliberately conservative — a long document that merely opens with "The
+    following" is a document. Only a short reply that both opens
+    conversationally and never grows into content is rejected, so a real file
+    is never thrown away to catch a chat line.
+    """
+    stripped = content.strip()
+    if len(stripped) > 400:
+        return False
+    if not _COMMENTARY_RE.match(stripped):
+        return False
+    # Structure means content arrived after the preamble: a heading, a list, a
+    # table row, a delimiter, or simply several lines of body text.
+    body = stripped.split("\n", 1)[1].strip() if "\n" in stripped else ""
+    if re.search(r"^\s*(#{1,6}\s|[-*+]\s|\d+[.)]\s|\||>)", body, re.MULTILINE):
+        return False
+    return len(body) < 120

package/latticeai/core/legacy_compatibility.py

@@ -13,7 +13,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Dict, List
 
-LEGACY_COMPATIBILITY_VERSION = "11.2.0"
+LEGACY_COMPATIBILITY_VERSION = "11.4.0"
 
 
 @dataclass(frozen=True)

package/latticeai/core/marketplace.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 from copy import deepcopy
 from typing import Any, Dict, List, Optional
 
-MARKETPLACE_VERSION = "11.2.0"
+MARKETPLACE_VERSION = "11.4.0"
 TEMPLATE_KINDS = ("plugin", "workflow", "agent", "ingestion_bridge")
 
 

package/latticeai/core/messages.py

@@ -522,6 +522,15 @@ MESSAGES: Dict[str, Dict[str, str]] = {
         "ko": "디렉터리를 찾을 수 없습니다.",
         "en": "That directory was not found.",
     },
+    # ── chronicle ───────────────────────────────────────────────────────
+    "chronicle.bad_date": {
+        "ko": "날짜를 읽을 수 없습니다. 2026-08-11 처럼 연-월-일로 적어 주세요.",
+        "en": "That date could not be read. Write it as year-month-day, like 2026-08-11.",
+    },
+    "chronicle.bad_timestamp": {
+        "ko": "시점을 읽을 수 없습니다. 2026-08-11T09:00:00 처럼 적어 주세요.",
+        "en": "That moment could not be read. Write it like 2026-08-11T09:00:00.",
+    },
     # ── MCP / setup ─────────────────────────────────────────────────────
     "mcp.connector_not_found": {
         "ko": "커넥터를 찾을 수 없습니다.",

package/latticeai/core/workspace_os_constants.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 from typing import Dict
 
-WORKSPACE_OS_VERSION = "11.2.0"
+WORKSPACE_OS_VERSION = "11.4.0"
 
 # Workspace types separate single-user Personal workspaces from shared
 # Organization workspaces. Both keep the same local-first JSON store; the type

package/latticeai/integrations/telegram_bot/__init__.py

@@ -0,0 +1,123 @@
+"""Telegram bridge — the phone-side surface of a local Lattice AI.
+
+The bot mirrors the web app's capabilities onto a chat: server status, models,
+Knowledge Graph counts, screenshots, history, document capture, the Review
+Center, and the full human-in-the-loop agent handshake. It is fail-closed by
+construction — no bot token, no chat allowlist, or no explicitly provisioned
+server capability and the loop refuses to start.
+
+Split into cohesive submodules in v11.3.0 (no behaviour change): ``config``
+(environment, endpoints, logger and the authenticated server client),
+``helpers`` (chat-id registry, Telegram API, network, agent artifacts),
+``screens`` (the menu commands that report on the running system), ``flows``
+(ask → render → approve, including the pending-plan state), and ``dispatch``
+(command/callback routing and the poll loop). ``__main__`` keeps
+``python -m latticeai.integrations.telegram_bot`` working. This module
+re-exports every name the single file exposed, so
+``latticeai.integrations.telegram_bot.X`` keeps working.
+
+Stubbing note: rebinding one of these *here* changes only this module's name.
+The submodule that calls it holds its own reference, so a test standing in for
+``CHAT_IDS_FILE``/``TOKEN``/``AGENT_WORKSPACE`` patches
+``…telegram_bot.helpers``, for ``_server_client``/``_bot_pending_plans``
+``…telegram_bot.flows`` (or ``…screens`` for a screen), and for ``get_updates``
+``…telegram_bot.dispatch``.
+"""
+
+# The single file had no ``__all__``, so its public surface was "every module
+# global" — including the names it imported for its own use. Every re-export
+# below therefore uses the redundant-alias form: it reproduces exactly that
+# surface, and it marks each name as deliberate rather than a leftover import.
+from latticeai.cli.runtime import _load_env_file as _load_env_file
+from latticeai.core.io_utils import atomic_write_json as atomic_write_json
+from latticeai.core.logging_safety import (
+    install_sensitive_log_filter as install_sensitive_log_filter,
+)
+from latticeai.core.logging_safety import safe_log_text as safe_log_text
+from latticeai.core.quiet import quiet as quiet
+
+from .config import AGENT_RESUME_URL as AGENT_RESUME_URL
+from .config import AGENT_URL as AGENT_URL
+from .config import AGENT_WORKSPACE as AGENT_WORKSPACE
+from .config import API_URL as API_URL
+from .config import BASE_URL as BASE_URL
+from .config import CHAT_IDS_FILE as CHAT_IDS_FILE
+from .config import CHAT_URL as CHAT_URL
+from .config import DATA_DIR as DATA_DIR
+from .config import GRAPH_STATS_URL as GRAPH_STATS_URL
+from .config import HISTORY_URL as HISTORY_URL
+from .config import INVITE_CODE as INVITE_CODE
+from .config import MAX_TELEGRAM_FILE_BYTES as MAX_TELEGRAM_FILE_BYTES
+from .config import MCP_TOOLS_URL as MCP_TOOLS_URL
+from .config import MODELS_URL as MODELS_URL
+from .config import PROPOSALS_URL as PROPOSALS_URL
+from .config import PUBLIC_WEB_URL as PUBLIC_WEB_URL
+from .config import SERVER_PORT as SERVER_PORT
+from .config import STATUS_URL as STATUS_URL
+from .config import TOKEN as TOKEN
+from .config import UPLOAD_DOC_URL as UPLOAD_DOC_URL
+from .config import _get_server_session as _get_server_session
+from .config import _server_client as _server_client
+from .config import env_value as env_value
+from .config import load_env_file as load_env_file
+from .config import logger as logger
+from .dispatch import HELP_TEXT as HELP_TEXT
+from .dispatch import _log_task_exception as _log_task_exception
+from .dispatch import handle_callback_query as handle_callback_query
+from .dispatch import handle_command as handle_command
+from .dispatch import run_bot as run_bot
+from .flows import _approval_pause_id as _approval_pause_id
+from .flows import _bot_pending_plans as _bot_pending_plans
+from .flows import _is_approval_pause as _is_approval_pause
+from .flows import _resume_payload as _resume_payload
+from .flows import ask_ai as ask_ai
+from .flows import format_artifact_card as format_artifact_card
+from .flows import format_grounding_badge as format_grounding_badge
+from .flows import format_proposals as format_proposals
+from .flows import format_run_explanation as format_run_explanation
+from .flows import handle_plan_callback as handle_plan_callback
+from .flows import handle_proposal_callback as handle_proposal_callback
+from .flows import process_ai_request as process_ai_request
+from .flows import send_artifact_card as send_artifact_card
+from .flows import send_grounding_badge as send_grounding_badge
+from .flows import send_plan_for_approval as send_plan_for_approval
+from .flows import send_run_explanation as send_run_explanation
+from .flows import show_review_center as show_review_center
+from .helpers import allowed_chat_ids as allowed_chat_ids
+from .helpers import answer_callback as answer_callback
+from .helpers import broadcast_web_chat as broadcast_web_chat
+from .helpers import collect_generated_files as collect_generated_files
+from .helpers import collect_preview_urls as collect_preview_urls
+from .helpers import download_as_base64 as download_as_base64
+from .helpers import download_telegram_file as download_telegram_file
+from .helpers import edit_message as edit_message
+from .helpers import get_graph_url as get_graph_url
+from .helpers import get_lan_ip as get_lan_ip
+from .helpers import get_updates as get_updates
+from .helpers import get_web_url as get_web_url
+from .helpers import is_chat_allowed as is_chat_allowed
+from .helpers import load_chat_ids as load_chat_ids
+from .helpers import parse_allowed_chat_ids as parse_allowed_chat_ids
+from .helpers import register_chat_id as register_chat_id
+from .helpers import resolve_workspace_file as resolve_workspace_file
+from .helpers import save_chat_ids as save_chat_ids
+from .helpers import send_chat_action as send_chat_action
+from .helpers import send_document as send_document
+from .helpers import send_generated_files as send_generated_files
+from .helpers import send_message as send_message
+from .helpers import send_photo as send_photo
+from .helpers import send_preview_links as send_preview_links
+from .screens import MAIN_MENU as MAIN_MENU
+from .screens import _mac_ram_used_gb as _mac_ram_used_gb
+from .screens import _unload_all_report as _unload_all_report
+from .screens import clear_server_history as clear_server_history
+from .screens import do_unload_model as do_unload_model
+from .screens import process_document_file as process_document_file
+from .screens import send_mcp_tools as send_mcp_tools
+from .screens import send_web_link as send_web_link
+from .screens import show_graph_stats as show_graph_stats
+from .screens import show_history_summary as show_history_summary
+from .screens import show_menu as show_menu
+from .screens import show_model_info as show_model_info
+from .screens import show_status as show_status
+from .screens import take_screenshot as take_screenshot

package/latticeai/integrations/telegram_bot/__main__.py

@@ -0,0 +1,17 @@
+"""Script entry: ``python -m latticeai.integrations.telegram_bot``.
+
+The single file carried this block under ``if __name__ == "__main__"``. A
+package cannot: ``__init__`` is never ``__main__``. Moving it here verbatim is
+what keeps the ``-m`` invocation working after the v11.3.0 split.
+"""
+
+import asyncio
+
+from latticeai.core.quiet import quiet
+from latticeai.integrations.telegram_bot import run_bot
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(run_bot())
+    except KeyboardInterrupt:
+        quiet()

package/latticeai/integrations/telegram_bot/config.py

@@ -0,0 +1,86 @@
+"""Environment, endpoints, logger, and the bot's server capability.
+
+Every value the bridge reads from the environment is resolved here, once, at
+import — the module *is* the bot's configuration surface. Importing it has the
+same side effects the single file had at its own import: the sensitive-log
+filter is installed, ``.env`` is loaded, and the data directory is provisioned.
+
+Security boundary (unchanged since 11.0.1): :func:`_server_client` is the only
+authenticated client. It carries the explicitly provisioned bot-to-server
+bearer capability and is used for Lattice-server calls alone — never for
+api.telegram.org, which always gets the plain ``httpx.AsyncClient`` the poll
+loop owns.
+
+Stubbing note: a constant is read through the globals of the module that *uses*
+it, so a test standing in for ``TOKEN``/``CHAT_IDS_FILE``/``AGENT_WORKSPACE``
+patches ``helpers``/``screens``/``flows``/``dispatch``, not this module.
+"""
+
+import logging
+import os
+from pathlib import Path
+
+import httpx
+
+from latticeai.cli.runtime import _load_env_file
+from latticeai.core.logging_safety import install_sensitive_log_filter
+
+install_sensitive_log_filter()
+
+def load_env_file(path=".env"):
+    # Single source of truth: shared with ltcai_cli via latticeai.cli.runtime.
+    _load_env_file(Path(path))
+
+load_env_file()
+
+def env_value(primary: str, default: str = "") -> str:
+    return os.getenv(primary) or default
+
+TOKEN          = env_value("LATTICEAI_TELEGRAM_BOT_TOKEN")
+API_URL        = f"https://api.telegram.org/bot{TOKEN}"
+SERVER_PORT    = int(env_value("LATTICEAI_SERVER_PORT", "4825"))
+BASE_URL       = env_value("LATTICEAI_BASE_URL", env_value("LATTICEAI_SERVER_URL", f"http://127.0.0.1:{SERVER_PORT}")).rstrip("/")
+CHAT_URL       = f"{BASE_URL}/chat"
+AGENT_URL      = f"{BASE_URL}/agent"
+MCP_TOOLS_URL  = f"{BASE_URL}/mcp/tools"
+HISTORY_URL    = f"{BASE_URL}/history"
+STATUS_URL     = f"{BASE_URL}/status"
+MODELS_URL     = f"{BASE_URL}/models"
+GRAPH_STATS_URL = f"{BASE_URL}/knowledge-graph/stats"
+UPLOAD_DOC_URL  = f"{BASE_URL}/upload/document"
+PROPOSALS_URL   = f"{BASE_URL}/api/proposals"
+
+AGENT_RESUME_URL      = f"{BASE_URL}/agent/resume"
+AGENT_WORKSPACE       = Path(env_value("LATTICEAI_AGENT_ROOT", "agent_workspace")).resolve()
+
+MAX_TELEGRAM_FILE_BYTES = 45 * 1024 * 1024
+INVITE_CODE           = env_value("LATTICEAI_INVITE_CODE")
+PUBLIC_WEB_URL        = env_value("LATTICEAI_PUBLIC_URL")
+DATA_DIR              = Path(env_value("LATTICEAI_DATA_DIR", str(Path.home() / ".ltcai")))
+DATA_DIR.mkdir(parents=True, exist_ok=True)
+CHAT_IDS_FILE = Path(env_value("LATTICEAI_TELEGRAM_CHATS_FILE", str(DATA_DIR / "telegram_chats.json")))
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# ── Server session auth ───────────────────────────────────────────────────────
+
+def _get_server_session() -> str:
+    """Return only the explicitly provisioned bot-to-server token.
+
+    Web sessions are hashed at rest and belong to interactive users. Scanning
+    ``sessions.json`` cannot recover a usable token and would couple the bot to
+    whichever administrator happened to be logged in most recently.
+    """
+    return env_value("LATTICEAI_SERVER_SESSION_TOKEN").strip()
+
+def _server_client(**kwargs) -> httpx.AsyncClient:
+    """Return a server client authenticated by an explicit bearer capability."""
+    token = _get_server_session()
+    if not token:
+        raise RuntimeError(
+            "LATTICEAI_SERVER_SESSION_TOKEN is required for Telegram server API calls."
+        )
+    headers = dict(kwargs.pop("headers", {}) or {})
+    headers["Authorization"] = f"Bearer {token}"
+    return httpx.AsyncClient(headers=headers, **kwargs)