feat: Allow finishing subtasks with a specified state and outcome. (#199)

Author: Aias00

agentscope-core/src/main/java/io/agentscope/core/plan/model/SubTask.java

@@ -22,17 +22,19 @@
 /**
  * Represents a subtask within a plan.
  *
- * <p>A subtask is a unit of work with a specific goal and expected outcome. It has a state that
+ * <p>
+ * A subtask is a unit of work with a specific goal and expected outcome. It has
+ * a state that
  * tracks its progress through the execution lifecycle.
  *
- * <p><b>Usage Example:</b>
+ * <p>
+ * <b>Usage Example:</b>
  *
  * <pre>{@code
  * SubTask task = new SubTask(
- *     "Setup project",
- *     "Initialize project structure with proper directory layout",
- *     "Project scaffolding completed"
- * );
+ *         "Setup project",
+ *         "Initialize project structure with proper directory layout",
+ *         "Project scaffolding completed");
  *
  * task.setState(SubTaskState.IN_PROGRESS);
  * // ... execute task
@@ -63,8 +65,10 @@ public SubTask() {
     /**
      * Create a new subtask.
      *
-     * @param name The subtask name (should be concise, not exceed 10 words)
-     * @param description The detailed description including constraints and targets
+     * @param name            The subtask name (should be concise, not exceed 10
+     *                        words)
+     * @param description     The detailed description including constraints and
+     *                        targets
      * @param expectedOutcome The expected outcome, specific and measurable
      */
     public SubTask(String name, String description, String expectedOutcome) {
@@ -80,7 +84,23 @@ public SubTask(String name, String description, String expectedOutcome) {
      * @param outcome The actual outcome achieved
      */
     public void finish(String outcome) {
-        this.state = SubTaskState.DONE;
+        finish(SubTaskState.DONE, outcome);
+    }
+
+    /**
+     * Mark the subtask as finished with a specific state and outcome.
+     *
+     * @param state   The final state (e.g., DONE or ABANDONED)
+     * @param outcome The actual outcome or reason for abandoning
+     * @throws IllegalArgumentException if the state is not a terminal state (DONE
+     *                                  or ABANDONED)
+     */
+    public void finish(SubTaskState state, String outcome) {
+        if (state != SubTaskState.DONE && state != SubTaskState.ABANDONED) {
+            throw new IllegalArgumentException(
+                    "SubTask can only be finished with DONE or ABANDONED state, but got: " + state);
+        }
+        this.state = state;
         this.outcome = outcome;
         this.finishedAt = ZonedDateTime.now().format(FORMATTER);
     }
@@ -98,6 +118,7 @@ public String toOneLineMarkdown() {
                     case DONE -> "- [x]";
                     case ABANDONED -> "- [ ] [Abandoned]";
                 };
+
         String displayName = (name != null) ? name : "Unnamed Subtask";
         return statusPrefix + " " + displayName;
     }

agentscope-core/src/test/java/io/agentscope/core/model/transport/OkHttpTransportTest.java

@@ -266,24 +266,26 @@ void testHttpTransportException() {
     }
 
     @Test
-    void testConnectionTimeout() throws Exception {
-        // Create a transport with very short timeout
-        HttpTransportConfig config =
-                HttpTransportConfig.builder().connectTimeout(Duration.ofMillis(1)).build();
-        OkHttpTransport shortTimeoutTransport = new OkHttpTransport(config);
+    void testConnectionRefused() throws Exception {
+        // Shutdown the mock server to ensure connection failure
+        mockServer.shutdown();
+        int port = mockServer.getPort();
+
+        HttpTransportConfig config = HttpTransportConfig.defaults();
+        OkHttpTransport myTransport = new OkHttpTransport(config);
 
         try {
-            // Use a non-routable IP to trigger connection timeout
             HttpRequest request =
                     HttpRequest.builder()
-                            .url("http://10.255.255.1:12345/timeout")
+                            // Use localhost to avoid network issues and ensure immediate connection
+                            // refused
+                            .url("http://localhost:" + port + "/timeout")
                             .method("GET")
                             .build();
 
-            assertThrows(
-                    HttpTransportException.class, () -> shortTimeoutTransport.execute(request));
+            assertThrows(HttpTransportException.class, () -> myTransport.execute(request));
         } finally {
-            shortTimeoutTransport.close();
+            myTransport.close();
         }
     }
 
@@ -299,6 +301,8 @@ void testOkHttpTransportBuilder() {
 
         assertNotNull(builtTransport);
         assertNotNull(builtTransport.getClient());
+        assertEquals(10000, builtTransport.getClient().connectTimeoutMillis());
+        assertEquals(30000, builtTransport.getClient().readTimeoutMillis());
         assertEquals(config, builtTransport.getConfig());
         builtTransport.close();
     }

agentscope-core/src/test/java/io/agentscope/core/plan/model/SubTaskTest.java

@@ -18,6 +18,7 @@
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import org.junit.jupiter.api.Test;
@@ -57,6 +58,51 @@ void testFinishSubTask() {
         assertNotNull(task.getFinishedAt());
     }
 
+    @Test
+    void testFinishSubTaskWithState() {
+        SubTask task = new SubTask("Task", "Desc", "Expected");
+
+        task.finish(SubTaskState.ABANDONED, "Given up");
+
+        assertEquals(SubTaskState.ABANDONED, task.getState());
+        assertEquals("Given up", task.getOutcome());
+        assertNotNull(task.getFinishedAt());
+    }
+
+    @Test
+    void testFinishSubTaskWithDoneState() {
+        SubTask task = new SubTask("Task", "Desc", "Expected");
+
+        task.finish(SubTaskState.DONE, "Success");
+
+        assertEquals(SubTaskState.DONE, task.getState());
+        assertEquals("Success", task.getOutcome());
+        assertNotNull(task.getFinishedAt());
+    }
+
+    @Test
+    void testFinishSubTaskWithInvalidState() {
+        SubTask task = new SubTask("Task", "Desc", "Expected");
+
+        // Should throw exception when attempting to finish with TODO
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            task.finish(SubTaskState.TODO, "Not actually done");
+                        });
+        assertTrue(exception.getMessage().contains("TODO"));
+
+        // Should throw exception when attempting to finish with IN_PROGRESS
+        exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            task.finish(SubTaskState.IN_PROGRESS, "Still working");
+                        });
+        assertTrue(exception.getMessage().contains("IN_PROGRESS"));
+    }
+
     @Test
     void testToOneLineMarkdown_TodoState() {
         SubTask task = new SubTask("Task1", "Desc", "Expected");