ltcai 11.1.0 → 11.4.0

package/lattice_brain/runtime/__init__.py

@@ -44,7 +44,7 @@ orchestrator, and the agent runtime service. Lazy-loaded so importing
     /agents/api/runtime/* , POST /agents (start via runtime.start or executor)
   api/chat.py
     from latticeai.services.tool_dispatch import build_agent_runtime
-    -> latticeai/core/agent.py:SingleAgentRuntime (별도 state/plan/transcript 머신, single-agent /agent 경로. dispatch_tool 만 공유)
+    -> latticeai/core/agent/:SingleAgentRuntime (별도 state/plan/transcript 머신, single-agent /agent 경로. dispatch_tool 만 공유)
   latticeai/services/tool_dispatch.py:14
     from latticeai.core.agent import SingleAgentRuntime
     (tool governance + core single-agent용)

package/lattice_brain/runtime/multi_agent.py

@@ -49,7 +49,7 @@ from typing import Any, Callable, Dict, List, Optional
 from ..utils import now_iso as _now
 from .contracts import multi_agent_contract
 
-MULTI_AGENT_VERSION = "11.1.0"
+MULTI_AGENT_VERSION = "11.4.0"
 
 AGENT_ROLES = ("researcher", "planner", "executor", "reviewer", "release")
 CORE_PIPELINE = ("planner", "executor", "reviewer")

package/lattice_brain/sealed_box.py

@@ -0,0 +1,244 @@
+"""Sealing a bundle to a recipient's public key (v11.2.0).
+
+Through 11.1.0 a shared subgraph was encrypted with a passphrase, which means
+the sender and the receiver must first agree on a secret over some *other*
+channel — and whatever that channel is, the passphrase is now in it. This
+module removes that step: the receiver publishes an X25519 public key, the
+sender seals a bundle to it, and only the holder of the matching private key
+can open it. Nothing secret ever travels.
+
+The construction is the standard sealed box, assembled from primitives
+``cryptography`` already ships (it is a core dependency; nothing new is added):
+
+1. the sender generates a **single-use ephemeral X25519 keypair**;
+2. ``ephemeral_private × recipient_public`` yields a shared secret only the two
+   of them can compute;
+3. **HKDF-SHA256** stretches that secret into a 256-bit key, with both public
+   keys mixed into ``info`` so a key derived for one recipient can never be
+   reused for another;
+4. **AES-256-GCM** encrypts the payload under it.
+
+Forward secrecy comes free: the ephemeral private key is discarded the moment
+the box is sealed, so a later compromise of the recipient's long-term key still
+does not decrypt an already-sent bundle — nothing else in the envelope can
+reconstruct the shared secret.
+
+The sender's Ed25519 signature over the bundle header is **untouched** by all
+of this. Signing says who wrote it; sealing says who may read it. Collapsing
+the two into one keypair is the usual way to end up with neither.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric.x25519 import (
+    X25519PrivateKey,
+    X25519PublicKey,
+)
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+#: Named in the envelope so a future construction can be told apart from this
+#: one instead of being silently mis-decrypted.
+SEALED_BOX_ALGORITHM = "x25519-hkdf-sha256-aes256gcm"
+#: Domain separation for the KDF — this key schedule is for subgraph bundles
+#: and nothing else.
+HKDF_INFO_PREFIX = b"latticeai.subgraph.sealed-box.v1"
+KEY_BYTES = 32
+NONCE_BYTES = 12
+SALT_BYTES = 16
+#: Filename of the recipient key under the data directory (0600, like the
+#: device identity's key file).
+RECIPIENT_KEY_FILENAME = "subgraph_recipient.key"
+
+
+def _b64(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=")
+
+
+def _unb64(text: str) -> bytes:
+    padded = str(text) + "=" * (-len(str(text)) % 4)
+    return base64.urlsafe_b64decode(padded.encode("ascii"))
+
+
+def _raw_public(key: X25519PublicKey) -> bytes:
+    return key.public_bytes(
+        serialization.Encoding.Raw, serialization.PublicFormat.Raw
+    )
+
+
+def public_key_fingerprint(public_key_b64: str) -> str:
+    """Human-comparable fingerprint of an X25519 public key.
+
+    Raises ``ValueError`` when the input is not a usable key — callers use this
+    as the validation gate before sealing anything to a pasted string.
+    """
+    try:
+        raw = _unb64(public_key_b64)
+        X25519PublicKey.from_public_bytes(raw)
+    except Exception as exc:  # noqa: BLE001 — any parse failure is one answer
+        raise ValueError(f"not a valid X25519 public key: {exc}") from exc
+    digest = hashlib.sha256(raw).hexdigest()
+    return ":".join(digest[i : i + 4] for i in range(0, 16, 4))
+
+
+def _derive(shared: bytes, salt: bytes, ephemeral: bytes, recipient: bytes) -> bytes:
+    return HKDF(
+        algorithm=hashes.SHA256(),
+        length=KEY_BYTES,
+        salt=salt,
+        info=HKDF_INFO_PREFIX + b"|" + ephemeral + b"|" + recipient,
+    ).derive(shared)
+
+
+def seal(plaintext: bytes, *, recipient_public_key: str) -> Dict[str, Any]:
+    """Encrypt ``plaintext`` so only the recipient's private key can open it.
+
+    Returns the JSON-safe crypto block that goes in the bundle envelope. The
+    recipient's own public key is echoed back into it so a receiver holding
+    several keys can tell at a glance whether this box was meant for them —
+    without trying to decrypt it, and without the sender having to be asked.
+    """
+    try:
+        recipient_raw = _unb64(recipient_public_key)
+        peer = X25519PublicKey.from_public_bytes(recipient_raw)
+    except Exception as exc:  # noqa: BLE001 — a bad key is a caller error, said plainly
+        raise ValueError(f"not a valid X25519 public key: {exc}") from exc
+    ephemeral = X25519PrivateKey.generate()
+    ephemeral_raw = _raw_public(ephemeral.public_key())
+    salt = os.urandom(SALT_BYTES)
+    nonce = os.urandom(NONCE_BYTES)
+    key = _derive(ephemeral.exchange(peer), salt, ephemeral_raw, recipient_raw)
+    ciphertext = AESGCM(key).encrypt(nonce, plaintext, None)
+    return {
+        "algorithm": SEALED_BOX_ALGORITHM,
+        "ephemeral_public_key": _b64(ephemeral_raw),
+        "recipient_public_key": _b64(recipient_raw),
+        "recipient_fingerprint": public_key_fingerprint(recipient_public_key),
+        "salt": _b64(salt),
+        "nonce": _b64(nonce),
+        "ciphertext": _b64(ciphertext),
+    }
+
+
+def unseal(block: Dict[str, Any], private_key: X25519PrivateKey) -> bytes:
+    """Open a sealed box with the recipient's private key.
+
+    Fail-closed and specific: an unknown algorithm, a missing field, a box
+    addressed to a different key, and a failed tag check each say which one
+    happened rather than collapsing into "decryption failed".
+    """
+    algorithm = str((block or {}).get("algorithm") or "")
+    if algorithm != SEALED_BOX_ALGORITHM:
+        raise ValueError(
+            f"unsupported sealed-box algorithm: {algorithm or 'missing'}"
+        )
+    try:
+        ephemeral_raw = _unb64(block["ephemeral_public_key"])
+        salt = _unb64(block["salt"])
+        nonce = _unb64(block["nonce"])
+        ciphertext = _unb64(block["ciphertext"])
+        peer = X25519PublicKey.from_public_bytes(ephemeral_raw)
+    except Exception as exc:  # noqa: BLE001 — a malformed envelope is one answer
+        raise ValueError(f"sealed bundle is missing encryption metadata: {exc}") from exc
+    recipient_raw = _raw_public(private_key.public_key())
+    addressed = str(block.get("recipient_public_key") or "")
+    if addressed and _unb64(addressed) != recipient_raw:
+        raise ValueError(
+            "this bundle was sealed to a different recipient key "
+            f"({block.get('recipient_fingerprint') or 'unknown fingerprint'})."
+        )
+    key = _derive(private_key.exchange(peer), salt, ephemeral_raw, recipient_raw)
+    try:
+        return bytes(AESGCM(key).decrypt(nonce, ciphertext, None))
+    except InvalidTag as exc:
+        raise ValueError(
+            "Sealed bundle decryption failed; the recipient key or the bundle is invalid."
+        ) from exc
+
+
+class RecipientIdentity:
+    """This Brain's X25519 receiving keypair — loads or creates, file-backed.
+
+    Deliberately *not* the device's Ed25519 identity. That key signs, and a
+    signing key that also decrypts is a key whose compromise costs twice. The
+    private half lives in a 0600 file under the data directory and never leaves
+    the machine; :meth:`describe` reports exactly that rather than implying a
+    keychain this class does not use.
+    """
+
+    def __init__(self, data_dir: Any) -> None:
+        self._data_dir = Path(data_dir)
+        self._key_file = self._data_dir / RECIPIENT_KEY_FILENAME
+        self._private = self._load_or_create()
+
+    def _load_or_create(self) -> X25519PrivateKey:
+        if self._key_file.exists():
+            return X25519PrivateKey.from_private_bytes(
+                _unb64(self._key_file.read_text(encoding="utf-8").strip())
+            )
+        key = X25519PrivateKey.generate()
+        raw = key.private_bytes(
+            serialization.Encoding.Raw,
+            serialization.PrivateFormat.Raw,
+            serialization.NoEncryption(),
+        )
+        self._data_dir.mkdir(parents=True, exist_ok=True)
+        self._key_file.write_text(_b64(raw), encoding="utf-8")
+        os.chmod(self._key_file, 0o600)
+        return key
+
+    @property
+    def public_key_b64(self) -> str:
+        return _b64(_raw_public(self._private.public_key()))
+
+    @property
+    def fingerprint(self) -> str:
+        return public_key_fingerprint(self.public_key_b64)
+
+    def describe(self) -> Dict[str, Any]:
+        return {
+            "public_key": self.public_key_b64,
+            "fingerprint": self.fingerprint,
+            "algorithm": SEALED_BOX_ALGORITHM,
+            "storage": "file",
+            "path": str(self._key_file),
+        }
+
+    def seal_to_self(self, plaintext: bytes) -> Dict[str, Any]:
+        """Seal to this Brain's own key — the honest way to test a round trip."""
+        return seal(plaintext, recipient_public_key=self.public_key_b64)
+
+    def unseal(self, block: Dict[str, Any]) -> bytes:
+        return unseal(block, self._private)
+
+
+def load_recipient_identity(data_dir: Any) -> Optional[RecipientIdentity]:
+    """Best-effort recipient key, or ``None`` when the directory is unusable.
+
+    Sharing is opt-in and a missing key is a *state*, not a crash: the status
+    surface reports "no receiving key" rather than failing a status read.
+    """
+    try:
+        return RecipientIdentity(data_dir)
+    except (OSError, ValueError):  # noqa: BLE001 — unwritable dir / corrupt key file
+        return None
+
+
+__all__ = [
+    "HKDF_INFO_PREFIX",
+    "RECIPIENT_KEY_FILENAME",
+    "SEALED_BOX_ALGORITHM",
+    "RecipientIdentity",
+    "load_recipient_identity",
+    "public_key_fingerprint",
+    "seal",
+    "unseal",
+]

package/lattice_brain/synthesis.py

@@ -35,6 +35,7 @@ import os
 from datetime import datetime, timezone
 from typing import Any, Callable, Dict, List, Optional, Sequence, Set, Tuple
 
+from .gates import FeatureGate
 from .graph.proactive import ProactiveBrain
 from .graph.schema import KGStoreV2
 from .quality import content_signature
@@ -60,6 +61,19 @@ CONTRADICTION_RESOLUTIONS = ("keep_old", "replace", "keep_both_temporal")
 SYNTHESIS_THRESHOLD_ENV = "LATTICEAI_SYNTHESIS_THRESHOLD"
 DEFAULT_SYNTHESIS_THRESHOLD = 25
 
+#: Whether the Brain is allowed to start a pass *by itself*. Default on — this
+#: is the behaviour 11.1.0 shipped — and it governs only the automatic path
+#: (:meth:`BrainSynthesizer.run_if_due`). An explicit run a person asked for is
+#: never gated: turning "tidy up on its own" off means the Brain stops deciding
+#: when, not that the button stops working.
+SYNTHESIS_ENV = "LATTICEAI_SYNTHESIS"
+SYNTHESIS_GATE = FeatureGate(
+    SYNTHESIS_ENV,
+    default=True,
+    name="synthesis",
+    detail="The Brain reviews accumulated material on its own and proposes tidy-ups.",
+)
+
 _MIN_SHARED_TOKENS = 3
 _MIN_CLUSTER_MEMBERS = 3
 _EDGE_SIMILARITY = 0.35
@@ -516,7 +530,14 @@ class BrainSynthesizer:
         self, result: Any, *, workspace_id: Optional[str] = None,
         user_email: Optional[str] = None,
     ) -> Optional[Dict[str, Any]]:
-        """Run synthesis only when this ingest pushed the counter over."""
+        """Run synthesis only when this ingest pushed the counter over.
+
+        The gate is checked *before* the counter moves, so "off" means off: a
+        long import while the switch is down does not bank a pass that fires the
+        instant someone turns it back on.
+        """
+        if not SYNTHESIS_GATE.enabled():
+            return None
         if not self.observe_ingest(result):
             return None
         return self.run(workspace_id=workspace_id, user_email=user_email)
@@ -792,6 +813,8 @@ __all__ = [
     "ContradictionResolutionError",
     "EDGE_KIND",
     "ProposalDesk",
+    "SYNTHESIS_ENV",
+    "SYNTHESIS_GATE",
     "SYNTHESIS_REVIEW_SOURCE",
     "SYNTHESIS_THRESHOLD_ENV",
     "SynthesisTrigger",

package/latticeai/__init__.py

@@ -1,3 +1,3 @@
 """Lattice AI - modular server package."""
 
-__version__ = "11.1.0"
+__version__ = "11.4.0"

package/latticeai/api/brain_intelligence.py

@@ -85,6 +85,10 @@ def create_brain_intelligence_router(
         Fixed contract consumed by the frontend:
         ``{"status": "ready"|"pending"|"unavailable", "pending_items": int,
         "total_items": int, "detail": str}``.
+
+        Additive since v11.2.0: ``breakdown`` splits the backlog into
+        ``embedded``/``missing``/``stale``/``queued`` when the store can. The
+        four keys above are unchanged, so existing readers see no difference.
         """
         user = require_user(request)
         scope = gate_read(request)

package/latticeai/api/chat.py

@@ -111,6 +111,16 @@ def create_chat_router(context: AppContext) -> APIRouter:
         get_history_user=context.require("get_history_user"),
     )
 
+    def review_sink() -> object:
+        """The Review Center queue, resolved per request (may be absent).
+
+        Cloud-derived knowledge is staged here rather than written, so the
+        hybrid turn needs the live queue — which is wired after this router's
+        context is built, hence a provider rather than a captured value.
+        """
+        provider = context.review_queue
+        return None if provider is None else provider()
+
     def notify_chat_message(role: str, text: str, source: Optional[str]) -> None:
         """Mirror persisted web exchanges to an injected bridge, never echoing it."""
         if context.on_chat_message is None or source == "telegram":
@@ -445,6 +455,7 @@ def create_chat_router(context: AppContext) -> APIRouter:
             chat_service=chat_service,
             notify=notify_chat_message,
             model_id=selected_model_id,
+            review_queue=review_sink(),
         )
         if hybrid_response is not None:
             return hybrid_response

package/latticeai/api/chat_helpers.py

@@ -212,8 +212,17 @@ def build_context_quality(
     lexical-only, or when retrieval failed entirely — so the frontend can
     tell the user the answer is weakly grounded instead of implying rich
     graph context. Never raises.
+
+    A fifth key, ``multimodal``, appears only when the matches really include
+    picture nodes (v11.2.0). "6 nodes" reads differently when two of them are
+    screenshots whose text came out of OCR, and until this call site passed
+    ``multimodal=`` the shipped chat surface could not tell the difference the
+    signal was built to report.
     """
-    from lattice_brain.graph.retrieval import context_quality_signal
+    from lattice_brain.graph.retrieval import (
+        context_quality_signal,
+        multimodal_signal,
+    )
 
     query = str(query or "").strip()
     if knowledge_graph is None or not query:
@@ -233,7 +242,9 @@ def build_context_quality(
             return context_quality_signal("none", 0, reason="그래프 검색에 실패했습니다")
         matches = result.get("matches") or []
         return context_quality_signal(
-            str(result.get("mode") or "hybrid"), len(matches)
+            str(result.get("mode") or "hybrid"),
+            len(matches),
+            multimodal=multimodal_signal(matches),
         )
     # Lexical-only stores without the hybrid mixin.
     try:
@@ -242,7 +253,9 @@ def build_context_quality(
         ).get("matches") or []
     except Exception:  # noqa: BLE001 — signal building must never fail chat
         return context_quality_signal("none", 0, reason="그래프 검색에 실패했습니다")
-    return context_quality_signal("lexical_only", len(matches))
+    return context_quality_signal(
+        "lexical_only", len(matches), multimodal=multimodal_signal(matches)
+    )
 
 
 # ── answer-citation binding (backlog #11, review §7.2 E #4) ──────────────────

package/latticeai/api/chat_hybrid.py

@@ -14,7 +14,10 @@ from latticeai.core.network_boundary import (
     NetworkBoundaryMode,
     normalize_network_mode,
 )
-from latticeai.runtime.network_boundary_wiring import resolve_active_network_mode
+from latticeai.runtime.network_boundary_wiring import (
+    get_hybrid_policy_service,
+    resolve_active_network_mode,
+)
 from latticeai.services.hybrid_chat import stream_hybrid_cloud_turn
 
 
@@ -32,6 +35,28 @@ def resolve_request_network_mode(
     )
 
 
+def resolve_hybrid_auto_commit(
+    *,
+    user_email: Optional[str],
+    workspace_id: Optional[str],
+) -> bool:
+    """The scoped hybrid policy's ``auto_commit`` decision for this turn.
+
+    Sibling of :func:`resolve_request_network_mode`: the dial says whether the
+    turn may reach the cloud, this says what may happen to what comes back.
+    Default is ``False`` — cloud-derived knowledge waits in the Review Center
+    — and a policy that cannot be read is treated as the default rather than
+    as permission.
+    """
+    try:
+        policy = get_hybrid_policy_service().resolve(
+            user_email=user_email, workspace_id=workspace_id
+        )
+    except Exception:  # noqa: BLE001 — an unreadable policy never grants a write
+        return False
+    return bool(policy.get("auto_commit", False))
+
+
 def maybe_hybrid_stream_response(
     *,
     req: Any,
@@ -45,6 +70,7 @@ def maybe_hybrid_stream_response(
     chat_service: Any,
     notify: Any,
     model_id: Optional[str],
+    review_queue: Any = None,
 ) -> Optional[StreamingResponse]:
     """Return a StreamingResponse when cloud path should run; else None."""
     if mode != NetworkBoundaryMode.CLOUD_ALLOWED:
@@ -66,6 +92,10 @@ def maybe_hybrid_stream_response(
             history_user=history_user,
             notify=notify,
             source=req.source,
+            review_queue=review_queue,
+            auto_commit=resolve_hybrid_auto_commit(
+                user_email=effective_email, workspace_id=workspace_id
+            ),
         ),
         media_type="text/event-stream",
         headers={
@@ -78,5 +108,6 @@ def maybe_hybrid_stream_response(
 
 __all__ = [
     "resolve_request_network_mode",
+    "resolve_hybrid_auto_commit",
     "maybe_hybrid_stream_response",
 ]

package/latticeai/api/chronicle.py

@@ -0,0 +1,63 @@
+"""Brain Chronicle API router (v11.3.0, track B).
+
+Read-only surface over :class:`~latticeai.services.chronicle.ChronicleService`
+— the first HTTP exposure of the bitemporal data v11.1.0 started recording:
+
+* ``GET /api/chronicle/overview`` — the growth curve: totals, the first and
+  last thing the Brain ever saw, and one bucket per day.
+* ``GET /api/chronicle/day/{date}`` — one day's story, grouped into what came
+  in, what was learned, what was talked about, and what changed.
+* ``GET /api/chronicle/as-of?ts=…`` — the Brain as it stood at an instant.
+
+All three follow the same require_user/gate_read contract as the command
+centre, so a workspace member never reads another workspace's timeline. A
+malformed date or timestamp answers 422 through the message catalog rather
+than a 500 or a silently empty day.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from fastapi import APIRouter, Query, Request
+
+from latticeai.core.messages import http_error, resolve_language
+from latticeai.services.chronicle import ChronicleService
+
+
+def create_chronicle_router(
+    *,
+    service: ChronicleService,
+    require_user: Callable[[Request], str],
+    gate_read: Callable[[Request], Optional[str]],
+) -> APIRouter:
+    router = APIRouter()
+
+    @router.get("/api/chronicle/overview")
+    async def chronicle_overview(request: Request):
+        user = require_user(request)
+        scope = gate_read(request)
+        return service.overview(user_email=user, workspace_id=scope)
+
+    @router.get("/api/chronicle/day/{date}")
+    async def chronicle_day(date: str, request: Request):
+        user = require_user(request)
+        scope = gate_read(request)
+        try:
+            return service.day(date, user_email=user, workspace_id=scope)
+        except ValueError:
+            raise http_error(422, "chronicle.bad_date", resolve_language(request))
+
+    @router.get("/api/chronicle/as-of")
+    async def chronicle_as_of(request: Request, ts: str = Query(..., max_length=64)):
+        require_user(request)
+        scope = gate_read(request)
+        try:
+            return service.as_of(ts, workspace_id=scope)
+        except ValueError:
+            raise http_error(422, "chronicle.bad_timestamp", resolve_language(request))
+
+    return router
+
+
+__all__ = ["create_chronicle_router"]

package/latticeai/api/features.py

@@ -0,0 +1,70 @@
+"""Feature switchboard API — read the catalog, move one switch (v11.2.0).
+
+Two routes and no more. The catalog is rendered by the service (labels,
+explanations, defaults, which options are even installable), so this router
+carries no product knowledge at all: adding a feature is a line in
+``latticeai/services/feature_toggles.CATALOG``, not a change here or in the
+client.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Union
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, Field
+
+from latticeai.core.messages import http_error, resolve_language
+from latticeai.services.feature_toggles import (
+    FeatureToggleService,
+    InvalidFeatureValue,
+    UnknownFeature,
+)
+
+
+class SetFeatureRequest(BaseModel):
+    """One switch move. ``value`` is a bool for a toggle, a string for a choice."""
+
+    value: Union[bool, str] = Field(
+        ..., description="true/false for a toggle, or the option id for a choice"
+    )
+
+
+def create_features_router(
+    *,
+    service: FeatureToggleService,
+    require_user: Callable[..., str],
+) -> APIRouter:
+    router = APIRouter(tags=["features"])
+
+    @router.get("/api/features")
+    async def list_features(request: Request) -> Any:
+        """Every opt-in feature, its live value, and where that value came from."""
+        require_user(request)
+        return service.catalog(resolve_language(request))
+
+    @router.post("/api/features/{feature_id}")
+    async def set_feature(
+        feature_id: str, body: SetFeatureRequest, request: Request
+    ) -> Any:
+        """Persist one person's choice; the answer is the feature as it now reads."""
+        user = require_user(request)
+        language = resolve_language(request)
+        try:
+            return service.set(
+                feature_id, body.value, language=language, user_email=user
+            )
+        except UnknownFeature as exc:
+            raise http_error(
+                400, "features.unknown", language, feature=feature_id
+            ) from exc
+        except InvalidFeatureValue as exc:
+            # Pass-through: the service already localized the reason through the
+            # same catalog (wrong type, or an option whose optional dependency
+            # is not installed), and re-wording it here would only lose it.
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    return router
+
+
+__all__ = ["SetFeatureRequest", "create_features_router"]