ltcai 9.9.5 → 10.0.0

package/lattice_brain/ingestion.py

@@ -42,10 +42,9 @@ from __future__ import annotations
 import fnmatch
 import hashlib
 import os
-import threading
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Dict, Iterable, List, Optional, Set, Tuple
+from typing import Any, Dict, Iterable, List, Optional, Tuple
 
 from .runtime.hooks import dispatch_tool
 from .utils import utc_now_iso
@@ -353,110 +352,14 @@ def _matches_ignore(
     return False
 
 
-# --- Large candidate 1 slice: incremental / background ingestion support ---
-JOB_ERRORS_CAP = 50  # per-job error records kept (failed count keeps counting)
-
-
-@dataclass
-class BackgroundIngestionJob:
-    """Job descriptor + progress state for background/incremental indexing.
-
-    ``done_indices`` tracks per-item completion so an interrupted or partially
-    failed job can be *resumed* from the remaining items instead of restarting.
-    ``errors`` is capped at ``max_errors`` records; ``failed`` keeps counting.
-    """
-    job_id: str
-    items: List[IngestionItem]
-    status: str = "queued"  # queued | running | completed | failed | partial
-    created_at: str = field(default_factory=utc_now_iso)
-    updated_at: str = field(default_factory=utc_now_iso)
-    processed: int = 0
-    failed: int = 0
-    total: int = 0
-    errors: List[Dict[str, Any]] = field(default_factory=list)
-    incremental: bool = True
-    user_email: Optional[str] = None
-    max_errors: int = JOB_ERRORS_CAP
-    done_indices: Set[int] = field(default_factory=set)
-
-    def touch(self) -> None:
-        self.updated_at = utc_now_iso()
-
-    def record_error(self, index: int, item: IngestionItem, detail: Any) -> None:
-        self.failed += 1
-        if len(self.errors) < self.max_errors:
-            self.errors.append({
-                "index": index,
-                "source": item.source_uri or item.path or item.title or item.source_type,
-                "detail": str(detail)[:500],
-            })
-
-    def remaining_indices(self) -> List[int]:
-        return [i for i in range(len(self.items)) if i not in self.done_indices]
-
-    def as_dict(self) -> Dict[str, Any]:
-        """Frozen job schema consumed by ``/api/ingestion/jobs*``."""
-        return {
-            "job_id": self.job_id,
-            "status": self.status,
-            "total": self.total,
-            "processed": self.processed,
-            "failed": self.failed,
-            "errors": list(self.errors),
-            "created_at": self.created_at,
-            "updated_at": self.updated_at,
-        }
-
-
-class BackgroundIngestionQueue:
-    """Simple in-memory queue for background incremental ingestion.
-
-    For large corpus: this is the seam where a real scheduler / worker pool
-    (celery, rq, or internal thread) can be plugged later without changing callers.
-    Supports incremental (skip duplicates) vs force reindex.
-    """
-    def __init__(self) -> None:
-        self._jobs: Dict[str, BackgroundIngestionJob] = {}
-        self._counter = 0
-        self._lock = threading.Lock()
-
-    def schedule(
-        self,
-        items: List[IngestionItem],
-        *,
-        incremental: bool = True,
-        user_email: Optional[str] = None,
-    ) -> BackgroundIngestionJob:
-        with self._lock:
-            self._counter += 1
-            job_id = f"bg_ingest_{self._counter:04d}"
-        job = BackgroundIngestionJob(
-            job_id=job_id,
-            items=items,
-            total=len(items),
-            incremental=incremental,
-            user_email=user_email,
-        )
-        # annotate items for downstream
-        for it in job.items:
-            # attach flag without breaking dataclass defaults (use metadata)
-            it.metadata = {**it.metadata, "incremental": incremental, "bg_job": job_id}
-        with self._lock:
-            self._jobs[job_id] = job
-        return job
-
-    def get(self, job_id: str) -> Optional[BackgroundIngestionJob]:
-        return self._jobs.get(job_id)
-
-    def list_pending(self) -> List[BackgroundIngestionJob]:
-        return [j for j in self._jobs.values() if j.status == "queued"]
-
-    def list_recent(self, limit: int = 20) -> List[BackgroundIngestionJob]:
-        """Most recent jobs first (insertion order is schedule order)."""
-        limit = max(1, int(limit))
-        with self._lock:
-            jobs = list(self._jobs.values())
-        return list(reversed(jobs))[:limit]
+# Background job scheduling + progress lives in its own module (v9.9.6):
+# the pipeline owns "ingest one item", the queue owns "schedule many and
+# report progress". Re-exported so every existing import keeps working.
+from .ingestion_jobs import (  # noqa: E402,F401 — re-export for existing importers
+    JOB_ERRORS_CAP,
+    BackgroundIngestionJob,
+    BackgroundIngestionQueue,
+)
 
 
 @dataclass

package/lattice_brain/ingestion_jobs.py

@@ -0,0 +1,133 @@
+"""Background ingestion jobs — queue + per-job progress (v9.9.6 extraction).
+
+Split out of :mod:`lattice_brain.ingestion` (behaviour-preserving move, review
+2026-07-27 P2 #8 "ingestion job/watch 분리"). The pipeline owns *what it means
+to ingest one item*; this module owns *scheduling many of them and reporting
+progress* — a genuinely separate concern with its own frozen wire schema
+(``/api/ingestion/jobs*``) and its own resume semantics.
+
+The seam is also where a real scheduler (thread pool, rq, celery) would plug
+in without touching the pipeline.
+
+``IngestionItem`` is imported only for type checking: the pipeline module owns
+that dataclass, and a runtime import here would be circular.
+"""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Set
+
+from .utils import utc_now_iso
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from .ingestion import IngestionItem
+
+
+JOB_ERRORS_CAP = 50  # per-job error records kept (failed count keeps counting)
+
+
+@dataclass
+class BackgroundIngestionJob:
+    """Job descriptor + progress state for background/incremental indexing.
+
+    ``done_indices`` tracks per-item completion so an interrupted or partially
+    failed job can be *resumed* from the remaining items instead of restarting.
+    ``errors`` is capped at ``max_errors`` records; ``failed`` keeps counting.
+    """
+    job_id: str
+    items: List[IngestionItem]
+    status: str = "queued"  # queued | running | completed | failed | partial
+    created_at: str = field(default_factory=utc_now_iso)
+    updated_at: str = field(default_factory=utc_now_iso)
+    processed: int = 0
+    failed: int = 0
+    total: int = 0
+    errors: List[Dict[str, Any]] = field(default_factory=list)
+    incremental: bool = True
+    user_email: Optional[str] = None
+    max_errors: int = JOB_ERRORS_CAP
+    done_indices: Set[int] = field(default_factory=set)
+
+    def touch(self) -> None:
+        self.updated_at = utc_now_iso()
+
+    def record_error(self, index: int, item: IngestionItem, detail: Any) -> None:
+        self.failed += 1
+        if len(self.errors) < self.max_errors:
+            self.errors.append({
+                "index": index,
+                "source": item.source_uri or item.path or item.title or item.source_type,
+                "detail": str(detail)[:500],
+            })
+
+    def remaining_indices(self) -> List[int]:
+        return [i for i in range(len(self.items)) if i not in self.done_indices]
+
+    def as_dict(self) -> Dict[str, Any]:
+        """Frozen job schema consumed by ``/api/ingestion/jobs*``."""
+        return {
+            "job_id": self.job_id,
+            "status": self.status,
+            "total": self.total,
+            "processed": self.processed,
+            "failed": self.failed,
+            "errors": list(self.errors),
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+        }
+
+
+class BackgroundIngestionQueue:
+    """Simple in-memory queue for background incremental ingestion.
+
+    For large corpus: this is the seam where a real scheduler / worker pool
+    (celery, rq, or internal thread) can be plugged later without changing callers.
+    Supports incremental (skip duplicates) vs force reindex.
+    """
+    def __init__(self) -> None:
+        self._jobs: Dict[str, BackgroundIngestionJob] = {}
+        self._counter = 0
+        self._lock = threading.Lock()
+
+    def schedule(
+        self,
+        items: List[IngestionItem],
+        *,
+        incremental: bool = True,
+        user_email: Optional[str] = None,
+    ) -> BackgroundIngestionJob:
+        with self._lock:
+            self._counter += 1
+            job_id = f"bg_ingest_{self._counter:04d}"
+        job = BackgroundIngestionJob(
+            job_id=job_id,
+            items=items,
+            total=len(items),
+            incremental=incremental,
+            user_email=user_email,
+        )
+        # annotate items for downstream
+        for it in job.items:
+            # attach flag without breaking dataclass defaults (use metadata)
+            it.metadata = {**it.metadata, "incremental": incremental, "bg_job": job_id}
+        with self._lock:
+            self._jobs[job_id] = job
+        return job
+
+    def get(self, job_id: str) -> Optional[BackgroundIngestionJob]:
+        return self._jobs.get(job_id)
+
+    def list_pending(self) -> List[BackgroundIngestionJob]:
+        return [j for j in self._jobs.values() if j.status == "queued"]
+
+    def list_recent(self, limit: int = 20) -> List[BackgroundIngestionJob]:
+        """Most recent jobs first (insertion order is schedule order)."""
+        limit = max(1, int(limit))
+        with self._lock:
+            jobs = list(self._jobs.values())
+        return list(reversed(jobs))[:limit]
+
+
+__all__ = ["JOB_ERRORS_CAP", "BackgroundIngestionJob", "BackgroundIngestionQueue"]

package/lattice_brain/runtime/multi_agent.py

@@ -48,7 +48,7 @@ from .contracts import multi_agent_contract
 from ..utils import now_iso as _now
 
 
-MULTI_AGENT_VERSION = "9.9.5"
+MULTI_AGENT_VERSION = "10.0.0"
 
 AGENT_ROLES = ("researcher", "planner", "executor", "reviewer", "release")
 CORE_PIPELINE = ("planner", "executor", "reviewer")

package/latticeai/__init__.py

@@ -1,3 +1,3 @@
 """Lattice AI - modular server package."""
 
-__version__ = "9.9.5"
+__version__ = "10.0.0"

package/latticeai/api/brain_intelligence.py

@@ -57,6 +57,14 @@ def create_brain_intelligence_router(
         scope = gate_read(request)
         return service.contradictions(user_email=user, workspace_id=scope)
 
+    @router.get("/api/brain/garden")
+    async def brain_garden(request: Request, limit: int = 8):
+        """Knowledge garden overview (v9.9.7): recent / contradictions /
+        stale / frequent, read-only and workspace-scoped."""
+        user = require_user(request)
+        scope = gate_read(request)
+        return service.garden_overview(user_email=user, workspace_id=scope, limit=limit)
+
     @router.get("/api/brain/vector-freshness")
     async def brain_vector_freshness(request: Request):
         """Vector index freshness summary (read-only, never raises).

package/latticeai/api/chat.py

@@ -16,6 +16,7 @@ from fastapi import APIRouter, HTTPException, Request
 from fastapi.responses import JSONResponse, StreamingResponse
 
 from latticeai.api.chat_agent_http import AgentHTTPController
+from latticeai.core.project_sessions import ProjectSessionStore
 from latticeai.api.chat_contracts import (
     AgentEvalRequest,
     AgentRequest,
@@ -197,6 +198,14 @@ def create_chat_router(context: AppContext) -> APIRouter:
             if context.data_dir
             else None
         ),
+        # Multi-turn project loop (v9.9.6): optional — without a data dir the
+        # agent runs exactly as before, one run at a time with no project state.
+        project_sessions=(
+            ProjectSessionStore(Path(context.data_dir) / "project_sessions")
+            if context.data_dir
+            else None
+        ),
+        artifact_ledger=context.artifact_ledger,
     )
     intent_controller = ChatIntentController(
         model_router=model_router,

package/latticeai/api/chat_agent_http.py

@@ -14,11 +14,14 @@ from pathlib import Path
 from typing import Any, Dict, Optional
 
 from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import StreamingResponse
 
 from lattice_brain.runtime.hooks import dispatch_tool
 from latticeai.api.chat_contracts import AgentEvalRequest, AgentRequest, AgentResumeRequest
 from latticeai.api.chat_helpers import _LANG_HINT, detect_language, workspace_scope_from_request
+from latticeai.api.chat_stream import agent_live_stream
 from latticeai.core.agent import AgentRunContext, AgentState, normalize_plan
+from latticeai.core.run_explain import explain_run
 from latticeai.core.run_store import (
     AgentRunStore,
     hash_approval_token,
@@ -48,6 +51,8 @@ class AgentHTTPController:
         ensure_agent_root: Any,
         funnel_metrics: Any = None,
         run_store: Any = None,
+        project_sessions: Any = None,
+        artifact_ledger: Any = None,
     ) -> None:
         self.runtime = runtime
         self.model_router = model_router
@@ -65,6 +70,12 @@ class AgentHTTPController:
         self.agent_root = Path(agent_root)
         self.ensure_agent_root = ensure_agent_root
         self.funnel_metrics = funnel_metrics
+        # Multi-turn project loop (v9.9.6). Optional: without a store the
+        # agent behaves exactly as before — single runs, no project memory.
+        self.project_sessions = project_sessions
+        # Re-search loop (v9.9.6): the next turn must see files this run just
+        # wrote, even before asynchronous indexing catches up.
+        self.artifact_ledger = artifact_ledger
         self._pending_lock = threading.Lock()
         # awaiting_approval runs: run_id -> paused run state + approval token.
         # Fail-closed: governed steps only ever execute after resume presents
@@ -91,6 +102,24 @@ class AgentHTTPController:
 
         @router.post("/agent")
         async def agent(req: AgentRequest, request: Request):
+            if req.stream:
+                # Surface parity (v9.9.7): the web app already watches the loop
+                # live through the chat route. `/agent` clients (VS Code) get
+                # the same named `agent_step` frames here, followed by the
+                # exact terminal payload the JSON response returns — a client
+                # that ignores named events sees the historical shape.
+                async def start(observer):
+                    return await self.agent(req, request, on_step=observer)
+
+                return StreamingResponse(
+                    agent_live_stream(
+                        start,
+                        router=self.model_router,
+                        model_id=req.executing_model,
+                    ),
+                    media_type="text/event-stream",
+                    headers={"X-Routed-To": "agent"},
+                )
             return await self.agent(req, request)
 
         @router.post("/agent/resume")
@@ -238,6 +267,18 @@ class AgentHTTPController:
             ctx.on_step = on_step
         ctx.executing_model = req.executing_model
         ctx.reviewing_model = req.reviewing_model
+        ctx.project_context = self._project_summary(req, current_user)
+        # Autonomy dial (v9.9.8): resolve the user/workspace-scoped mode once so
+        # the plan gate and every per-tool gate in this run agree, even if the
+        # stored preference changes mid-run.
+        mode_probe = getattr(self.runtime, "resolve_permission_mode", None)
+        if callable(mode_probe):
+            try:
+                ctx.permission_mode = mode_probe(
+                    user_email=current_user, workspace_id=req.workspace_id,
+                ).value
+            except Exception:  # noqa: BLE001 — never fail a run over the dial
+                ctx.permission_mode = None
         ctx.state = AgentState.PLANNING
         ctx.state_history.append(ctx.state.value)
         await self.runtime.plan(
@@ -288,6 +329,55 @@ class AgentHTTPController:
             max_retry,
         )
 
+    def _project_summary(self, req: AgentRequest, current_user: str) -> str:
+        """Where this project stands, for the planner/executor prompt.
+
+        Advisory: a missing store, an unknown project id, or a read failure
+        yields "" and the run proceeds as a standalone run.
+        """
+        project_id = getattr(req, "project_id", None)
+        if not project_id or self.project_sessions is None:
+            return ""
+        try:
+            return self.project_sessions.summary(
+                str(project_id),
+                user_email=current_user or None,
+                workspace_id=req.workspace_id,
+            )
+        except Exception as exc:  # noqa: BLE001 — project context never gates a run
+            logging.warning("project session summary failed: %s", exc)
+            return ""
+
+    def _record_project_run(
+        self,
+        req: AgentRequest,
+        current_user: str,
+        ctx: AgentRunContext,
+        payload: Dict[str, Any],
+    ) -> None:
+        """Fold a finished run into its project session (best effort).
+
+        The verification result is stored exactly as the run reported it — a
+        NEEDS_REVIEW run never becomes a project's "done".
+        """
+        project_id = getattr(req, "project_id", None)
+        if not project_id or self.project_sessions is None:
+            return
+        try:
+            self.project_sessions.record_run(
+                str(project_id),
+                run_id=str(payload.get("run_id") or ""),
+                goal=str(ctx.plan.get("goal") or req.message),
+                status=str(payload.get("status") or ""),
+                final_state=ctx.state.value,
+                files=payload.get("created_files") or [],
+                explanation=payload.get("explanation"),
+                user_email=current_user or None,
+                workspace_id=req.workspace_id,
+            )
+        except Exception as exc:  # noqa: BLE001 — bookkeeping never fails a run
+            logging.warning("project session record failed: %s", exc)
+
     def _pause_for_approval(
         self,
         ctx: AgentRunContext,
@@ -541,7 +631,8 @@ class AgentHTTPController:
                     self.funnel_metrics.increment("needs_review_runs")
             except Exception as exc:  # noqa: BLE001
                 logging.warning("funnel metrics increment failed: %s", exc)
-        return {
+        loop_summary = ctx.trace.summary()
+        payload = {
             "status": "ok" if ctx.state == AgentState.DONE else "failed",
             "response": message,
             "workspace": str(self.agent_root),
@@ -550,8 +641,34 @@ class AgentHTTPController:
             "final_state": ctx.state.value,
             "created_files": collect_created_files(ctx.transcript),
             "artifacts": collect_artifacts(ctx.transcript),
-            "loop": ctx.trace.summary(),
+            "loop": loop_summary,
+            # Plain-language outcome (v9.9.6): the loop counters say a weak
+            # model needed three repairs; this says it in a sentence a person
+            # can read, and never upgrades a non-success into a success.
+            "explanation": explain_run(
+                state=ctx.state,
+                loop=loop_summary,
+                transcript=ctx.transcript,
+                max_retry=max_retry,
+            ),
         }
+        # Multi-turn project loop (v9.9.6): the project remembers this run's
+        # files and its honest verdict, so the next turn continues instead of
+        # restarting.
+        self._record_project_run(req, current_user, ctx, payload)
+        if self.artifact_ledger is not None and payload.get("created_files"):
+            try:
+                self.artifact_ledger.record(
+                    payload["created_files"],
+                    user_email=current_user or None,
+                    conversation_id=req.conversation_id,
+                    workspace_id=req.workspace_id,
+                )
+            except Exception as exc:  # noqa: BLE001 — advisory context only
+                logging.warning("artifact ledger record failed: %s", exc)
+        if getattr(req, "project_id", None):
+            payload["project_id"] = str(req.project_id)
+        return payload
 
     async def resume(
         self,

package/latticeai/api/chat_contracts.py

@@ -36,6 +36,15 @@ class AgentRequest(BaseModel):
     executing_model: Optional[str] = None
     reviewing_model: Optional[str] = None
     human_in_loop: bool = False
+    # Multi-turn project loop (v9.9.6): when set, the run reads the project's
+    # accumulated state (files, open TODOs, last verification) and folds its
+    # own outcome back in when it finishes.
+    project_id: Optional[str] = None
+    # Live loop visibility (v9.9.7): stream named `agent_step` SSE frames while
+    # the run executes, then the same terminal payload as the JSON response.
+    # Surface parity — the web app already gets this through the chat route;
+    # `/agent` clients (VS Code) need it on their own endpoint.
+    stream: bool = False
 
 
 class AgentResumeRequest(BaseModel):

package/latticeai/api/chat_documents.py

@@ -134,6 +134,11 @@ class DocumentGenerationCoordinator:
                     logging.debug(
                         "Document generation context retrieved from knowledge graph."
                     )
+                # Shared context contract (v9.9.6): document generation now
+                # reports the same context_quality signal chat does, so a
+                # thin-context document is as visible as a thin-context answer.
+                if retrieval.get("stats", {}).get("budget_trimmed"):
+                    logging.debug("Document context trimmed to the shared budget.")
             except Exception as exc:
                 logging.warning("Knowledge graph reinforcement skipped: %s", exc)
         return DocumentPreparation(is_document, context, retrieval)
@@ -165,6 +170,16 @@ class DocumentGenerationCoordinator:
         graph_markdown = (preparation.retrieval or {}).get("context_markdown", "")
         system_prompt = session.get_system_prompt(graph_markdown)
         footnote = format_sources_footnote((preparation.retrieval or {}).get("sources", []))
+        # Shared context contract (v9.9.6): the document path records the same
+        # context_quality + assembly trace on the answer trace that chat does,
+        # so both surfaces answer "how well was this grounded?" identically.
+        context_quality = (preparation.retrieval or {}).get("context_quality")
+        if isinstance(trace_seed, dict):
+            if context_quality:
+                trace_seed["context_quality"] = context_quality
+            assembly_trace = (preparation.retrieval or {}).get("trace")
+            if assembly_trace:
+                trace_seed["context_assembly"] = assembly_trace
 
         if req.stream:
             async def stream_document():
@@ -245,6 +260,7 @@ class DocumentGenerationCoordinator:
                 "response": response_text,
                 "trace_id": trace_record["id"],
                 "trace": trace_record,
+                **({"context_quality": context_quality} if context_quality else {}),
             }
         )
 

package/latticeai/api/evidence_actions.py

@@ -0,0 +1,48 @@
+"""Evidence → action router (v9.9.6).
+
+``POST /api/evidence/actions`` turns an answer's citations into ready-to-send,
+evidence-scoped follow-up prompts. Read-only and deterministic: it resolves
+graph nodes and composes text — no model call, no writes. Execution stays on
+the existing chat / file-generation path so there is exactly one road from a
+prompt to an artifact.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, List, Optional
+
+from fastapi import APIRouter, Request
+from pydantic import BaseModel, Field
+
+
+class EvidenceActionsRequest(BaseModel):
+    """Citations from one answer (the ids the grounding badge reported)."""
+
+    question: str = ""
+    source_ids: List[str] = Field(default_factory=list)
+    language: str = "ko"
+
+
+def create_evidence_actions_router(
+    *,
+    service: Any,
+    require_user: Callable[[Request], Any],
+    allowed_workspaces_for: Optional[Callable[[Any], Any]] = None,
+) -> APIRouter:
+    router = APIRouter()
+
+    @router.post("/api/evidence/actions")
+    async def evidence_actions(req: EvidenceActionsRequest, request: Request):
+        user = require_user(request)
+        scope = allowed_workspaces_for(user) if allowed_workspaces_for is not None else None
+        return service.actions_for(
+            question=req.question,
+            source_ids=req.source_ids,
+            language=req.language,
+            allowed_workspaces=scope,
+        )
+
+    return router
+
+
+__all__ = ["create_evidence_actions_router", "EvidenceActionsRequest"]

package/latticeai/api/permission_mode.py

@@ -0,0 +1,61 @@
+"""Permission mode API — strict / trusted / bypass dial (v9.9.8)."""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, Field
+
+from latticeai.core.permission_mode import mode_catalog, normalize_mode
+from latticeai.services.permission_mode_service import PermissionModeService
+
+
+class SetPermissionModeRequest(BaseModel):
+    mode: str = Field(..., description="strict | trusted | bypass")
+    workspace_id: Optional[str] = None
+    acknowledge_risk: bool = False
+
+
+def create_permission_mode_router(
+    *,
+    service: PermissionModeService,
+    require_user: Callable[..., str],
+) -> APIRouter:
+    router = APIRouter(tags=["permission-mode"])
+
+    @router.get("/api/permission-mode")
+    async def get_permission_mode(
+        request: Request,
+        workspace_id: Optional[str] = None,
+    ):
+        user = require_user(request)
+        header_ws = request.headers.get("X-Workspace-Id")
+        scope = workspace_id or (header_ws.strip() if header_ws else None)
+        return service.get(user_email=user, workspace_id=scope)
+
+    @router.get("/api/permission-mode/catalog")
+    async def permission_mode_catalog(request: Request):
+        require_user(request)
+        return {"modes": mode_catalog()}
+
+    @router.post("/api/permission-mode")
+    async def set_permission_mode(body: SetPermissionModeRequest, request: Request):
+        user = require_user(request)
+        header_ws = request.headers.get("X-Workspace-Id")
+        scope = body.workspace_id or (header_ws.strip() if header_ws else None)
+        try:
+            return service.set_mode(
+                normalize_mode(body.mode),
+                user_email=user,
+                workspace_id=scope,
+                acknowledge_risk=body.acknowledge_risk,
+                source="api",
+            )
+        except PermissionError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    return router
+
+
+__all__ = ["create_permission_mode_router", "SetPermissionModeRequest"]