feat: implement thread management for L1 conversation memory

backend-java/src/main/java/io/agentflow/api/controller/GlobalExceptionHandler.java

@@ -7,6 +7,7 @@
 import io.agentflow.api.service.RunComparisonValidationException;
 import io.agentflow.api.service.RunConflictException;
 import io.agentflow.api.service.RunNotFoundException;
+import io.agentflow.api.service.ThreadNotFoundException;
 import io.agentflow.api.security.ForbiddenException;
 import io.agentflow.api.security.UnauthorizedException;
 import java.util.Map;
@@ -33,6 +34,11 @@ public ResponseEntity<Map<String, String>> handleAgentVersionNotFound(
         return ResponseEntity.status(HttpStatus.NOT_FOUND).body(Map.of("detail", ex.getMessage()));
     }
 
+    @ExceptionHandler(ThreadNotFoundException.class)
+    public ResponseEntity<Map<String, String>> handleThreadNotFound(ThreadNotFoundException ex) {
+        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(Map.of("detail", ex.getMessage()));
+    }
+
     @ExceptionHandler(RunNotFoundException.class)
     public ResponseEntity<Map<String, String>> handleRunNotFound(RunNotFoundException ex) {
         return ResponseEntity.status(HttpStatus.NOT_FOUND).body(Map.of("detail", ex.getMessage()));

backend-java/src/main/java/io/agentflow/api/controller/ThreadsController.java

@@ -0,0 +1,59 @@
+package io.agentflow.api.controller;
+
+import io.agentflow.api.dto.RunResponse;
+import io.agentflow.api.dto.ThreadCreateRequest;
+import io.agentflow.api.dto.ThreadMessageResponse;
+import io.agentflow.api.dto.ThreadResponse;
+import io.agentflow.api.service.ThreadService;
+import jakarta.validation.Valid;
+import java.util.List;
+import org.springframework.http.HttpStatus;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.ResponseStatus;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/v1/threads")
+public class ThreadsController {
+
+    private final ThreadService service;
+
+    public ThreadsController(ThreadService service) {
+        this.service = service;
+    }
+
+    @PostMapping
+    @ResponseStatus(HttpStatus.CREATED)
+    public ThreadResponse create(@Valid @RequestBody ThreadCreateRequest payload) {
+        return service.create(payload);
+    }
+
+    @GetMapping
+    public List<ThreadResponse> list(@RequestParam(defaultValue = "50") int limit) {
+        return service.list(limit);
+    }
+
+    @GetMapping("/{id}")
+    public ThreadResponse get(@PathVariable String id) {
+        return service.get(id);
+    }
+
+    @GetMapping("/{id}/messages")
+    public ThreadMessageResponse.Page listMessages(
+            @PathVariable String id,
+            @RequestParam(required = false) String cursor,
+            @RequestParam(defaultValue = "50") int limit) {
+        return service.listMessages(id, cursor, limit);
+    }
+
+    @GetMapping("/{id}/runs")
+    public List<RunResponse> listRuns(
+            @PathVariable String id, @RequestParam(defaultValue = "50") int limit) {
+        return service.listRuns(id, limit);
+    }
+}

backend-java/src/main/java/io/agentflow/api/dto/RunCreateRequest.java

@@ -19,6 +19,9 @@ public class RunCreateRequest {
      */
     private String adapter;
 
+    @JsonProperty("thread_id")
+    private String threadId;
+
     public String getAgentId() {
         return agentId;
     }
@@ -50,4 +53,12 @@ public String getAdapter() {
     public void setAdapter(String adapter) {
         this.adapter = adapter;
     }
+
+    public String getThreadId() {
+        return threadId;
+    }
+
+    public void setThreadId(String threadId) {
+        this.threadId = threadId;
+    }
 }

backend-java/src/main/java/io/agentflow/api/dto/RunResponse.java

@@ -11,6 +11,7 @@ public class RunResponse {
     private String id;
     private String tenantId;
     private String agentId;
+    private String threadId;
     private String adapter;
     private RunStatus status;
     private Map<String, Object> input;
@@ -74,6 +75,7 @@ public static RunResponse fromEntity(
         dto.id = entity.getId();
         dto.tenantId = entity.getTenantId();
         dto.agentId = entity.getAgentId();
+        dto.threadId = entity.getThreadId();
         dto.adapter = entity.getAdapter();
         dto.status = entity.getStatus();
         dto.input = entity.getInput();
@@ -101,6 +103,10 @@ public String getAgentId() {
         return agentId;
     }
 
+    public String getThreadId() {
+        return threadId;
+    }
+
     public String getAdapter() {
         return adapter;
     }

backend-java/src/main/java/io/agentflow/api/dto/ThreadCreateRequest.java

@@ -0,0 +1,51 @@
+package io.agentflow.api.dto;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import jakarta.validation.constraints.NotBlank;
+
+public class ThreadCreateRequest {
+
+    @NotBlank
+    @JsonProperty("agent_id")
+    private String agentId;
+
+    private String title;
+
+    @JsonProperty("user_id")
+    private String userId;
+
+    @JsonProperty("project_id")
+    private String projectId;
+
+    public String getAgentId() {
+        return agentId;
+    }
+
+    public void setAgentId(String agentId) {
+        this.agentId = agentId;
+    }
+
+    public String getTitle() {
+        return title;
+    }
+
+    public void setTitle(String title) {
+        this.title = title;
+    }
+
+    public String getUserId() {
+        return userId;
+    }
+
+    public void setUserId(String userId) {
+        this.userId = userId;
+    }
+
+    public String getProjectId() {
+        return projectId;
+    }
+
+    public void setProjectId(String projectId) {
+        this.projectId = projectId;
+    }
+}

backend-java/src/main/java/io/agentflow/api/dto/ThreadMessageResponse.java

@@ -0,0 +1,99 @@
+package io.agentflow.api.dto;
+
+import io.agentflow.api.entity.MessageEntity;
+import java.time.Instant;
+import java.util.List;
+import java.util.Map;
+
+public class ThreadMessageResponse {
+
+    private String id;
+    private String runId;
+    private int index;
+    private String stepId;
+    private String role;
+    private String name;
+    private String content;
+    private String toolCallId;
+    private Map<String, Object> extra;
+    private Instant createdAt;
+
+    public static ThreadMessageResponse from(MessageEntity entity, String runId) {
+        ThreadMessageResponse dto = new ThreadMessageResponse();
+        dto.id = entity.getId();
+        dto.runId = runId;
+        dto.index = entity.getIndex();
+        dto.stepId = entity.getStepId();
+        dto.role = entity.getRole();
+        dto.name = entity.getName();
+        dto.content = entity.getContent();
+        dto.toolCallId = entity.getToolCallId();
+        dto.extra = entity.getExtra();
+        dto.createdAt = entity.getCreatedAt();
+        return dto;
+    }
+
+    public String getId() {
+        return id;
+    }
+
+    public String getRunId() {
+        return runId;
+    }
+
+    public int getIndex() {
+        return index;
+    }
+
+    public String getStepId() {
+        return stepId;
+    }
+
+    public String getRole() {
+        return role;
+    }
+
+    public String getName() {
+        return name;
+    }
+
+    public String getContent() {
+        return content;
+    }
+
+    public String getToolCallId() {
+        return toolCallId;
+    }
+
+    public Map<String, Object> getExtra() {
+        return extra;
+    }
+
+    public Instant getCreatedAt() {
+        return createdAt;
+    }
+
+    public static class Page {
+        private final List<ThreadMessageResponse> items;
+        private final String nextCursor;
+        private final boolean hasMore;
+
+        public Page(List<ThreadMessageResponse> items, String nextCursor, boolean hasMore) {
+            this.items = items;
+            this.nextCursor = nextCursor;
+            this.hasMore = hasMore;
+        }
+
+        public List<ThreadMessageResponse> getItems() {
+            return items;
+        }
+
+        public String getNextCursor() {
+            return nextCursor;
+        }
+
+        public boolean isHasMore() {
+            return hasMore;
+        }
+    }
+}

backend-java/src/main/java/io/agentflow/api/dto/ThreadResponse.java

@@ -0,0 +1,61 @@
+package io.agentflow.api.dto;
+
+import io.agentflow.api.entity.ThreadEntity;
+import java.time.Instant;
+
+public class ThreadResponse {
+
+    private String id;
+    private String tenantId;
+    private String projectId;
+    private String agentId;
+    private String userId;
+    private String title;
+    private Instant createdAt;
+    private Instant updatedAt;
+
+    public static ThreadResponse fromEntity(ThreadEntity entity) {
+        ThreadResponse dto = new ThreadResponse();
+        dto.id = entity.getId();
+        dto.tenantId = entity.getTenantId();
+        dto.projectId = entity.getProjectId();
+        dto.agentId = entity.getAgentId();
+        dto.userId = entity.getUserId();
+        dto.title = entity.getTitle();
+        dto.createdAt = entity.getCreatedAt();
+        dto.updatedAt = entity.getUpdatedAt();
+        return dto;
+    }
+
+    public String getId() {
+        return id;
+    }
+
+    public String getTenantId() {
+        return tenantId;
+    }
+
+    public String getProjectId() {
+        return projectId;
+    }
+
+    public String getAgentId() {
+        return agentId;
+    }
+
+    public String getUserId() {
+        return userId;
+    }
+
+    public String getTitle() {
+        return title;
+    }
+
+    public Instant getCreatedAt() {
+        return createdAt;
+    }
+
+    public Instant getUpdatedAt() {
+        return updatedAt;
+    }
+}

backend-java/src/main/java/io/agentflow/api/entity/RunEntity.java

@@ -28,6 +28,9 @@ public class RunEntity {
     @Column(name = "agent_id", nullable = false, length = 26)
     private String agentId;
 
+    @Column(name = "thread_id", length = 26)
+    private String threadId;
+
     @Column(nullable = false, length = 64)
     private String adapter;
 
@@ -101,6 +104,14 @@ public void setAgentId(String agentId) {
         this.agentId = agentId;
     }
 
+    public String getThreadId() {
+        return threadId;
+    }
+
+    public void setThreadId(String threadId) {
+        this.threadId = threadId;
+    }
+
     public String getAdapter() {
         return adapter;
     }