ltcai 0.1.9 → 0.1.11

package/skills/summarize_document/SKILL.md

@@ -0,0 +1,68 @@
+# Skill: summarize_document
+
+## 메타데이터
+- **버전**: 0.1.0
+- **카테고리**: document
+- **위험도**: low
+- **필요 권한**: local_read
+
+## 설명
+텍스트 파일(.txt, .md, .pdf, .docx)을 읽어 핵심 내용을 요약하고, 섹션별 요점과 키워드를 추출한다.
+
+## 거버넌스
+
+`risk.json` 참고. 요약: `risk=read`, `destructive=false`, `shell=false`, `network=false`, `auto_approve=true`, `sandbox=home`, `rollback=none`
+
+## 트리거 조건
+
+호출해야 하는 상황:
+- 사용자가 "이 문서 요약해줘", "핵심만 뽑아줘", "이 파일 내용이 뭐야?"라고 요청할 때
+- 에이전트가 Discover 단계에서 긴 문서의 구조를 빠르게 파악해야 할 때
+- 여러 문서를 비교하기 전 각 문서의 핵심 파악이 필요할 때
+
+호출하면 **안** 되는 상황:
+- 문서를 수정해야 할 때 → `edit_file` 사용
+- CSV/Excel 데이터 분석 → `data_analysis` 사용
+- 코드 파일 분석 → `code_review` 사용
+
+## Side Effects
+
+| 항목 | 내용 |
+|------|------|
+| 파일 변경 | 없음 |
+| 생성 파일 | 없음 |
+| 프로세스 | 없음 |
+| 네트워크 | 없음 |
+
+## Rollback
+
+없음. 읽기 전용 작업.
+
+## 입력 스키마
+`schema.json` 참고.
+
+## 출력 스키마
+`schema.json` 참고.
+
+## 실행 조건
+- LLM 모델이 로드되어 있어야 함
+- 파일이 존재해야 하며 .txt/.md/.pdf/.docx 형식이어야 함
+- 파일 크기 20 MB 이하
+
+## 예제
+`examples.md` 참고.
+
+## 실패 처리
+| 에러 코드 | 원인 | 처리 방법 |
+|-----------|------|-----------|
+| `INVALID_INPUT` | path 누락 | 파일 경로 입력 |
+| `FILE_NOT_FOUND` | 경로에 파일 없음 | 경로 확인 |
+| `UNSUPPORTED_FORMAT` | 지원하지 않는 형식 | .txt/.md/.pdf/.docx로 변환 후 재시도 |
+| `SIZE_LIMIT` | 20 MB 초과 | 파일 분할 후 재시도 |
+| `MODEL_NOT_LOADED` | LLM 미로드 | `/model` 명령으로 모델 선택 |
+
+## 테스트 케이스
+```python
+# tests/unit/test_tools.py::test_summarize_document_md
+# tests/unit/test_tools.py::test_summarize_document_unsupported
+```

package/skills/summarize_document/examples.md

@@ -0,0 +1,65 @@
+# summarize_document — Examples
+
+## 1. Markdown file summary (success)
+
+**Input**
+```json
+{ "path": "~/project/README.md", "style": "bullet" }
+```
+**Output**
+```json
+{
+  "success": true,
+  "result": {
+    "title": "README.md",
+    "summary": "• Lattice AI는 Apple Silicon 기반 로컬 AI 에이전트\n• FastAPI 서버 + VS Code 익스텐션 + Telegram bot 구조\n• MLX 및 클라우드 모델(OpenAI/Groq) 지원",
+    "keywords": ["Lattice AI", "MLX", "FastAPI", "VS Code", "Telegram", "local LLM"],
+    "sections": [
+      { "heading": "Installation", "summary": "pip install ltcai 후 ltcai start로 실행" },
+      { "heading": "Features", "summary": "채팅, 에이전트 모드, 파일 편집, 웹 검색 등 지원" }
+    ],
+    "word_count": 1240
+  }
+}
+```
+
+## 2. PDF summary with focus section (success)
+
+**Input**
+```json
+{ "path": "~/docs/report.pdf", "style": "paragraph", "focus_sections": ["결론", "권고사항"], "max_length": 300 }
+```
+**Output**
+```json
+{
+  "success": true,
+  "result": {
+    "title": "report.pdf",
+    "summary": "보고서의 결론: 시스템 성능이 전분기 대비 23% 향상되었으며, 추가 최적화를 위해 캐시 레이어 도입이 권고됩니다.",
+    "keywords": ["성능", "최적화", "캐시", "권고"],
+    "word_count": 8500
+  }
+}
+```
+
+## 3. Unsupported format (failure)
+
+**Input**
+```json
+{ "path": "~/data/sales.csv" }
+```
+**Output**
+```json
+{ "success": false, "error": "UNSUPPORTED_FORMAT", "message": "Supported formats: txt, md, pdf, docx. Use data_analysis for CSV files." }
+```
+
+## 4. File not found (failure)
+
+**Input**
+```json
+{ "path": "~/docs/nonexistent.md" }
+```
+**Output**
+```json
+{ "success": false, "error": "FILE_NOT_FOUND", "message": "No such file: /home/user/docs/nonexistent.md" }
+```

package/skills/summarize_document/risk.json

@@ -0,0 +1,9 @@
+{
+  "risk": "read",
+  "destructive": false,
+  "shell": false,
+  "network": false,
+  "auto_approve": true,
+  "sandbox": "home",
+  "rollback": "none"
+}

package/skills/summarize_document/schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "summarize_document",
+  "input": {
+    "required": ["path"],
+    "optional": ["max_length", "style", "focus_sections"],
+    "properties": {
+      "path":           { "type": "string", "description": "절대 경로 또는 ~/로 시작하는 경로 (.txt, .md, .pdf, .docx)" },
+      "max_length":     { "type": "integer", "default": 500, "description": "요약 최대 글자 수" },
+      "style":          { "type": "string", "enum": ["bullet","paragraph","table"], "default": "bullet", "description": "출력 형식" },
+      "focus_sections": { "type": "array", "items": { "type": "string" }, "description": "특정 섹션만 요약할 때 섹션 제목 목록" }
+    }
+  },
+  "output": {
+    "oneOf": [
+      {
+        "title": "success",
+        "properties": {
+          "success": { "const": true },
+          "result": {
+            "properties": {
+              "title":    { "type": "string", "description": "문서 제목 또는 파일명" },
+              "summary":  { "type": "string", "description": "핵심 요약" },
+              "keywords": { "type": "array", "items": { "type": "string" }, "description": "주요 키워드 (최대 10개)" },
+              "sections": {
+                "type": "array",
+                "items": {
+                  "properties": {
+                    "heading": { "type": "string" },
+                    "summary": { "type": "string" }
+                  },
+                  "required": ["heading","summary"]
+                },
+                "description": "섹션별 요약 (있는 경우)"
+              },
+              "word_count": { "type": "integer" }
+            },
+            "required": ["title","summary","keywords"]
+          }
+        },
+        "required": ["success","result"]
+      },
+      {
+        "title": "failure",
+        "properties": {
+          "success": { "const": false },
+          "error":   { "type": "string", "enum": ["INVALID_INPUT","FILE_NOT_FOUND","UNSUPPORTED_FORMAT","SIZE_LIMIT","MODEL_NOT_LOADED"] },
+          "message": { "type": "string" }
+        },
+        "required": ["success","error","message"]
+      }
+    ]
+  },
+  "evals": [
+    {
+      "id": "markdown_summary",
+      "input": { "path": "__TEST__/README.md", "style": "bullet" },
+      "pass_criteria": "success == true and len(keywords) >= 1"
+    },
+    {
+      "id": "unsupported_format",
+      "input": { "path": "__TEST__/data.csv" },
+      "pass_criteria": "error == UNSUPPORTED_FORMAT"
+    },
+    {
+      "id": "missing_path",
+      "input": {},
+      "pass_criteria": "error == INVALID_INPUT"
+    }
+  ]
+}

package/skills/web_search/SKILL.md

@@ -9,6 +9,34 @@
 ## 설명
 외부 검색 엔진(DuckDuckGo/Brave)을 통해 웹 검색을 수행하고 상위 결과를 반환한다.
 
+## 거버넌스
+
+`policies/policy.md` 참고. 요약: `risk=read`, `destructive=false`, `shell=false`, `network=true`, `auto_approve=true`, `sandbox=system`, `rollback=none`
+
+## 트리거 조건
+
+호출해야 하는 상황:
+- 사용자가 "검색해줘", "찾아봐줘", "최신 정보 알려줘"라고 요청할 때
+- 에이전트가 Discover 단계에서 외부 문서/API/라이브러리 정보를 수집해야 할 때
+- LLM의 학습 데이터 이후 최신 정보(라이브러리 버전, 뉴스 등)가 필요할 때
+
+호출하면 **안** 되는 상황:
+- 로컬 파일 내용 검색 시 → `grep` 사용
+- LLM이 이미 알고 있는 일반 지식 질문 시
+
+## Side Effects
+
+| 항목 | 내용 |
+|------|------|
+| 파일 변경 | 없음 |
+| 생성 파일 | 없음 |
+| 프로세스 | 없음 |
+| 네트워크 | 외부 검색 API로 검색어 전송 (DuckDuckGo/Brave) |
+
+## Rollback
+
+없음. 읽기 전용 네트워크 요청.
+
 ## 입력 스키마
 ```json
 {

package/skills/web_search/examples.md

@@ -0,0 +1,61 @@
+# web_search — Examples
+
+## 1. Basic search (success)
+
+**Input**
+```json
+{ "query": "FastAPI 비동기 처리", "num_results": 3 }
+```
+**Output**
+```json
+{
+  "success": true,
+  "result": {
+    "query": "FastAPI 비동기 처리",
+    "results": [
+      { "title": "FastAPI - Async", "url": "https://fastapi.tiangolo.com/async/", "snippet": "FastAPI는 Python의 asyncio를 완벽히 지원합니다..." }
+    ]
+  }
+}
+```
+
+## 2. Search with language (success)
+
+**Input**
+```json
+{ "query": "Python type hints best practices", "num_results": 5, "lang": "en-US" }
+```
+**Output**
+```json
+{
+  "success": true,
+  "result": {
+    "query": "Python type hints best practices",
+    "results": [
+      { "title": "PEP 484 – Type Hints", "url": "https://peps.python.org/pep-0484/", "snippet": "This PEP introduces a standard syntax for type annotations..." }
+    ]
+  }
+}
+```
+
+## 3. Empty query (failure)
+
+**Input**
+```json
+{ "query": "" }
+```
+**Output**
+```json
+{ "success": false, "error": "INVALID_INPUT", "message": "query is required" }
+```
+
+## 4. Network error (failure)
+
+**Input**
+```json
+{ "query": "offline test" }
+```
+**Output**
+```json
+{ "success": false, "error": "NETWORK_ERROR", "message": "외부 검색 API에 연결할 수 없습니다. 잠시 후 재시도하세요." }
+```

package/skills/web_search/risk.json

@@ -0,0 +1,9 @@
+{
+  "risk": "read",
+  "destructive": false,
+  "shell": false,
+  "network": true,
+  "auto_approve": true,
+  "sandbox": "system",
+  "rollback": "none"
+}

package/skills/web_search/schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "web_search",
+  "input": {
+    "required": ["query"],
+    "optional": ["num_results", "lang"],
+    "properties": {
+      "query":       { "type": "string", "description": "검색어" },
+      "num_results": { "type": "integer", "default": 5, "minimum": 1, "maximum": 20 },
+      "lang":        { "type": "string", "default": "ko-KR" }
+    }
+  },
+  "output": {
+    "oneOf": [
+      {
+        "title": "success",
+        "properties": {
+          "success": { "const": true },
+          "result": {
+            "properties": {
+              "query":   { "type": "string" },
+              "results": {
+                "type": "array",
+                "items": {
+                  "properties": {
+                    "title":   { "type": "string" },
+                    "url":     { "type": "string", "format": "uri" },
+                    "snippet": { "type": "string" }
+                  },
+                  "required": ["title","url","snippet"]
+                }
+              }
+            },
+            "required": ["query","results"]
+          }
+        },
+        "required": ["success","result"]
+      },
+      {
+        "title": "failure",
+        "properties": {
+          "success": { "const": false },
+          "error":   { "type": "string", "enum": ["INVALID_INPUT","NETWORK_ERROR","TIMEOUT"] },
+          "message": { "type": "string" }
+        },
+        "required": ["success","error","message"]
+      }
+    ]
+  },
+  "evals": [
+    {
+      "id": "basic_search",
+      "input": { "query": "FastAPI async", "num_results": 3 },
+      "pass_criteria": "success == true and len(results) >= 1"
+    },
+    {
+      "id": "empty_query",
+      "input": { "query": "" },
+      "pass_criteria": "error == INVALID_INPUT"
+    }
+  ]
+}

package/tests/unit/test_tools.py

@@ -5,7 +5,28 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).parent.parent.parent))
 
-from tools import local_list, local_read, local_write, read_document, ToolError
+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
 
 
 # ---------------------------------------------------------------------------
@@ -125,3 +146,175 @@ def test_read_document_csv(tmp_path):
     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")