claude-controller 0.2.0 → 0.3.0

package/web/handler_fs.py

@@ -18,7 +18,7 @@ class FsHandlerMixin:
 
     def _handle_get_config(self):
         defaults = {
-            "skip_permissions": True,
+            "skip_permissions": False,
             "allowed_tools": "Bash,Read,Write,Edit,Glob,Grep,Agent,NotebookEdit,WebFetch,WebSearch",
             "model": "",
             "max_jobs": 10,
@@ -39,7 +39,7 @@ class FsHandlerMixin:
     def _handle_save_config(self):
         body = self._read_body()
         if not body or not isinstance(body, dict):
-            return self._error_response("설정 데이터가 필요합니다")
+            return self._error_response("설정 데이터가 필요합니다", code="MISSING_FIELD")
 
         current = {}
         try:
@@ -52,6 +52,7 @@ class FsHandlerMixin:
             "skip_permissions", "allowed_tools", "model", "max_jobs",
             "append_system_prompt", "target_repo", "base_branch",
             "checkpoint_interval", "locale",
+            "webhook_url", "webhook_secret", "webhook_events",
         }
         for k, v in body.items():
             if k in allowed_keys:
@@ -64,7 +65,7 @@ class FsHandlerMixin:
             )
             self._json_response({"ok": True, "config": current})
         except OSError as e:
-            self._error_response(f"설정 저장 실패: {e}", 500)
+            self._error_response(f"설정 저장 실패: {e}", 500, code="CONFIG_SAVE_FAILED")
 
     def _handle_get_recent_dirs(self):
         try:
@@ -80,26 +81,26 @@ class FsHandlerMixin:
         body = self._read_body()
         dirs = body.get("dirs")
         if not isinstance(dirs, list):
-            return self._error_response("dirs 배열이 필요합니다")
+            return self._error_response("dirs 배열이 필요합니다", code="MISSING_FIELD")
         dirs = [d for d in dirs if isinstance(d, str)][:8]
         try:
             DATA_DIR.mkdir(parents=True, exist_ok=True)
             RECENT_DIRS_FILE.write_text(json.dumps(dirs, ensure_ascii=False), "utf-8")
             self._json_response({"ok": True})
         except OSError as e:
-            self._error_response(f"저장 실패: {e}", 500)
+            self._error_response(f"저장 실패: {e}", 500, code="SAVE_FAILED")
 
     def _handle_dirs(self, dir_path):
         try:
             dir_path = os.path.abspath(os.path.expanduser(dir_path))
             if not os.path.isdir(dir_path):
-                return self._error_response("디렉토리가 아닙니다", 400)
+                return self._error_response("디렉토리가 아닙니다", 400, code="NOT_A_DIRECTORY")
 
             entries = []
             try:
                 items = sorted(os.listdir(dir_path))
             except PermissionError:
-                return self._error_response("접근 권한 없음", 403)
+                return self._error_response("접근 권한 없음", 403, code="PERMISSION_DENIED")
 
             parent = os.path.dirname(dir_path)
             if parent != dir_path:
@@ -122,7 +123,7 @@ class FsHandlerMixin:
 
             self._json_response({"current": dir_path, "entries": entries})
         except Exception as e:
-            self._error_response(f"디렉토리 읽기 실패: {e}", 500)
+            self._error_response(f"디렉토리 읽기 실패: {e}", 500, code="DIR_READ_ERROR")
 
     def _handle_mkdir(self):
         body = self._read_body()
@@ -130,23 +131,23 @@ class FsHandlerMixin:
         name = body.get("name", "").strip()
 
         if not parent or not name:
-            return self._error_response("parent와 name 필드가 필요합니다")
+            return self._error_response("parent와 name 필드가 필요합니다", code="MISSING_FIELD")
 
         if "/" in name or "\\" in name or name in (".", ".."):
-            return self._error_response("잘못된 디렉토리 이름입니다")
+            return self._error_response("잘못된 디렉토리 이름입니다", code="INVALID_NAME")
 
         try:
             parent = os.path.abspath(os.path.expanduser(parent))
             if not os.path.isdir(parent):
-                return self._error_response("상위 디렉토리가 존재하지 않습니다", 400)
+                return self._error_response("상위 디렉토리가 존재하지 않습니다", 400, code="DIR_NOT_FOUND")
 
             new_dir = os.path.join(parent, name)
             if os.path.exists(new_dir):
-                return self._error_response("이미 존재하는 이름입니다", 409)
+                return self._error_response("이미 존재하는 이름입니다", 409, code="ALREADY_EXISTS")
 
             os.makedirs(new_dir)
             self._json_response({"ok": True, "path": new_dir}, 201)
         except PermissionError:
-            self._error_response("접근 권한 없음", 403)
+            self._error_response("접근 권한 없음", 403, code="PERMISSION_DENIED")
         except OSError as e:
-            self._error_response(f"디렉토리 생성 실패: {e}", 500)
+            self._error_response(f"디렉토리 생성 실패: {e}", 500, code="DIR_CREATE_ERROR")

package/web/handler_goals.py

@@ -0,0 +1,203 @@
+"""
+Goal 관련 HTTP 핸들러 Mixin
+
+포함 엔드포인트:
+  - GET    /api/goals              # 목표 목록 (status 필터 가능)
+  - GET    /api/goals/:id          # 목표 상세 (DAG 포함)
+  - POST   /api/goals              # 목표 생성
+  - POST   /api/goals/:id/update   # 목표 수정 (mode, budget 변경)
+  - POST   /api/goals/:id/approve  # Gate 모드: 다음 단계 승인
+  - DELETE /api/goals/:id          # 목표 취소
+"""
+
+import sys
+import time
+from urllib.parse import parse_qs
+
+from config import CONTROLLER_DIR, DATA_DIR
+
+# cognitive 패키지를 import 경로에 추가
+if str(CONTROLLER_DIR) not in sys.path:
+    sys.path.insert(0, str(CONTROLLER_DIR))
+
+from cognitive.goal_engine import GoalEngine, GoalStatus, ExecutionMode
+
+# 모듈 수준 싱글턴
+_goal_engine = None
+
+
+def _get_engine():
+    global _goal_engine
+    if _goal_engine is None:
+        _goal_engine = GoalEngine(str(DATA_DIR))
+    return _goal_engine
+
+
+class GoalHandlerMixin:
+
+    def _handle_list_goals(self, parsed):
+        """GET /api/goals — 목표 목록"""
+        qs = parse_qs(parsed.query)
+        status = qs.get("status", [None])[0]
+        goals = _get_engine().list_goals(status=status)
+        self._json_response(goals)
+
+    def _handle_get_goal(self, goal_id):
+        """GET /api/goals/:id — 목표 상세 (DAG, 진행률 포함)"""
+        goal = _get_engine().get_goal(goal_id)
+        if goal is None:
+            return self._error_response(
+                "목표를 찾을 수 없습니다", 404, code="GOAL_NOT_FOUND")
+        # 실행 가능한 다음 태스크 정보도 포함
+        next_tasks = _get_engine().get_next_tasks(goal_id)
+        goal["next_tasks"] = next_tasks
+        self._json_response(goal)
+
+    def _handle_create_goal(self):
+        """POST /api/goals — 목표 생성"""
+        body = self._read_body()
+        objective = body.get("objective", "").strip()
+        if not objective:
+            return self._error_response(
+                "objective 필드가 필요합니다", 400, code="MISSING_FIELD")
+
+        mode_str = body.get("mode", "gate")
+        try:
+            mode = ExecutionMode(mode_str)
+        except ValueError:
+            valid = [m.value for m in ExecutionMode]
+            return self._error_response(
+                f"유효하지 않은 mode: {mode_str}. 가능한 값: {valid}",
+                400, code="INVALID_MODE")
+
+        context = body.get("context", {})
+        if not isinstance(context, dict):
+            return self._error_response(
+                "context는 JSON 객체여야 합니다", 400, code="INVALID_PARAM")
+
+        try:
+            budget_usd = float(body.get("budget_usd", 5.0))
+            max_tasks = int(body.get("max_tasks", 20))
+        except (ValueError, TypeError):
+            return self._error_response(
+                "budget_usd 또는 max_tasks 값이 유효하지 않습니다",
+                400, code="INVALID_PARAM")
+
+        if budget_usd <= 0:
+            return self._error_response(
+                "budget_usd는 0보다 커야 합니다", 400, code="INVALID_PARAM")
+        if max_tasks < 1:
+            return self._error_response(
+                "max_tasks는 1 이상이어야 합니다", 400, code="INVALID_PARAM")
+
+        goal = _get_engine().create_goal(
+            objective=objective,
+            mode=mode,
+            context=context,
+            budget_usd=budget_usd,
+            max_tasks=max_tasks,
+        )
+        self._json_response(goal, 201)
+
+    def _handle_update_goal(self, goal_id):
+        """POST /api/goals/:id/update — 목표 수정 (mode, budget 변경)"""
+        engine = _get_engine()
+        goal = engine.get_goal(goal_id)
+        if goal is None:
+            return self._error_response(
+                "목표를 찾을 수 없습니다", 404, code="GOAL_NOT_FOUND")
+
+        if goal["status"] in (GoalStatus.COMPLETED.value,
+                              GoalStatus.FAILED.value,
+                              GoalStatus.CANCELLED.value):
+            return self._error_response(
+                f"종료된 목표({goal['status']})는 수정할 수 없습니다",
+                409, code="GOAL_ALREADY_FINISHED")
+
+        body = self._read_body()
+        changed = False
+
+        if "mode" in body:
+            try:
+                mode = ExecutionMode(body["mode"])
+                goal["mode"] = mode.value
+                changed = True
+            except ValueError:
+                valid = [m.value for m in ExecutionMode]
+                return self._error_response(
+                    f"유효하지 않은 mode: {body['mode']}. 가능한 값: {valid}",
+                    400, code="INVALID_MODE")
+
+        if "budget_usd" in body:
+            try:
+                budget = float(body["budget_usd"])
+                if budget <= 0:
+                    raise ValueError
+                goal["budget_usd"] = budget
+                changed = True
+            except (ValueError, TypeError):
+                return self._error_response(
+                    "budget_usd는 0보다 큰 숫자여야 합니다",
+                    400, code="INVALID_PARAM")
+
+        if "max_tasks" in body:
+            try:
+                mt = int(body["max_tasks"])
+                if mt < 1:
+                    raise ValueError
+                goal["max_tasks"] = mt
+                changed = True
+            except (ValueError, TypeError):
+                return self._error_response(
+                    "max_tasks는 1 이상의 정수여야 합니다",
+                    400, code="INVALID_PARAM")
+
+        if not changed:
+            return self._error_response(
+                "변경할 필드가 없습니다. mode, budget_usd, max_tasks 중 하나를 지정하세요.",
+                400, code="NO_CHANGES")
+
+        goal["updated_at"] = time.time()
+        engine._save_goal(goal)
+        self._json_response(goal)
+
+    def _handle_approve_goal(self, goal_id):
+        """POST /api/goals/:id/approve — Gate 모드: 다음 단계 승인"""
+        engine = _get_engine()
+        goal = engine.get_goal(goal_id)
+        if goal is None:
+            return self._error_response(
+                "목표를 찾을 수 없습니다", 404, code="GOAL_NOT_FOUND")
+
+        if goal["status"] != GoalStatus.GATE_WAITING.value:
+            return self._error_response(
+                f"현재 상태({goal['status']})에서는 승인할 수 없습니다. "
+                "gate_waiting 상태일 때만 가능합니다.",
+                409, code="INVALID_STATE_TRANSITION")
+
+        engine.update_status(goal_id, GoalStatus.RUNNING)
+        next_tasks = engine.get_next_tasks(goal_id)
+        goal = engine.get_goal(goal_id)
+
+        self._json_response({
+            "goal": goal,
+            "next_tasks": next_tasks,
+        })
+
+    def _handle_cancel_goal(self, goal_id):
+        """DELETE /api/goals/:id — 목표 취소"""
+        engine = _get_engine()
+        goal = engine.get_goal(goal_id)
+        if goal is None:
+            return self._error_response(
+                "목표를 찾을 수 없습니다", 404, code="GOAL_NOT_FOUND")
+
+        if goal["status"] in (GoalStatus.COMPLETED.value,
+                              GoalStatus.FAILED.value,
+                              GoalStatus.CANCELLED.value):
+            return self._error_response(
+                f"이미 종료된 목표({goal['status']})는 취소할 수 없습니다",
+                409, code="GOAL_ALREADY_FINISHED")
+
+        goal = engine.cancel_goal(goal_id)
+        self._json_response(goal)

package/web/handler_jobs.py

@@ -33,13 +33,26 @@ ALLOWED_UPLOAD_EXTS = IMAGE_EXTS | {
 
 class JobHandlerMixin:
 
-    def _handle_jobs(self):
-        self._json_response(self._jobs_mod().get_all_jobs())
+    def _handle_jobs(self, cwd_filter=None, page=1, limit=10):
+        all_jobs = self._jobs_mod().get_all_jobs(cwd_filter=cwd_filter)
+        total = len(all_jobs)
+        page = max(1, page)
+        limit = max(1, min(limit, 100))
+        pages = max(1, (total + limit - 1) // limit)
+        page = min(page, pages)
+        start = (page - 1) * limit
+        self._json_response({
+            "jobs": all_jobs[start:start + limit],
+            "total": total,
+            "page": page,
+            "limit": limit,
+            "pages": pages,
+        })
 
     def _handle_job_result(self, job_id):
         result, err = self._jobs_mod().get_job_result(job_id)
         if err:
-            self._error_response(err, 404)
+            self._error_response(err, 404, code="JOB_NOT_FOUND")
         else:
             self._json_response(result)
 
@@ -49,18 +62,20 @@ class JobHandlerMixin:
         filename = body.get("filename", "file")
 
         if not data_b64:
-            return self._error_response("data 필드가 필요합니다")
+            return self._error_response("data 필드가 필요합니다", code="MISSING_FIELD")
         if "," in data_b64:
             data_b64 = data_b64.split(",", 1)[1]
 
         try:
             raw = base64.b64decode(data_b64)
         except Exception:
-            return self._error_response("잘못된 base64 데이터")
+            return self._error_response("잘못된 base64 데이터", code="INVALID_DATA")
 
         ext = os.path.splitext(filename)[1].lower()
         if ext not in ALLOWED_UPLOAD_EXTS:
-            ext = ext if ext else ".bin"
+            return self._error_response(
+                f"허용되지 않는 파일 형식입니다: {ext or '(확장자 없음)'}",
+                400, code="INVALID_FILE_TYPE")
         prefix = "img" if ext in IMAGE_EXTS else "file"
         safe_name = f"{prefix}_{int(time.time())}_{os.getpid()}_{id(raw) % 10000}{ext}"
 
@@ -81,7 +96,18 @@ class JobHandlerMixin:
         body = self._read_body()
         prompt = body.get("prompt", "").strip()
         if not prompt:
-            return self._error_response("prompt 필드가 필요합니다")
+            return self._error_response("prompt 필드가 필요합니다", code="MISSING_FIELD")
+
+        # 페르소나 적용: system_prompt를 프롬프트 앞에 주입
+        persona_id = body.get("persona")
+        if persona_id:
+            import personas as _p
+            prompt = _p.apply_persona_to_prompt(persona_id, prompt)
+
+        # depends_on: 선행 작업 ID 목록 (예: [42, 43] 또는 "42,43")
+        depends_on = body.get("depends_on")
+        if isinstance(depends_on, str):
+            depends_on = [d.strip() for d in depends_on.split(",") if d.strip()]
 
         result, err = self._jobs_mod().send_to_fifo(
             prompt,
@@ -89,9 +115,10 @@ class JobHandlerMixin:
             job_id=body.get("id") or None,
             images=body.get("images") or None,
             session=body.get("session") or None,
+            depends_on=depends_on or None,
         )
         if err:
-            self._error_response(err, 502)
+            self._error_response(err, 502, code="SEND_FAILED")
         else:
             self._json_response(result, 201)
 
@@ -100,21 +127,21 @@ class JobHandlerMixin:
         if ok:
             self._json_response({"started": True})
         else:
-            self._error_response("서비스 시작 실패", 500)
+            self._error_response("서비스 시작 실패", 500, code="SERVICE_START_FAILED")
 
     def _handle_service_stop(self):
         ok, err = self._jobs_mod().stop_controller_service()
         if ok:
             self._json_response({"stopped": True})
         else:
-            self._error_response(err or "서비스 종료 실패", 500)
+            self._error_response(err or "서비스 종료 실패", 500, code="SERVICE_STOP_FAILED")
 
     def _handle_delete_job(self, job_id):
         meta_file = LOGS_DIR / f"job_{job_id}.meta"
         out_file = LOGS_DIR / f"job_{job_id}.out"
 
         if not meta_file.exists():
-            return self._error_response("작업을 찾을 수 없습니다", 404)
+            return self._error_response("작업을 찾을 수 없습니다", 404, code="JOB_NOT_FOUND")
 
         meta = parse_meta_file(meta_file)
         if meta and meta.get("STATUS") == "running":
@@ -122,7 +149,7 @@ class JobHandlerMixin:
             if pid:
                 try:
                     os.kill(int(pid), 0)
-                    return self._error_response("실행 중인 작업은 삭제할 수 없습니다", 409)
+                    return self._error_response("실행 중인 작업은 삭제할 수 없습니다", 409, code="JOB_RUNNING")
                 except (ProcessLookupError, ValueError, OSError):
                     pass
 
@@ -133,7 +160,7 @@ class JobHandlerMixin:
                 out_file.unlink()
             self._json_response({"deleted": True, "job_id": job_id})
         except OSError as e:
-            self._error_response(f"삭제 실패: {e}", 500)
+            self._error_response(f"삭제 실패: {e}", 500, code="DELETE_FAILED")
 
     def _handle_delete_completed_jobs(self):
         deleted = []
@@ -143,13 +170,6 @@ class JobHandlerMixin:
                 continue
             status = meta.get("STATUS", "")
             if status in ("done", "failed"):
-                pid = meta.get("PID")
-                if pid and status == "running":
-                    try:
-                        os.kill(int(pid), 0)
-                        continue
-                    except (ProcessLookupError, ValueError, OSError):
-                        pass
                 job_id = meta.get("JOB_ID", "")
                 out_file = LOGS_DIR / f"job_{job_id}.out"
                 try:
@@ -161,22 +181,14 @@ class JobHandlerMixin:
                     pass
         self._json_response({"deleted": deleted, "count": len(deleted)})
 
-    def _handle_job_stream(self, job_id):
-        out_file = LOGS_DIR / f"job_{job_id}.out"
-        meta_file = LOGS_DIR / f"job_{job_id}.meta"
-
-        if not meta_file.exists():
-            return self._error_response("작업을 찾을 수 없습니다", 404)
-
-        parsed = urlparse(self.path)
-        qs = parse_qs(parsed.query)
-        offset = int(qs.get("offset", [0])[0])
-
+    @staticmethod
+    def _parse_stream_events(out_file, offset):
+        """out 파일에서 offset 이후의 스트림 이벤트를 파싱한다. (events, new_offset) 반환."""
+        events = []
+        new_offset = offset
         if not out_file.exists():
-            return self._json_response({"events": [], "offset": 0, "done": False})
-
+            return events, new_offset
         try:
-            events = []
             with open(out_file, "r") as f:
                 f.seek(offset)
                 for raw_line in f:
@@ -199,28 +211,120 @@ class JobHandlerMixin:
                                         "input": str(tp.get("input", ""))[:200]
                                     })
                         elif evt_type == "result":
-                            events.append({
+                            result_evt = {
                                 "type": "result",
                                 "result": evt.get("result", ""),
                                 "cost_usd": evt.get("total_cost_usd"),
                                 "duration_ms": evt.get("duration_ms"),
                                 "is_error": evt.get("is_error", False),
                                 "session_id": evt.get("session_id", "")
-                            })
+                            }
+                            if result_evt["is_error"]:
+                                from jobs import classify_error
+                                result_evt["user_error"] = classify_error(evt.get("result", ""))
+                            events.append(result_evt)
                     except json.JSONDecodeError:
                         continue
                 new_offset = f.tell()
+        except OSError:
+            pass
+        return events, new_offset
+
+    def _handle_job_stream(self, job_id):
+        # SSE content negotiation — Accept 헤더로 분기
+        accept = self.headers.get("Accept", "")
+        if "text/event-stream" in accept:
+            return self._handle_job_stream_sse(job_id)
+
+        out_file = LOGS_DIR / f"job_{job_id}.out"
+        meta_file = LOGS_DIR / f"job_{job_id}.meta"
+
+        if not meta_file.exists():
+            return self._error_response("작업을 찾을 수 없습니다", 404, code="JOB_NOT_FOUND")
+
+        parsed = urlparse(self.path)
+        qs = parse_qs(parsed.query)
+        offset = self._safe_int(qs.get("offset", [0])[0], 0)
 
+        if not out_file.exists():
+            return self._json_response({"events": [], "offset": 0, "done": False})
+
+        try:
+            events, new_offset = self._parse_stream_events(out_file, offset)
             meta = parse_meta_file(meta_file)
             done = meta.get("STATUS", "") in ("done", "failed")
             self._json_response({"events": events, "offset": new_offset, "done": done})
         except OSError as e:
-            self._error_response(f"스트림 읽기 실패: {e}", 500)
+            self._error_response(f"스트림 읽기 실패: {e}", 500, code="STREAM_READ_ERROR")
+
+    def _handle_job_stream_sse(self, job_id):
+        """SSE 실시간 스트림 — 이벤트를 push 방식으로 전달한다."""
+        import time as _time
+
+        out_file = LOGS_DIR / f"job_{job_id}.out"
+        meta_file = LOGS_DIR / f"job_{job_id}.meta"
+
+        if not meta_file.exists():
+            return self._error_response("작업을 찾을 수 없습니다", 404, code="JOB_NOT_FOUND")
+
+        self.send_response(200)
+        self.send_header("Content-Type", "text/event-stream; charset=utf-8")
+        self.send_header("Cache-Control", "no-cache")
+        self.send_header("X-Accel-Buffering", "no")
+        self._set_cors_headers()
+        self.end_headers()
+
+        offset = 0
+        last_activity = _time.time()
+
+        try:
+            while True:
+                events, new_offset = self._parse_stream_events(out_file, offset)
+                offset = new_offset
+
+                for evt in events:
+                    data = json.dumps(evt, ensure_ascii=False)
+                    self.wfile.write(f"data: {data}\n\n".encode("utf-8"))
+
+                if events:
+                    self.wfile.flush()
+                    last_activity = _time.time()
+
+                # 작업 완료 확인
+                meta = parse_meta_file(meta_file)
+                status = meta.get("STATUS", "")
+                if status == "running" and meta.get("PID"):
+                    try:
+                        os.kill(int(meta["PID"]), 0)
+                    except (ProcessLookupError, ValueError, OSError):
+                        status = "done"
+
+                if status in ("done", "failed"):
+                    # 최종 이벤트 한 번 더 수집
+                    final_events, _ = self._parse_stream_events(out_file, offset)
+                    for evt in final_events:
+                        data = json.dumps(evt, ensure_ascii=False)
+                        self.wfile.write(f"data: {data}\n\n".encode("utf-8"))
+                    self.wfile.write(f"event: done\ndata: {{\"status\":\"{status}\"}}\n\n".encode("utf-8"))
+                    self.wfile.flush()
+                    break
+
+                # Heartbeat — 15초 동안 이벤트 없으면 keepalive 전송
+                now = _time.time()
+                if now - last_activity > 15:
+                    self.wfile.write(b": heartbeat\n\n")
+                    self.wfile.flush()
+                    last_activity = now
+
+                _time.sleep(0.3)
+
+        except (BrokenPipeError, ConnectionResetError, OSError):
+            pass  # 클라이언트 연결 끊김
 
     def _handle_job_checkpoints(self, job_id):
         checkpoints, err = self._ckpt_mod().get_job_checkpoints(job_id)
         if err:
-            self._error_response(err, 404)
+            self._error_response(err, 404, code="JOB_NOT_FOUND")
         else:
             self._json_response(checkpoints)
 
@@ -229,21 +333,40 @@ class JobHandlerMixin:
         matched = [j for j in jobs if j.get("session_id") == session_id]
         if not matched:
             return self._error_response(
-                f"Session ID '{session_id[:8]}...'에 해당하는 작업을 찾을 수 없습니다", 404)
+                f"Session ID '{session_id[:8]}...'에 해당하는 작업을 찾을 수 없습니다", 404, code="SESSION_NOT_FOUND")
         self._json_response(matched[0])
 
+    def _handle_job_diff(self, job_id):
+        parsed = urlparse(self.path)
+        qs = parse_qs(parsed.query)
+        from_hash = qs.get("from", [""])[0].strip()
+        to_hash = qs.get("to", [""])[0].strip()
+
+        if not from_hash:
+            return self._error_response("from 파라미터가 필요합니다", code="MISSING_FIELD")
+
+        result, err = self._ckpt_mod().diff_checkpoints(job_id, from_hash, to_hash or None)
+        if err:
+            status = 404 if "찾을 수 없습니다" in err else 500
+            self._error_response(err, status, code="DIFF_FAILED")
+        else:
+            self._json_response(result)
+
     def _handle_job_rewind(self, job_id):
         body = self._read_body()
         checkpoint_hash = body.get("checkpoint", "").strip()
         new_prompt = body.get("prompt", "").strip()
 
         if not checkpoint_hash:
-            return self._error_response("checkpoint 필드가 필요합니다")
+            return self._error_response("checkpoint 필드가 필요합니다", code="MISSING_FIELD")
         if not new_prompt:
-            return self._error_response("prompt 필드가 필요합니다")
+            return self._error_response("prompt 필드가 필요합니다", code="MISSING_FIELD")
 
         result, err = self._ckpt_mod().rewind_job(job_id, checkpoint_hash, new_prompt)
         if err:
-            self._error_response(err, 400 if "찾을 수 없습니다" in err else 500)
+            if "찾을 수 없습니다" in err:
+                self._error_response(err, 400, code="CHECKPOINT_NOT_FOUND")
+            else:
+                self._error_response(err, 500, code="REWIND_FAILED")
         else:
             self._json_response(result, 201)