ltcai 0.1.23 → 0.1.24

package/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-  <img src="docs/images/logo.svg" alt="Lattice AI" width="280"/>
+  <img src="https://raw.githubusercontent.com/TaeSooPark-PTS/LatticeAI/main/docs/images/logo.svg" alt="Lattice AI" width="280"/>
   <br/>
   <strong>Your personal AI workspace server — local & cloud, one stack.</strong>
   <br/><br/>
@@ -7,7 +7,7 @@
 [![PyPI](https://img.shields.io/pypi/v/ltcai?label=PyPI&color=blue)](https://pypi.org/project/ltcai/)
 [![PyPI Downloads](https://img.shields.io/pypi/dm/ltcai?label=PyPI%20downloads)](https://pypi.org/project/ltcai/)
 [![npm](https://img.shields.io/npm/v/ltcai?label=npm)](https://www.npmjs.com/package/ltcai)
-[![VS Code](https://img.shields.io/badge/VS%20Code%20Marketplace-v0.1.23-blue?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=parktaesoo.ltcai)
+[![VS Code](https://vsmarketplacebadges.dev/version-short/parktaesoo.ltcai.svg)](https://marketplace.visualstudio.com/items?itemName=parktaesoo.ltcai)
 [![Open VSX](https://img.shields.io/open-vsx/v/parktaesoo/ltcai?label=Open%20VSX)](https://open-vsx.org/extension/parktaesoo/ltcai)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green)](./LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue)](https://www.python.org/)
@@ -32,9 +32,9 @@
 
 <table>
 <tr>
-<td width="33%"><b>Chat UI</b><br/><img src="docs/images/screenshot-chat.png" alt="Lattice AI Chat" width="100%"/></td>
-<td width="33%"><b>Admin Dashboard</b><br/><img src="docs/images/screenshot-admin.png" alt="Admin Dashboard" width="100%"/></td>
-<td width="33%"><b>Data Graph (Graph RAG)</b><br/><img src="docs/images/screenshot-graph.png" alt="Knowledge Graph" width="100%"/></td>
+<td width="33%"><b>Chat UI</b><br/><img src="https://raw.githubusercontent.com/TaeSooPark-PTS/LatticeAI/main/docs/images/screenshot-chat.png" alt="Lattice AI Chat" width="100%"/></td>
+<td width="33%"><b>Admin Dashboard</b><br/><img src="https://raw.githubusercontent.com/TaeSooPark-PTS/LatticeAI/main/docs/images/screenshot-admin.png" alt="Admin Dashboard" width="100%"/></td>
+<td width="33%"><b>Data Graph (Graph RAG)</b><br/><img src="https://raw.githubusercontent.com/TaeSooPark-PTS/LatticeAI/main/docs/images/screenshot-graph.png" alt="Knowledge Graph" width="100%"/></td>
 </tr>
 </table>
 
@@ -42,6 +42,8 @@
 
 ## ⚡ Quick Start (30 seconds)
 
+**Python / PyPI**
+
 ```bash
 # Install (cloud models)
 pip install ltcai
@@ -49,21 +51,43 @@ pip install ltcai
 # Install (+ Apple Silicon local models)
 pip install "ltcai[local]"
 
+# Verify environment
+LTCAI doctor
+
 # Start server
 LTCAI
 # → http://localhost:4825
+```
 
-# Start with public HTTPS tunnel (Cloudflare, no account needed)
-LTCAI --tunnel
-# → https://xxxx.trycloudflare.com
+**Node / npm**
+
+```bash
+npm install -g ltcai
+LTCAI doctor
+LTCAI
 ```
 
+**VS Code / Cursor**
+
+1. Install **Lattice AI** from [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=parktaesoo.ltcai) or [Open VSX](https://open-vsx.org/extension/parktaesoo/ltcai)
+2. Start the local server with `LTCAI`
+3. Run `Lattice AI: Open Chat` (`Cmd+Shift+A`) in your editor
+
 **First run:** open `http://localhost:4825` → sign up → first account auto-becomes admin → pick a model → start chatting.
 
+**Public HTTPS tunnel (Cloudflare, no account needed):**
+
+```bash
+LTCAI --tunnel
+# → https://xxxx.trycloudflare.com
+```
+
 ---
 
 ## 🆚 Why Lattice AI?
 
+Comparison is based on public product behavior as of 2026-05.
+
 | | Lattice AI | Open WebUI | Continue.dev | GitHub Copilot |
 |---|:---:|:---:|:---:|:---:|
 | Local model (offline, Apple Silicon) | ✅ | ✅ | ✅ | ❌ |
@@ -270,7 +294,7 @@ Or: `./start_ai.sh` (auto-restart + caffeinate)
 | VS Code Marketplace | [marketplace.visualstudio.com](https://marketplace.visualstudio.com/items?itemName=parktaesoo.ltcai) |
 | Open VSX | [open-vsx.org](https://open-vsx.org/extension/parktaesoo/ltcai) |
 
-Current version: **0.1.23** — [Changelog](docs/CHANGELOG.md)
+Current version: **0.1.24** — [Changelog](docs/CHANGELOG.md)
 
 ---
 

package/docs/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.1.24] - 2026-05-24
+
+### 안정화 및 UX 개선
+
+- **로컬 파일 인증 강화** — `/local/list` · `/local/read` · `/local/write` · `/local/serve`에서 로그인 세션 필수화 (`_require_local_user` 헬퍼 도입)
+- **`GET /local/list` 라우트 추가** — smoke-test 및 브라우저 직접 호출 호환
+- **VS Code 배지 수정** — shields.io `visual-studio-marketplace` 폐기 → `vsmarketplacebadges.dev`로 전환
+- **README 이미지 URL 안정화** — 로고·스크린샷을 `raw.githubusercontent.com` 절대 URL로 전환해 PyPI / npm / Marketplace 페이지에서도 표시
+- **Quick Start 분리** — PyPI / npm / VS Code 사용자의 첫 설치 경로를 각각 명확히 안내
+- **GitHub Actions Node 24** — CI 런타임을 Node 24로 업그레이드
+
+### Release
+- 배포 버전을 `0.1.24`로 상향
+- 대상 채널: `npm` · `PyPI` · `VS Code Marketplace` · `Open VSX`
+
 ## [0.1.23] - 2026-05-24
 
 ### Discord 권한 알림 시스템
@@ -19,12 +34,22 @@
 - **영어 README** 전면 재작성 — 한국어는 접을 수 있는 `<details>` 섹션으로 이동
 - **SVG 로고** 추가 (`docs/images/logo.svg`)
 - **경쟁 제품 비교표** — Lattice AI vs Open WebUI · Continue.dev · GitHub Copilot
+- **Quick Start 분리** — PyPI / npm / VS Code 사용자의 첫 설치 경로를 각각 명확히 안내
+- **비교표 기준 명시** — 공개 제품 동작 기준 시점을 README에 표기
+- **패키지 페이지 이미지 안정화** — README 이미지 URL을 GitHub raw URL로 전환해 PyPI / npm / Marketplace에서도 표시되도록 개선
+- **npm 패키지 정리** — 배포 tarball에서 테스트/캐시 파일 제외
 - **실제 UI 스크린샷 3장** — Chat UI · Admin Dashboard · Data Graph (Playwright 2x 캡처)
 - **VS Code 익스텐션 카테고리** `Other` → `AI, Machine Learning, Chat, Other`
 - **VS Code 익스텐션 키워드** 8개 → 16개 (copilot, apple-silicon, groq, graph-rag 등)
 - **VS Code 익스텐션 README** 전면 재작성 (기능표, 비교표, 모델 목록)
 - 구버전 `.tgz` / `.vsix` 빌드 파일 삭제
 
+### CI / 보안 안정화
+
+- `/local/list` `GET` smoke-test 호환 라우트 추가
+- `/local/list`, `/local/read`, `/local/write`, `/local/serve`는 로컬 개발 모드에서도 로그인 세션을 요구하도록 강화
+- GitHub Actions integration smoke test 실패 원인 수정
+
 ### Release
 - 배포 버전을 `0.1.23`으로 상향
 - 대상 채널: `npm` · `PyPI` · `VS Code Marketplace` · `Open VSX`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ltcai",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "description": "Lattice AI local MLX/cloud LLM workspace server",
   "homepage": "https://github.com/TaeSooPark-PTS/LatticeAI#readme",
   "repository": {
@@ -50,7 +50,6 @@
     "tools.py",
     "codex_telegram_bot.py",
     "skills/",
-    "tests/",
     "static/account.html",
     "static/chat.html",
     "static/admin.html",

package/server.py

@@ -5631,6 +5631,13 @@ def _local_permission_response(path: str, action: str, user_email: str, content:
     }
 
 
+def _require_local_user(request: Request) -> str:
+    email = get_current_user(request)
+    if not email:
+        raise HTTPException(status_code=401, detail="로컬 파일 접근은 로그인 세션이 필요합니다.")
+    return email
+
+
 def _require_local_approval(
     *,
     token: Optional[str],
@@ -5773,16 +5780,22 @@ async def permissions_status(token: str, request: Request):
 
 @app.post("/local/list")
 async def local_list_endpoint(req: LocalAccessRequest, request: Request):
-    current_user = require_user(request)
+    current_user = _require_local_user(request)
     if not req.approved:
         return _local_permission_response(req.path, "list", current_user)
     _require_local_approval(token=req.approval_token, path=req.path, action="list", user_email=current_user)
     return _tool_response(local_list, req.path)
 
 
+@app.get("/local/list")
+async def local_list_get_endpoint(path: str, request: Request):
+    current_user = _require_local_user(request)
+    return _local_permission_response(path, "list", current_user)
+
+
 @app.post("/local/read")
 async def local_read_endpoint(req: LocalAccessRequest, request: Request):
-    current_user = require_user(request)
+    current_user = _require_local_user(request)
     if not req.approved:
         return _local_permission_response(req.path, "read", current_user)
     _require_local_approval(token=req.approval_token, path=req.path, action="read", user_email=current_user)
@@ -5792,7 +5805,7 @@ async def local_read_endpoint(req: LocalAccessRequest, request: Request):
 @app.get("/local/serve")
 async def local_serve_file(path: str, request: Request, approval_token: Optional[str] = None):
     """Serve a local file (images etc.) directly for browser preview."""
-    current_user = require_user(request)
+    current_user = _require_local_user(request)
     _require_local_approval(token=approval_token, path=path, action="read", user_email=current_user)
     target = Path(path).expanduser().resolve()
     if not target.exists() or not target.is_file():
@@ -5802,7 +5815,7 @@ async def local_serve_file(path: str, request: Request, approval_token: Optional
 
 @app.post("/local/write")
 async def local_write_endpoint(req: LocalWriteRequest, request: Request):
-    current_user = require_user(request)
+    current_user = _require_local_user(request)
     if not req.approved:
         return _local_permission_response(req.path, "write", current_user, req.content)
     _require_local_approval(

package/tests/integration/test_api.py

@@ -1,94 +0,0 @@
-"""Integration tests for FastAPI endpoints.
-
-Run against a live server:  pytest tests/integration/ --base-url http://localhost:8899
-Default base URL falls back to http://localhost:8899 if flag not provided.
-"""
-import os
-import pytest
-import httpx
-
-BASE_URL = os.environ.get("LTCAI_TEST_BASE_URL", "http://localhost:8899")
-
-
-def _session_cookie() -> dict:
-    """Return session cookie if LTCAI_TEST_SESSION env var is set, else empty dict."""
-    sid = os.environ.get("LTCAI_TEST_SESSION", "")
-    return {"session_id": sid} if sid else {}
-
-
-@pytest.fixture(scope="session")
-def client():
-    with httpx.Client(base_url=BASE_URL, cookies=_session_cookie(), timeout=15) as c:
-        yield c
-
-
-# ---------------------------------------------------------------------------
-# Health / Info
-# ---------------------------------------------------------------------------
-
-def test_health(client):
-    r = client.get("/health")
-    assert r.status_code == 200
-    data = r.json()
-    assert "status" in data
-
-
-def test_mode_endpoint(client):
-    r = client.get("/mode")
-    assert r.status_code == 200
-    data = r.json()
-    assert "model" in data or "mode" in data
-
-
-def test_runtime_features(client):
-    r = client.get("/runtime_features")
-    assert r.status_code == 200
-
-
-# ---------------------------------------------------------------------------
-# Local filesystem endpoints
-# ---------------------------------------------------------------------------
-
-def test_local_list_home(client):
-    r = client.get("/local/list", params={"path": "~"})
-    # 200 if authenticated, 401/403 if no session
-    assert r.status_code in (200, 401, 403)
-
-
-def test_local_list_requires_auth(client):
-    """Without a session cookie the endpoint must reject the request."""
-    r = httpx.get(f"{BASE_URL}/local/list", params={"path": "~"}, timeout=10)
-    assert r.status_code in (401, 403)
-
-
-def test_local_serve_missing_file(client):
-    r = client.get("/local/serve", params={"path": "/nonexistent_lattice_ai_test_xyz.txt"})
-    assert r.status_code in (400, 401, 403, 404)
-
-
-# ---------------------------------------------------------------------------
-# /tools/read_document
-# ---------------------------------------------------------------------------
-
-def test_read_document_missing(client):
-    r = client.post("/tools/read_document", json={"path": "/nonexistent_lattice_ai_doc.txt"})
-    assert r.status_code in (400, 401, 403, 404, 422)
-
-
-# ---------------------------------------------------------------------------
-# /chat — smoke test (no model required)
-# ---------------------------------------------------------------------------
-
-def test_chat_requires_message(client):
-    r = client.post("/chat", json={})
-    # Missing message → 422 validation error or 401 unauth
-    assert r.status_code in (401, 403, 422)
-
-
-# ---------------------------------------------------------------------------
-# /agent — smoke test
-# ---------------------------------------------------------------------------
-
-def test_agent_requires_task(client):
-    r = client.post("/agent", json={})
-    assert r.status_code in (401, 403, 422)

package/tests/unit/test_security.py

@@ -1,193 +0,0 @@
-"""Unit tests for security-sensitive helpers in server.py."""
-import sys
-import time
-import pytest
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).parent.parent.parent))
-
-from server import (
-    _bytes_match_extension,
-    _rate_buckets,
-    enforce_rate_limit,
-    hash_password,
-    verify_password,
-    _agent_risk,
-    _host_is_loopback,
-    _local_permission_response,
-    _require_local_approval,
-    _LOCAL_WRITE_BLOCKED_PREFIXES,
-)
-from fastapi import HTTPException
-
-
-# ---------------------------------------------------------------------------
-# Password hashing
-# ---------------------------------------------------------------------------
-
-def test_password_hash_roundtrip():
-    h = hash_password("hunter2")
-    assert verify_password("hunter2", h)
-    assert not verify_password("wrong", h)
-
-
-def test_password_hash_not_plaintext():
-    h = hash_password("hunter2")
-    assert "hunter2" not in h
-    assert ":" in h  # salt:hash format
-
-
-def test_password_hash_unique_per_call():
-    """Same input must yield different hashes (salted)."""
-    h1 = hash_password("same")
-    h2 = hash_password("same")
-    assert h1 != h2
-    assert verify_password("same", h1)
-    assert verify_password("same", h2)
-
-
-# ---------------------------------------------------------------------------
-# MIME / magic-number sniffing
-# ---------------------------------------------------------------------------
-
-def test_bytes_match_pdf():
-    assert _bytes_match_extension(b"%PDF-1.7\n...", ".pdf")
-
-
-def test_bytes_match_pdf_rejects_zip_bytes():
-    assert not _bytes_match_extension(b"PK\x03\x04...", ".pdf")
-
-
-def test_bytes_match_docx_is_zip():
-    assert _bytes_match_extension(b"PK\x03\x04...", ".docx")
-
-
-def test_bytes_match_png():
-    assert _bytes_match_extension(b"\x89PNG\r\n\x1a\nrest", ".png")
-
-
-def test_bytes_match_txt_skips_check():
-    """Text-like formats have no magic — always accepted."""
-    assert _bytes_match_extension(b"anything goes", ".txt")
-    assert _bytes_match_extension(b"anything goes", ".md")
-    assert _bytes_match_extension(b"anything goes", ".csv")
-
-
-# ---------------------------------------------------------------------------
-# Rate limiting
-# ---------------------------------------------------------------------------
-
-def test_rate_limit_allows_within_capacity():
-    _rate_buckets.clear()
-    for _ in range(10):
-        enforce_rate_limit("test_user@example.com", "agent")  # capacity 10
-
-
-def test_rate_limit_blocks_over_capacity():
-    _rate_buckets.clear()
-    for _ in range(10):
-        enforce_rate_limit("burst_user@example.com", "agent")
-    with pytest.raises(HTTPException) as exc:
-        enforce_rate_limit("burst_user@example.com", "agent")
-    assert exc.value.status_code == 429
-    assert "Retry-After" in exc.value.headers
-
-
-def test_rate_limit_skips_unauth():
-    """Empty email = no rate-limit (anon health-check style)."""
-    _rate_buckets.clear()
-    for _ in range(200):
-        enforce_rate_limit("", "agent")  # never raises
-
-
-# ---------------------------------------------------------------------------
-# Harness risk classification
-# ---------------------------------------------------------------------------
-
-def test_agent_risk_read_only_is_low():
-    assert _agent_risk("local_read", {"path": "/tmp/x"}) == "low"
-    assert _agent_risk("list_dir", {}) == "low"
-
-
-def test_agent_risk_write_is_medium():
-    assert _agent_risk("write_file", {"path": "out.txt"}) == "medium"
-    assert _agent_risk("local_write", {"path": "/tmp/safe.txt"}) == "medium"
-
-
-def test_agent_risk_run_command_is_high():
-    assert _agent_risk("run_command", {"command": "ls"}) == "high"
-
-
-def test_agent_risk_system_path_write_upgraded_to_high():
-    for prefix in _LOCAL_WRITE_BLOCKED_PREFIXES:
-        risk = _agent_risk("local_write", {"path": prefix + "evil.txt"})
-        assert risk == "high", f"prefix {prefix} should upgrade local_write to high"
-
-
-def test_agent_risk_unknown_action_defaults_medium():
-    assert _agent_risk("nonexistent_tool_xyz", {}) == "medium"
-
-
-# ---------------------------------------------------------------------------
-# Network exposure / local file approvals
-# ---------------------------------------------------------------------------
-
-def test_host_loopback_detection():
-    assert _host_is_loopback("127.0.0.1")
-    assert _host_is_loopback("localhost")
-    assert not _host_is_loopback("0.0.0.0")
-    assert not _host_is_loopback("192.168.0.2")
-
-
-def test_local_approval_token_allows_exact_scope(tmp_path):
-    target = tmp_path / "note.txt"
-    target.write_text("hello")
-    user = "alice@example.com"
-    approval = _local_permission_response(str(target), "read", user)
-    from server import _local_approvals
-    _local_approvals[approval["approval_token"]]["approved"] = True
-
-    _require_local_approval(
-        token=approval["approval_token"],
-        path=str(target),
-        action="read",
-        user_email=user,
-    )
-
-
-def test_local_approval_token_rejects_wrong_path(tmp_path):
-    allowed = tmp_path / "allowed.txt"
-    denied = tmp_path / "denied.txt"
-    allowed.write_text("allowed")
-    denied.write_text("denied")
-    user = "alice@example.com"
-    approval = _local_permission_response(str(allowed), "read", user)
-    from server import _local_approvals
-    _local_approvals[approval["approval_token"]]["approved"] = True
-
-    with pytest.raises(HTTPException) as exc:
-        _require_local_approval(
-            token=approval["approval_token"],
-            path=str(denied),
-            action="read",
-            user_email=user,
-        )
-    assert exc.value.status_code == 403
-
-
-def test_local_write_approval_binds_content(tmp_path):
-    target = tmp_path / "out.txt"
-    user = "alice@example.com"
-    approval = _local_permission_response(str(target), "write", user, "first")
-    from server import _local_approvals
-    _local_approvals[approval["approval_token"]]["approved"] = True
-
-    with pytest.raises(HTTPException) as exc:
-        _require_local_approval(
-            token=approval["approval_token"],
-            path=str(target),
-            action="write",
-            user_email=user,
-            content="changed",
-        )
-    assert exc.value.status_code == 403

package/tests/unit/test_setup_wizard.py

@@ -1,35 +0,0 @@
-import os
-import shutil
-
-import setup
-
-
-def test_scan_environment_includes_components_and_paths():
-    env = setup.scan_environment()
-
-    assert "components" in env
-    assert "python" in env["components"]
-    assert "official_url" in env["components"]["python"]
-    assert "path" in env
-    assert "active" in env["path"]
-
-
-def test_recommendations_include_components():
-    env = setup.scan_environment()
-    recs = setup.get_recommendations(env)
-
-    assert "components" in recs
-    assert any(item["id"].startswith("component_") for item in recs["components"])
-
-
-def test_repair_path_can_find_binary_from_common_dir(monkeypatch):
-    python_path = shutil.which("python3") or shutil.which("python")
-    assert python_path
-    python_dir = os.path.dirname(python_path)
-
-    monkeypatch.setattr(setup, "COMMON_PATH_DIRS", [python_dir])
-    monkeypatch.setenv("PATH", "")
-
-    setup.repair_path_for("python3" if python_path.endswith("python3") else "python")
-
-    assert python_dir in os.environ["PATH"].split(os.pathsep)

package/tests/unit/test_tools.py

@@ -1,320 +0,0 @@
-"""Unit tests for tools.py core functions."""
-import sys
-import pytest
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).parent.parent.parent))
-
-import tools as tools_module
-from tools import (
-    ToolError,
-    edit_file,
-    grep,
-    local_list,
-    local_read,
-    local_write,
-    read_document,
-    read_file,
-    todo_read,
-    todo_write,
-    write_file,
-)
-
-
-@pytest.fixture
-def workspace(tmp_path, monkeypatch):
-    """Redirect tools' AGENT_ROOT to a temp directory for the duration of a test."""
-    monkeypatch.setattr(tools_module, "AGENT_ROOT", tmp_path)
-    tools_module.ensure_agent_root()
-    return tmp_path
-
-
-# ---------------------------------------------------------------------------
-# local_list
-# ---------------------------------------------------------------------------
-
-def test_local_list_returns_items(tmp_path):
-    (tmp_path / "a.txt").write_text("hello")
-    (tmp_path / "sub").mkdir()
-    result = local_list(str(tmp_path))
-    names = [i["name"] for i in result["items"]]
-    assert "a.txt" in names
-    assert "sub" in names
-
-
-def test_local_list_dirs_before_files(tmp_path):
-    (tmp_path / "z_file.txt").write_text("x")
-    (tmp_path / "a_dir").mkdir()
-    result = local_list(str(tmp_path))
-    types = [i["type"] for i in result["items"]]
-    assert types[0] == "directory"
-
-
-def test_local_list_nonexistent_raises(tmp_path):
-    with pytest.raises(ToolError):
-        local_list(str(tmp_path / "does_not_exist"))
-
-
-def test_local_list_file_raises(tmp_path):
-    f = tmp_path / "file.txt"
-    f.write_text("x")
-    with pytest.raises(ToolError):
-        local_list(str(f))
-
-
-# ---------------------------------------------------------------------------
-# local_read
-# ---------------------------------------------------------------------------
-
-def test_local_read_text_file(tmp_path):
-    f = tmp_path / "hello.txt"
-    f.write_text("hello world")
-    result = local_read(str(f))
-    assert "hello world" in result["content"]
-    assert result["path"] == str(f)
-
-
-def test_local_read_missing_file_raises(tmp_path):
-    with pytest.raises(ToolError):
-        local_read(str(tmp_path / "missing.txt"))
-
-
-def test_local_read_tilde_expansion(tmp_path, monkeypatch):
-    monkeypatch.setenv("HOME", str(tmp_path))
-    f = tmp_path / "testfile.txt"
-    f.write_text("tilde test")
-    result = local_read("~/testfile.txt")
-    assert "tilde test" in result["content"]
-
-
-def test_local_read_returns_size(tmp_path):
-    f = tmp_path / "sized.txt"
-    f.write_text("abc")
-    result = local_read(str(f))
-    assert result["size"] == 3
-
-
-# ---------------------------------------------------------------------------
-# local_write
-# ---------------------------------------------------------------------------
-
-def test_local_write_creates_file(tmp_path):
-    target = tmp_path / "out.txt"
-    result = local_write(str(target), "new content")
-    assert target.read_text() == "new content"
-    assert "bytes" in result
-
-
-def test_local_write_overwrites_file(tmp_path):
-    target = tmp_path / "out.txt"
-    target.write_text("old")
-    local_write(str(target), "new")
-    assert target.read_text() == "new"
-
-
-def test_local_write_creates_parent_dirs(tmp_path):
-    target = tmp_path / "deep" / "nested" / "file.txt"
-    local_write(str(target), "deep write")
-    assert target.exists()
-
-
-def test_local_write_returns_path(tmp_path):
-    target = tmp_path / "x.txt"
-    result = local_write(str(target), "hi")
-    assert result["path"] == str(target)
-
-
-# ---------------------------------------------------------------------------
-# read_document
-# ---------------------------------------------------------------------------
-
-def test_read_document_plain_text(tmp_path):
-    f = tmp_path / "doc.txt"
-    f.write_text("plain text content")
-    result = read_document(str(f))
-    assert "plain text content" in result.get("text", "") or "plain text content" in str(result)
-
-
-def test_read_document_missing_file_raises(tmp_path):
-    with pytest.raises(ToolError):
-        read_document(str(tmp_path / "missing.pdf"))
-
-
-def test_read_document_csv(tmp_path):
-    f = tmp_path / "data.csv"
-    f.write_text("col1,col2\n1,2\n3,4\n")
-    result = read_document(str(f))
-    # should not raise; returns some text content
-    assert result is not None
-
-
-# ---------------------------------------------------------------------------
-# read_file (workspace, with line numbers and offset/limit)
-# ---------------------------------------------------------------------------
-
-def test_read_file_returns_numbered_view(workspace):
-    (workspace / "a.txt").write_text("alpha\nbeta\ngamma\n")
-    result = read_file("a.txt")
-    assert result["total_lines"] == 3
-    assert result["start_line"] == 1
-    assert result["end_line"] == 3
-    assert "1\talpha" in result["numbered"]
-    assert "3\tgamma" in result["numbered"]
-
-
-def test_read_file_offset_and_limit(workspace):
-    (workspace / "a.txt").write_text("\n".join(f"line{i}" for i in range(1, 11)))
-    result = read_file("a.txt", offset=3, limit=2)
-    assert result["start_line"] == 4
-    assert result["end_line"] == 5
-    assert result["content"].splitlines() == ["line4", "line5"]
-
-
-def test_read_file_disable_line_numbers(workspace):
-    (workspace / "a.txt").write_text("only\n")
-    result = read_file("a.txt", line_numbers=False)
-    assert "numbered" not in result
-    assert result["content"] == "only\n"
-
-
-# ---------------------------------------------------------------------------
-# edit_file
-# ---------------------------------------------------------------------------
-
-def test_edit_file_replaces_unique_match(workspace):
-    (workspace / "code.py").write_text("def foo():\n    return 1\n")
-    result = edit_file("code.py", "return 1", "return 42")
-    assert (workspace / "code.py").read_text() == "def foo():\n    return 42\n"
-    assert result["replacements"] == 1
-    assert result["first_edit_line"] == 2
-
-
-def test_edit_file_missing_string_raises(workspace):
-    (workspace / "code.py").write_text("hello\n")
-    with pytest.raises(ToolError, match="not found"):
-        edit_file("code.py", "missing", "world")
-
-
-def test_edit_file_ambiguous_raises_unless_replace_all(workspace):
-    (workspace / "code.py").write_text("x = 1\nx = 1\n")
-    with pytest.raises(ToolError, match="ambiguous"):
-        edit_file("code.py", "x = 1", "x = 2")
-    result = edit_file("code.py", "x = 1", "x = 2", replace_all=True)
-    assert result["replacements"] == 2
-    assert (workspace / "code.py").read_text() == "x = 2\nx = 2\n"
-
-
-def test_edit_file_rejects_identical(workspace):
-    (workspace / "code.py").write_text("same\n")
-    with pytest.raises(ToolError, match="identical"):
-        edit_file("code.py", "same", "same")
-
-
-# ---------------------------------------------------------------------------
-# grep
-# ---------------------------------------------------------------------------
-
-def test_grep_finds_regex_matches(workspace):
-    (workspace / "a.py").write_text("def foo():\n    return 1\n\ndef bar():\n    return 2\n")
-    (workspace / "b.py").write_text("x = 1\n")
-    result = grep(r"^def \w+", path=".")
-    paths = sorted({m["path"] for m in result["matches"]})
-    assert "a.py" in paths
-    assert result["files_with_matches"] == 1
-
-
-def test_grep_respects_glob(workspace):
-    (workspace / "a.py").write_text("needle\n")
-    (workspace / "a.txt").write_text("needle\n")
-    result = grep("needle", path=".", glob="*.py")
-    paths = [m["path"] for m in result["matches"]]
-    assert "a.py" in paths
-    assert "a.txt" not in paths
-
-
-def test_grep_case_insensitive(workspace):
-    (workspace / "a.txt").write_text("HELLO world\n")
-    result = grep("hello", path=".", case_insensitive=True)
-    assert any("HELLO" in m["match"] for m in result["matches"])
-
-
-def test_grep_context_lines(workspace):
-    (workspace / "a.txt").write_text("before\nhit\nafter\n")
-    result = grep("hit", path=".", context_lines=1)
-    assert result["matches"]
-    ctx_lines = [c["text"] for c in result["matches"][0]["context"]]
-    assert "before" in ctx_lines and "after" in ctx_lines
-
-
-def test_grep_invalid_regex_raises(workspace):
-    (workspace / "a.txt").write_text("hello\n")
-    with pytest.raises(ToolError, match="regex"):
-        grep("[unterminated", path=".")
-
-
-def test_grep_skips_binary_dirs(workspace):
-    (workspace / "node_modules").mkdir()
-    (workspace / "node_modules" / "x.js").write_text("needle\n")
-    (workspace / "src.py").write_text("needle\n")
-    result = grep("needle", path=".")
-    paths = [m["path"] for m in result["matches"]]
-    assert "src.py" in paths
-    assert all("node_modules" not in p for p in paths)
-
-
-# ---------------------------------------------------------------------------
-# todo_read / todo_write
-# ---------------------------------------------------------------------------
-
-def test_todo_read_empty_when_unset(workspace):
-    result = todo_read()
-    assert result["todos"] == []
-
-
-def test_todo_write_round_trip(workspace):
-    todos = [
-        {"id": "1", "content": "design API", "status": "completed"},
-        {"id": "2", "content": "write tests", "status": "in_progress"},
-        {"id": "3", "content": "deploy", "status": "pending"},
-    ]
-    todo_write(todos)
-    fresh = todo_read()
-    assert [t["content"] for t in fresh["todos"]] == ["design API", "write tests", "deploy"]
-    assert fresh["todos"][1]["status"] == "in_progress"
-
-
-def test_todo_write_rejects_invalid_status(workspace):
-    with pytest.raises(ToolError, match="status"):
-        todo_write([{"id": "1", "content": "x", "status": "blocked"}])
-
-
-def test_todo_write_rejects_missing_content(workspace):
-    with pytest.raises(ToolError, match="content"):
-        todo_write([{"id": "1", "content": "", "status": "pending"}])
-
-
-def test_todo_write_warns_multiple_in_progress(workspace):
-    result = todo_write([
-        {"id": "1", "content": "a", "status": "in_progress"},
-        {"id": "2", "content": "b", "status": "in_progress"},
-    ])
-    assert result["warning"]
-
-
-# ---------------------------------------------------------------------------
-# Sandbox: workspace tools must not escape AGENT_ROOT
-# ---------------------------------------------------------------------------
-
-def test_read_file_blocks_path_escape(workspace):
-    with pytest.raises(ToolError, match="escapes"):
-        read_file("../../etc/passwd")
-
-
-def test_edit_file_blocks_path_escape(workspace):
-    with pytest.raises(ToolError, match="escapes"):
-        edit_file("../../etc/passwd", "a", "b")
-
-
-def test_grep_blocks_path_escape(workspace):
-    with pytest.raises(ToolError, match="escapes"):
-        grep("x", path="../../etc")