ltcai 9.9.2 → 9.9.3

package/latticeai/api/chat_intents.py

@@ -23,6 +23,9 @@ from latticeai.core.file_generation import (
     PREVIEWABLE_EXTENSIONS,
     generate_file_content,
     infer_file_target,
+    infer_project_manifest,
+    repair_bundle_references,
+    validate_project_bundle,
 )
 
 
@@ -80,6 +83,7 @@ class ChatIntentController:
         agent_controller: Any,
         agent_root: Path,
         ingestion_pipeline: Any = None,
+        funnel_metrics: Any = None,
     ) -> None:
         self.router = model_router
         self.config = config
@@ -99,6 +103,16 @@ class ChatIntentController:
         self.agent_controller = agent_controller
         self.agent_root = Path(agent_root)
         self.ingestion_pipeline = ingestion_pipeline
+        self.funnel_metrics = funnel_metrics
+
+    def _funnel_increment(self, name: str) -> None:
+        """UX funnel counter (backlog #16) — advisory, never raises."""
+        if self.funnel_metrics is None:
+            return
+        try:
+            self.funnel_metrics.increment(name)
+        except Exception as exc:  # noqa: BLE001 — metrics must never break chat
+            logging.warning("funnel metrics increment failed: %s", exc)
 
     def no_model_response(self) -> JSONResponse:
         detail = "No model loaded. Call /models/load first."
@@ -235,7 +249,21 @@ class ChatIntentController:
         # An explicit path ("report.txt") wins; otherwise infer one from an
         # explicit type keyword ("html 파일 만들어줘") so weak models never
         # have to drive the JSON tool loop just to create a file.
-        target_path = file_action_target(req.message) or infer_file_target(req.message)
+        explicit_target = file_action_target(req.message)
+        if explicit_target is None:
+            # Multi-file intent ("todo 앱 html+css+js") becomes a real linked
+            # project bundle instead of one inlined page. Single-type requests
+            # return None here and keep the unchanged single-file flow.
+            manifest = infer_project_manifest(req.message)
+            if manifest is not None:
+                return await self.direct_project_action(
+                    req,
+                    manifest,
+                    model_id=model_id,
+                    effective_email=effective_email,
+                    workspace_id=workspace_id,
+                )
+        target_path = explicit_target or infer_file_target(req.message)
         if not target_path:
             return None
         # Never silently overwrite: an existing target gets a _2/_3 suffix so
@@ -316,6 +344,7 @@ class ChatIntentController:
             workspace_id=workspace_id,
             conversation_id=getattr(req, "conversation_id", None),
         )
+        self._funnel_increment("real_file_delivered")
         self.notify("user", req.message, req.source)
         self.notify("assistant", answer, req.source)
         payload = {
@@ -354,6 +383,156 @@ class ChatIntentController:
             )
         return JSONResponse(content=payload)
 
+    async def direct_project_action(
+        self,
+        req: Any,
+        manifest: Dict[str, Any],
+        *,
+        model_id: Optional[str],
+        effective_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ):
+        """Artifact Loop: manifest → per-file generate/validate → bundle write.
+
+        Every file goes through the same model-agnostic pipeline as the
+        single-file path; after generation the *bundle* is verified as a whole
+        (dangling href/src references are deterministically repaired first),
+        then written together under one project directory, exposed through the
+        standard ``artifacts[]`` contract, and downloadable as a zip.
+        """
+        if not model_id:
+            return self.no_model_response()
+        project_dir = next_available_path(self.agent_root, manifest["name"])
+        bundle_files = [str(f["path"]) for f in manifest["files"]]
+
+        async def _generate(context: str) -> str:
+            return str(
+                await self.router.generate_as(
+                    model_id,
+                    message="Return only the requested file content.",
+                    context=context,
+                    max_tokens=max(int(req.max_tokens or 0), 4096),
+                    temperature=min(req.temperature, 0.3),
+                )
+            )
+
+        contents: Dict[str, str] = {}
+        file_meta: Dict[str, Dict[str, Any]] = {}
+        for spec in manifest["files"]:
+            name = str(spec["path"])
+            request_text = f"{req.message}\n\nThis file's role: {spec.get('brief', '')}"
+            content, meta = await generate_file_content(
+                _generate,
+                target_path=name,
+                user_request=request_text,
+                bundle_files=bundle_files,
+            )
+            contents[name] = content
+            file_meta[name] = meta
+
+        contents, reference_fixes = repair_bundle_references(contents)
+        bundle_validation = validate_project_bundle(contents)
+
+        steps: List[Dict[str, Any]] = []
+        created_files: List[Dict[str, Any]] = []
+        artifacts: List[Dict[str, Any]] = []
+        brain_ingests: List[Dict[str, Any]] = []
+        for name, content in contents.items():
+            rel_path = f"{project_dir}/{name}"
+            try:
+                result = self.execute_tool(
+                    "write_file",
+                    {"path": rel_path, "content": content},
+                )
+            except self.tool_error as exc:
+                raise HTTPException(status_code=400, detail=str(exc)) from exc
+            final_path = result.get("path") or rel_path
+            steps.append({
+                "state": AgentState.EXECUTING.value,
+                "action": "write_file",
+                "args": {"path": rel_path},
+                "result": result,
+            })
+            created_files.append({
+                "path": final_path,
+                "filename": Path(final_path).name,
+                "bytes": result.get("bytes", 0),
+                "action": "write_file",
+            })
+            verdict = bundle_validation["files"].get(name, {})
+            artifacts.append({
+                "kind": "file",
+                "path": final_path,
+                "filename": Path(final_path).name,
+                "bytes": result.get("bytes", 0),
+                "previewable": Path(final_path).suffix.lower() in PREVIEWABLE_EXTENSIONS,
+                "valid": bool(verdict.get("valid", True)),
+                "repaired": bool(file_meta.get(name, {}).get("repaired")),
+            })
+            ingest = self._ingest_generated_file(
+                final_path,
+                content,
+                effective_email=effective_email,
+                workspace_id=workspace_id,
+                conversation_id=getattr(req, "conversation_id", None),
+            )
+            if ingest is not None:
+                brain_ingests.append({"path": final_path, **ingest})
+
+        file_list = ", ".join(Path(a["path"]).name for a in artifacts)
+        answer = (
+            f"{project_dir} 프로젝트를 만들었습니다 "
+            f"({len(artifacts)}개 파일: {file_list})."
+        )
+        if not bundle_validation["ok"]:
+            answer += " 일부 파일은 검증 경고가 있어 결과를 확인해 주세요."
+        repaired_any = any(a["repaired"] for a in artifacts)
+        if repaired_any:
+            answer += " (모델 출력이 불완전한 파일은 자동 보정을 거쳤습니다.)"
+
+        from urllib.parse import quote
+
+        payload: Dict[str, Any] = {
+            "status": "ok",
+            "response": answer,
+            "workspace": str(self.agent_root),
+            "steps": steps,
+            "state_history": [AgentState.EXECUTING.value, AgentState.DONE.value],
+            "final_state": AgentState.DONE.value,
+            "created_files": created_files,
+            "artifacts": artifacts,
+            "routed_to_agent": True,
+            "action_route": "direct_project_bundle",
+            "project": {
+                "dir": project_dir,
+                "files": bundle_files,
+                "zip_url": f"/tools/download_zip?path={quote(project_dir)}",
+                "bundle_validation": bundle_validation,
+                "reference_fixes": reference_fixes,
+            },
+            "generation": {
+                "files": file_meta,
+                "repaired": repaired_any,
+            },
+        }
+        if brain_ingests:
+            payload["brain_ingest"] = brain_ingests
+        self._funnel_increment("real_file_delivered")
+        self.notify("user", req.message, req.source)
+        self.notify("assistant", answer, req.source)
+        if req.stream:
+            return StreamingResponse(
+                agent_payload_stream(
+                    answer,
+                    payload,
+                    router=self.router,
+                    model_id=model_id,
+                ),
+                media_type="text/event-stream",
+                headers={"X-Model": model_id or "tool", "X-Routed-To": "agent"},
+            )
+        return JSONResponse(content=payload)
+
     def _ingest_generated_file(
         self,
         rel_path: str,
@@ -419,6 +598,15 @@ class ChatIntentController:
         )
         result = await self.agent_controller.agent(agent_request, request)
         answer = str(result.get("response") or "파일 작업을 처리했습니다.")
+        # UX funnel (backlog #16): a file-intent request that the agent loop
+        # finished without producing a single artifact is the "code-only"
+        # failure mode the >95% real-file goal watches. Paused/failed runs
+        # count neither way — they did not answer with code instead of files.
+        delivered = bool(result.get("created_files") or result.get("artifacts"))
+        if delivered:
+            self._funnel_increment("real_file_delivered")
+        elif str(result.get("status") or "") == "ok":
+            self._funnel_increment("code_only_responses")
         self.notify("user", req.message, req.source)
         self.notify("assistant", answer, req.source)
         result["routed_to_agent"] = True

package/latticeai/api/chat_stream.py

@@ -8,7 +8,7 @@ from typing import Any, AsyncIterator, Dict, Optional
 
 from fastapi.responses import JSONResponse, StreamingResponse
 
-from latticeai.api.chat_helpers import single_text_stream
+from latticeai.api.chat_helpers import assess_answer_grounding, single_text_stream
 
 
 def single_answer_response(req: Any, answer: str, *, model: str):
@@ -87,6 +87,7 @@ async def stream_chat(
         persisted_response = f"{persisted_response}\n\n[stream_error] {stream_error}"
 
     trace_record = None
+    grounding = None
     try:
         answer_trace = trace_seed or chat_service.build_graph_trace(
             req.message,
@@ -94,6 +95,19 @@ async def stream_chat(
             context,
             allowed_workspaces={workspace_id} if workspace_id else None,
         )
+        # Answer-citation binding (backlog #11): same honest verdict as the
+        # non-streaming path, recorded on the persisted trace + trailer.
+        try:
+            grounding = assess_answer_grounding(
+                full_response,
+                trace=answer_trace if isinstance(answer_trace, dict) else None,
+                context_quality=context_quality,
+            )
+            if isinstance(answer_trace, dict):
+                answer_trace["grounding"] = grounding
+        except Exception as exc:  # noqa: BLE001 — annotation must never break streaming
+            logging.warning("answer grounding assessment failed: %s", exc)
+            grounding = None
         trace_record = await chat_service.persist_answer(
             question=req.message,
             response=persisted_response,
@@ -114,6 +128,8 @@ async def stream_chat(
         trailer.update({"trace_id": trace_record["id"], "trace": trace_record})
     if context_quality is not None:
         trailer["context_quality"] = context_quality
+    if grounding is not None:
+        trailer["grounding"] = grounding
     if stream_error:
         trailer["error"] = stream_error
     yield f"data: {json.dumps(trailer, ensure_ascii=False)}\n\n"

package/latticeai/api/funnel_metrics.py

@@ -0,0 +1,31 @@
+"""Admin-only UX funnel metrics endpoint (backlog #16).
+
+Exposes :class:`~latticeai.services.funnel_metrics.FunnelMetricsService`
+snapshots at ``GET /api/admin/funnel-metrics``. Follows the admin router
+convention: gate through the injected ``require_admin`` callable, read-only,
+no side effects.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from fastapi import APIRouter, Request
+
+
+def create_funnel_metrics_router(
+    *,
+    service: Any,
+    require_admin: Callable[[Request], Any],
+) -> APIRouter:
+    router = APIRouter()
+
+    @router.get("/api/admin/funnel-metrics")
+    async def funnel_metrics(request: Request):
+        require_admin(request)
+        return service.snapshot()
+
+    return router
+
+
+__all__ = ["create_funnel_metrics_router"]

package/latticeai/api/knowledge_graph.py

@@ -28,6 +28,16 @@ class KnowledgeGraphIngestRequest(BaseModel):
     metadata: Optional[Dict[str, Any]] = None
 
 
+class CurateNoiseRequest(BaseModel):
+    # Dry-run by default: the job *reports* removals until explicitly applied.
+    dry_run: bool = True
+    max_df_ratio: float = 0.8
+    min_doc_frequency: int = 1
+    min_corpus_docs: int = 5
+    normalize_verbs: bool = True
+    max_removals: int = 200
+
+
 def _workspace_scope_from_request(request: Request) -> Optional[str]:
     header = request.headers.get("X-Workspace-Id")
     if header and header.strip():
@@ -143,6 +153,26 @@ def create_knowledge_graph_router(
         (require_admin or require_user)(request)
         return graph().curate()
 
+    @router.post("/knowledge-graph/curate/noise")
+    async def knowledge_graph_curate_noise(req: CurateNoiseRequest, request: Request):
+        """Noise-reduction curation job (backlog #10).
+
+        Dry-run by default: reports which heuristic concept nodes would be
+        removed (low IDF / below the frequency floor) and which relation
+        verbs would be normalized, without changing the graph. Set
+        ``dry_run=false`` to apply. User-created nodes are never removed.
+        Administrative like ``/knowledge-graph/curate`` when roles exist.
+        """
+        (require_admin or require_user)(request)
+        return graph().curate_noise(
+            dry_run=req.dry_run,
+            max_df_ratio=req.max_df_ratio,
+            min_doc_frequency=req.min_doc_frequency,
+            min_corpus_docs=req.min_corpus_docs,
+            normalize_verbs=req.normalize_verbs,
+            max_removals=req.max_removals,
+        )
+
     @router.get("/knowledge-graph/provenance/coverage")
     async def knowledge_graph_provenance_coverage(request: Request):
         require_user(request)

package/latticeai/api/local_files.py

@@ -49,6 +49,16 @@ class FolderIngestRequest(BaseModel):
     approval_token: Optional[str] = None
 
 
+class FolderWatchEnableRequest(BaseModel):
+    path: str
+    recursive: bool = True
+    workspace_id: Optional[str] = None
+    # Watching continuously reads local disk → same approval dance as
+    # /api/ingestion/folder. This is the explicit opt-in the review requires.
+    approved: bool = False
+    approval_token: Optional[str] = None
+
+
 def create_local_files_router(
     *,
     require_user,
@@ -64,9 +74,26 @@ def create_local_files_router(
     data_dir: Optional[Path] = None,
     allowed_workspaces_for=None,
     workspace_service=None,
+    folder_watch=None,
 ) -> APIRouter:
     router = APIRouter()
 
+    # ── opt-in folder watch service (backlog #8) ──────────────────────────────
+    # Constructed here (not injected) unless a test provides one; restore()
+    # only resumes watches persisted with the explicit opt-in — a fresh
+    # data_dir never starts a polling thread.
+    if folder_watch is None and ingestion_pipeline is not None and data_dir is not None:
+        try:
+            from latticeai.services.folder_watch import FolderWatchService
+
+            folder_watch = FolderWatchService(
+                pipeline=ingestion_pipeline,
+                config_path=Path(data_dir) / "folder_watch.json",
+            )
+            folder_watch.restore()
+        except Exception:  # noqa: BLE001 — watch mode is optional, never blocks routes
+            folder_watch = None
+
     @router.get("/api/local-agent/status")
     async def local_agent_status(request: Request):
         """Real on-device runtime status — the 'Local Agent' is the Lattice
@@ -307,6 +334,68 @@ def create_local_files_router(
             )
         return summary
 
+    # ── folder watch mode: opt-in, off by default (backlog #8) ────────────────
+    def _require_folder_watch():
+        _require_pipeline()
+        if folder_watch is None:
+            raise HTTPException(status_code=503, detail="Folder watch service is unavailable.")
+
+    @router.get("/api/ingestion/watch")
+    async def folder_watch_status(request: Request):
+        """Watch-mode status: stored opt-ins, poller state, last scan results."""
+        require_user(request)
+        _require_folder_watch()
+        return folder_watch.status()
+
+    @router.post("/api/ingestion/watch")
+    async def folder_watch_enable(req: FolderWatchEnableRequest, request: Request):
+        """Explicitly opt a previously-ingested folder into watch mode.
+
+        Follows the same local-read approval dance as ``/api/ingestion/folder``.
+        Enabling snapshots the folder as the baseline; only *future* new or
+        changed files are re-ingested (through the normal pipeline, with the
+        watch owner's workspace scope).
+        """
+        current_user = permission_gateway.require_local_user(request)
+        _require_folder_watch()
+        workspace_id = _ingestion_write_workspace(request, req.workspace_id, current_user)
+        path = (req.path or "").strip()
+        if not path:
+            raise HTTPException(status_code=400, detail="path is required.")
+        if not req.approved:
+            return permission_gateway.local_permission_response(path, "read", current_user)
+        permission_gateway.require_local_approval(
+            token=req.approval_token,
+            path=path,
+            action="read",
+            user_email=current_user,
+        )
+        result = folder_watch.enable(
+            path,
+            owner=current_user or None,
+            workspace_id=workspace_id,
+            recursive=req.recursive,
+        )
+        if result.get("status") != "ok":
+            raise HTTPException(status_code=400, detail=result.get("detail") or "watch enable failed")
+        return result
+
+    @router.delete("/api/ingestion/watch")
+    async def folder_watch_disable(
+        request: Request,
+        watch_id: Optional[str] = None,
+        path: Optional[str] = None,
+    ):
+        """Opt back out of watch mode (removes the stored consent record)."""
+        require_user(request)
+        _require_folder_watch()
+        if not watch_id and not path:
+            raise HTTPException(status_code=400, detail="watch_id or path is required.")
+        result = folder_watch.disable(watch_id=watch_id, path=path)
+        if result.get("status") == "not_found":
+            raise HTTPException(status_code=404, detail="watch not found")
+        return result
+
     @router.post("/local/write")
     async def local_write_endpoint(req: LocalWriteRequest, request: Request):
         current_user = permission_gateway.require_local_user(request)
@@ -353,6 +442,7 @@ def create_local_files_router(
 
 __all__ = [
     "FolderIngestRequest",
+    "FolderWatchEnableRequest",
     "LocalAccessRequest",
     "LocalWriteRequest",
     "create_local_files_router",

package/latticeai/api/setup.py

@@ -17,7 +17,15 @@ from latticeai.setup.auto_setup import (
     verify as auto_setup_verify,
 )
 from latticeai.models.router import parse_model_ref
+from latticeai.setup.demo_corpus import (
+    DEMO_DOCUMENTS,
+    DEMO_METADATA_FLAG,
+    DEMO_URI_PREFIX,
+    demo_source_uri,
+    suggested_questions,
+)
 from latticeai.setup.wizard import get_recommendations, install_stream, open_url, scan_environment
+from lattice_brain.ingestion import IngestionItem
 
 
 class SetupInstallRequest(BaseModel):
@@ -25,7 +33,18 @@ class SetupInstallRequest(BaseModel):
     confirmation_token: Optional[str] = None
 
 
-def create_setup_router(*, model_router, require_user) -> APIRouter:
+class DemoCorpusRequest(BaseModel):
+    workspace_id: Optional[str] = None
+
+
+def create_setup_router(
+    *,
+    model_router,
+    require_user,
+    ingestion_pipeline=None,
+    knowledge_graph=None,
+    workspace_service=None,
+) -> APIRouter:
     api_router = APIRouter()
     router = model_router
 
@@ -157,6 +176,120 @@ def create_setup_router(*, model_router, require_user) -> APIRouter:
         return {"status": "ok", "opened": url, "mcp_id": mcp_id}
     
     
+    # ── First Value Loop demo corpus (backlog #3, review §3.3 P0) ────────────
+
+    def _require_demo_pipeline():
+        if ingestion_pipeline is None or not ingestion_pipeline.available():
+            raise HTTPException(
+                status_code=503, detail="Knowledge Graph ingestion is disabled.",
+            )
+        if knowledge_graph is None:
+            raise HTTPException(status_code=503, detail="Knowledge Graph is disabled.")
+
+    def _demo_workspace(request: Request, body_workspace: Optional[str], user: str) -> Optional[str]:
+        header = request.headers.get("X-Workspace-Id")
+        header = header.strip() if header and header.strip() else None
+        supplied = [value for value in (body_workspace, header) if value]
+        if len(set(supplied)) > 1:
+            raise HTTPException(status_code=403, detail="Workspace selectors must match.")
+        requested = supplied[0] if supplied else None
+        if workspace_service is None:
+            return requested
+        try:
+            return workspace_service.resolve_write_scope(requested, user or None)
+        except PermissionError as exc:
+            raise HTTPException(status_code=403, detail=str(exc)) from exc
+
+    @api_router.get("/api/setup/demo-corpus")
+    async def demo_corpus_status(request: Request):
+        """Whether the demo corpus is installed + the suggestion chips."""
+        require_user(request)
+        _require_demo_pipeline()
+        installed = knowledge_graph.find_documents_by_uri_prefix(DEMO_URI_PREFIX)
+        return {
+            "installed": bool(installed),
+            "documents": installed,
+            "document_count": len(installed),
+            "suggested_questions": suggested_questions(),
+        }
+
+    @api_router.post("/api/setup/demo-corpus")
+    async def demo_corpus_install(request: Request, req: Optional[DemoCorpusRequest] = None):
+        """One-click ingest of the 3 built-in demo documents (idempotent).
+
+        Every document goes through the normal IngestionPipeline door with
+        ``demo://`` provenance so it is honest (real nodes, real chunks, real
+        provenance) and removable via DELETE. Re-POSTing reports duplicates
+        instead of duplicating.
+        """
+        user = require_user(request)
+        _require_demo_pipeline()
+        workspace_id = _demo_workspace(request, req.workspace_id if req else None, user)
+        results = []
+        ingested = 0
+        duplicates = 0
+        failed = 0
+        for doc in DEMO_DOCUMENTS:
+            result = ingestion_pipeline.ingest(
+                IngestionItem(
+                    source_type="note",
+                    title=doc["title"],
+                    text=doc["text"],
+                    source_uri=demo_source_uri(doc["id"]),
+                    owner=user or None,
+                    workspace_id=workspace_id,
+                    metadata={DEMO_METADATA_FLAG: True, "demo_id": doc["id"]},
+                ),
+                user_email=user or None,
+            )
+            if result.status != "ok":
+                failed += 1
+            elif result.duplicate:
+                duplicates += 1
+            else:
+                ingested += 1
+            results.append({
+                "demo_id": doc["id"],
+                "title": doc["title"],
+                "source_uri": demo_source_uri(doc["id"]),
+                "status": result.status,
+                "node_id": result.node_id,
+                "duplicate": result.duplicate,
+                "chunk_count": result.chunk_count,
+                "detail": result.detail,
+            })
+        status = "ok" if failed == 0 else ("partial" if (ingested + duplicates) else "failed")
+        return {
+            "status": status,
+            "ingested": ingested,
+            "duplicates": duplicates,
+            "failed": failed,
+            "documents": results,
+            "suggested_questions": suggested_questions(),
+        }
+
+    @api_router.delete("/api/setup/demo-corpus")
+    async def demo_corpus_remove(request: Request):
+        """Remove every demo document (node + chunks + edges + orphan source)."""
+        require_user(request)
+        _require_demo_pipeline()
+        installed = knowledge_graph.find_documents_by_uri_prefix(DEMO_URI_PREFIX)
+        removed = []
+        for doc in installed:
+            outcome = knowledge_graph.delete_document_tree(doc["id"])
+            removed.append({
+                "node_id": doc["id"],
+                "title": doc.get("title"),
+                "source_uri": doc.get("source_uri"),
+                "status": outcome.get("status"),
+                "removed_nodes": outcome.get("removed_nodes", 0),
+            })
+        return {
+            "status": "ok",
+            "removed_count": len(removed),
+            "removed": removed,
+        }
+
     @api_router.post("/permissions/open/{permission_id}")
     async def open_permission_settings(permission_id: str, request: Request):
         require_user(request)

package/latticeai/api/tools.py

@@ -11,7 +11,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from fastapi import APIRouter, File, HTTPException, Request, UploadFile
-from fastapi.responses import FileResponse
+from fastapi.responses import FileResponse, Response
 from pydantic import BaseModel
 
 from latticeai.api.computer_use import create_computer_use_router
@@ -543,8 +543,38 @@ def create_tools_router(
             filename=target.name,
             media_type="application/octet-stream",
         )
-    
-    
+
+
+    @api_router.get("/tools/download_zip")
+    async def tools_download_zip(path: str, request: Request):
+        """Serve a generated project directory from the agent workspace as a zip.
+
+        The multi-file artifact loop writes bundles like ``todo-app/`` —
+        this is their one-click download. Path confinement mirrors
+        ``/tools/download``: anything outside the workspace is refused.
+        """
+        require_user(request)
+        from urllib.parse import unquote
+
+        from latticeai.tools.filesystem import zip_workspace_dir
+
+        rel = unquote(path).lstrip("/")
+        target = (AGENT_ROOT / rel).resolve()
+        if AGENT_ROOT not in target.parents and target != AGENT_ROOT:
+            raise HTTPException(status_code=403, detail="경로가 작업 공간 밖입니다.")
+        if not target.exists() or not target.is_dir():
+            raise HTTPException(status_code=404, detail="디렉터리가 없습니다.")
+        try:
+            payload, filename = zip_workspace_dir(rel)
+        except ToolError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+        return Response(
+            content=payload,
+            media_type="application/zip",
+            headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+        )
+
+
     @api_router.post("/upload/document")
     async def upload_document(request: Request, file: UploadFile = File(...)):
         current_user = require_user(request)