ltcai 9.9.4 → 9.9.9

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/quality.py

@@ -131,13 +131,33 @@ class HybridFusion:
         return sorted(results, key=lambda x: x["fused_score"], reverse=True)
 
 class RerankerInterface:
-    """Pluggable reranker interface"""
+    """Pluggable reranker interface.
+
+    Default is identity (fused score). When
+    ``LATTICEAI_CROSS_ENCODER_RERANK=1`` and a CrossEncoder is importable,
+    delegates to :func:`lattice_brain.graph.rerank.rerank_matches`. Failures
+    never raise — always returns a ranked list.
+    """
+
     def rerank(self, query: str, candidates: List[Dict], top_k: int = 5) -> List[Dict]:
-        # Default local-safe fallback: preserve fused ordering without making
-        # unearned cross-encoder claims.
-        for c in candidates:
-            c["rerank_score"] = c.get("fused_score", 0.0)
-        return sorted(candidates, key=lambda x: x.get("rerank_score", 0), reverse=True)[:top_k]
+        try:
+            from lattice_brain.graph.rerank import rerank_matches
+
+            # Map fused_score → score so the shared helper ranks consistently.
+            prepared = []
+            for c in candidates:
+                item = dict(c)
+                if "score" not in item:
+                    item["score"] = item.get("fused_score", 0.0)
+                prepared.append(item)
+            result = rerank_matches(query, prepared, top_k=top_k)
+            return list(result.get("matches") or [])
+        except Exception:  # noqa: BLE001 — quality path must never raise
+            for c in candidates:
+                c["rerank_score"] = c.get("fused_score", 0.0)
+            return sorted(
+                candidates, key=lambda x: x.get("rerank_score", 0), reverse=True
+            )[:top_k]
 
 # -----------------------------
 # 3. Memory Candidate Extraction / Scoring / Dedupe / Merge / Conflict / Retention

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.4"
+MULTI_AGENT_VERSION = "9.9.9"
 
 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.4"
+__version__ = "9.9.9"

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,9 +70,13 @@ class AgentHTTPController:
         self.agent_root = Path(agent_root)
         self.ensure_agent_root = ensure_agent_root
         self.funnel_metrics = funnel_metrics
-        self._pending: Dict[str, tuple] = {}
+        # 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()
-        self._pending_ttl_seconds = 15 * 60
         # awaiting_approval runs: run_id -> paused run state + approval token.
         # Fail-closed: governed steps only ever execute after resume presents
         # the matching, unexpired token for this run (or via the legacy
@@ -93,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")
@@ -240,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(
@@ -250,33 +289,29 @@ class AgentHTTPController:
             model_id=req.planning_model,
         )
 
+        requirements_probe = getattr(self.runtime, "approval_requirements", None)
+
         if req.human_in_loop:
-            context_id = secrets.token_urlsafe(16)
-            with self._pending_lock:
-                self._pending[context_id] = (
-                    ctx,
-                    req,
-                    language_hint,
-                    current_user,
-                    time.monotonic(),
-                )
-            return {
-                "status": "waiting_approval",
-                "context_id": context_id,
-                "plan": ctx.plan,
-                "steps": ctx.transcript,
-                "state_history": ctx.state_history,
-                "planning_model": req.planning_model or self.model_router.current_model_id,
-                "executing_model": req.executing_model or self.model_router.current_model_id,
-                "reviewing_model": req.reviewing_model or self.model_router.current_model_id,
-                "loop": ctx.trace.summary(),
-            }
+            # Deprecated explicit pause (L1 unification, 9.9.5): the legacy
+            # ``human_in_loop`` flow now rides the same durable approval
+            # store as ``awaiting_approval`` — one pause path, one resume
+            # path, restart-safe. The legacy wire contract is preserved:
+            # ``status="waiting_approval"`` + ``context_id`` (token-less,
+            # same-user resume).
+            requirements = (
+                requirements_probe(ctx)
+                if callable(requirements_probe)
+                else {"requires_approval": True, "non_auto_steps": [], "plan_summary": ""}
+            )
+            return self._pause_for_approval(
+                ctx, req, language_hint, current_user, requirements,
+                legacy_context=True,
+            )
 
         # Interactive approval: when the plan needs human approval, pause the
         # run as awaiting_approval (short-TTL token) instead of failing it.
         # ``getattr`` keeps injected fake runtimes without the preview method
         # on the historical fail-closed path.
-        requirements_probe = getattr(self.runtime, "approval_requirements", None)
         if callable(requirements_probe):
             requirements = requirements_probe(ctx)
             if requirements.get("requires_approval"):
@@ -294,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,
@@ -301,8 +385,16 @@ class AgentHTTPController:
         language_hint: str,
         current_user: str,
         requirements: Dict[str, Any],
+        *,
+        legacy_context: bool = False,
     ) -> Dict[str, Any]:
-        """Park a plan that needs approval and hand the user a resume token."""
+        """Park a plan that needs approval and hand the user a resume token.
+
+        ``legacy_context=True`` marks a deprecated ``human_in_loop`` pause:
+        same durable storage, but the response speaks the historical
+        ``waiting_approval``/``context_id`` contract and resume may present
+        the ``context_id`` instead of the approval token (same user only).
+        """
         run_id = secrets.token_urlsafe(16)
         approval_token = secrets.token_urlsafe(32)
         now_monotonic = time.monotonic()
@@ -319,6 +411,7 @@ class AgentHTTPController:
                 "token": approval_token,
                 "expires_monotonic": now_monotonic + self._approval_ttl_seconds,
                 "expires_at": expires_at,
+                "legacy_context": legacy_context,
             }
         # Durable mirror: a restart between pause and resume must not orphan
         # the run. Best-effort — the in-memory pause still answers on failure.
@@ -332,6 +425,7 @@ class AgentHTTPController:
                 token=approval_token,
                 expires_epoch=time.time() + self._approval_ttl_seconds,
                 expires_at=expires_at,
+                legacy_context=legacy_context,
             )
         except Exception as exc:  # noqa: BLE001
             logging.warning("agent run store persist failed: %s", exc)
@@ -345,8 +439,8 @@ class AgentHTTPController:
             "이 작업에는 승인이 필요한 단계가 있어 실행을 잠시 멈췄습니다. "
             "계획을 확인한 뒤 승인하면 이어서 실행합니다."
         )
-        return {
-            "status": "awaiting_approval",
+        payload = {
+            "status": "waiting_approval" if legacy_context else "awaiting_approval",
             "run_id": run_id,
             "approval": {
                 "token": approval_token,
@@ -364,6 +458,10 @@ class AgentHTTPController:
             "reviewing_model": req.reviewing_model or self.model_router.current_model_id,
             "loop": ctx.trace.summary(),
         }
+        if legacy_context:
+            # Historical wire field — the run id doubles as the context id.
+            payload["context_id"] = run_id
+        return payload
 
     def _purge_expired_approvals_locked(self, now_monotonic: float) -> None:
         for run_id, entry in list(self._approvals.items()):
@@ -450,6 +548,7 @@ class AgentHTTPController:
             "token_hash": str(record.get("token_hash") or ""),
             "expires_monotonic": time.monotonic() + remaining,
             "expires_at": record.get("expires_at"),
+            "legacy_context": bool(record.get("legacy_context")),
         }
 
     @staticmethod
@@ -532,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),
@@ -541,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,
@@ -565,31 +691,63 @@ class AgentHTTPController:
                 status_code=400,
                 detail="run_id (with approval_token) or context_id is required.",
             )
+        # Deprecated context_id resume (L1 unification, 9.9.5): the legacy
+        # pause lives in the same durable approval store now. Token-less
+        # resume stays allowed for it — bound to the pausing user, and only
+        # for entries that were created through the legacy pause.
+        now_monotonic = time.monotonic()
         with self._pending_lock:
-            now = time.monotonic()
-            for context_id, pending in list(self._pending.items()):
-                if now - pending[4] >= self._pending_ttl_seconds:
-                    self._pending.pop(context_id, None)
-            entry = self._pending.get(req.context_id)
-            if entry and entry[3] == current_user:
-                self._pending.pop(req.context_id, None)
-        if not entry:
-            raise HTTPException(
-                status_code=404,
-                detail="Agent context not found or expired. Start a new request.",
-            )
+            entry = self._approvals.get(req.context_id)
+            if entry is None:
+                try:
+                    entry = self._restore_persisted_approval(req.context_id)
+                except HTTPException as exc:
+                    if exc.status_code == 410:
+                        # Legacy contract never had a distinct expiry answer.
+                        raise HTTPException(
+                            status_code=404,
+                            detail="Agent context not found or expired. Start a new request.",
+                        ) from exc
+                    raise
+            if entry is None or not entry.get("legacy_context"):
+                raise HTTPException(
+                    status_code=404,
+                    detail="Agent context not found or expired. Start a new request.",
+                )
+            if entry["user"] != current_user:
+                raise HTTPException(
+                    status_code=403,
+                    detail="Agent context belongs to another user.",
+                )
+            if now_monotonic >= entry["expires_monotonic"]:
+                self._approvals.pop(req.context_id, None)
+                try:
+                    self.run_store.delete(req.context_id)
+                except Exception:  # noqa: BLE001
+                    pass
+                raise HTTPException(
+                    status_code=404,
+                    detail="Agent context not found or expired. Start a new request.",
+                )
+            self._approvals.pop(req.context_id, None)
+            try:
+                self.run_store.delete(req.context_id)
+            except Exception as exc:  # noqa: BLE001
+                logging.warning("agent run store delete failed: %s", exc)
 
-        ctx, original_request, language_hint, original_user, _created_at = entry
-        if original_user != current_user:
-            raise HTTPException(
-                status_code=403,
-                detail="Agent context belongs to another user.",
-            )
+        ctx = entry["ctx"]
+        original_request = entry["req"]
+        language_hint = entry["language_hint"]
         if not req.approved:
             return {"status": "cancelled", "response": "사용자가 계획을 취소했습니다."}
         if req.modified_plan:
-            ctx.plan = req.modified_plan
-            ctx.transcript[-1].update(ctx.plan)
+            plan, plan_fixes = normalize_plan(req.modified_plan, original_request.message)
+            ctx.plan = plan
+            ctx.transcript.append({
+                "state": AgentState.WAITING_APPROVAL.value,
+                "edited_plan": True,
+                **({"plan_fixes": plan_fixes} if plan_fixes else {}),
+            })
         ctx.executing_model = req.executing_model or ctx.executing_model
         ctx.reviewing_model = req.reviewing_model or ctx.reviewing_model
         # The authenticated owner of this pending context explicitly approved

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):
@@ -45,7 +54,7 @@ class AgentResumeRequest(BaseModel):
     modified_plan: Optional[dict] = None
     executing_model: Optional[str] = None
     reviewing_model: Optional[str] = None
-    # awaiting_approval flow (v9.10): run_id + short-TTL approval token.
+    # awaiting_approval flow (v9.9.x): run_id + short-TTL approval token.
     run_id: Optional[str] = None
     approval_token: Optional[str] = None
     approve: Optional[bool] = None

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 {}),
             }
         )