feat(adk): add plan task tool (#736)

Change-Id: I61cd3709e78b5e1ef1fe169572913e7e35946d56

Author: fanlv

adk/middlewares/plantask/backend_test.go

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2025 CloudWeGo Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package plantask
+
+import (
+	"context"
+	"errors"
+	"path/filepath"
+	"strings"
+	"sync"
+)
+
+type inMemoryBackend struct {
+	files map[string]string
+	mu    sync.RWMutex
+}
+
+func newInMemoryBackend() *inMemoryBackend {
+	return &inMemoryBackend{
+		files: make(map[string]string),
+	}
+}
+
+func (b *inMemoryBackend) LsInfo(ctx context.Context, req *LsInfoRequest) ([]FileInfo, error) {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+
+	reqPath := strings.TrimSuffix(req.Path, "/")
+	var result []FileInfo
+	for path := range b.files {
+		dir := filepath.Dir(path)
+		if dir == reqPath {
+			result = append(result, FileInfo{Path: path})
+		}
+	}
+	return result, nil
+}
+
+func (b *inMemoryBackend) Read(ctx context.Context, req *ReadRequest) (string, error) {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+
+	content, ok := b.files[req.FilePath]
+	if !ok {
+		return "", errors.New("file not found")
+	}
+	return content, nil
+}
+
+func (b *inMemoryBackend) Write(ctx context.Context, req *WriteRequest) error {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	b.files[req.FilePath] = req.Content
+	return nil
+}
+
+func (b *inMemoryBackend) Delete(ctx context.Context, req *DeleteRequest) error {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	delete(b.files, req.FilePath)
+	return nil
+}

adk/middlewares/plantask/plantask.go

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2025 CloudWeGo Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package plantask
+
+import (
+	"context"
+	"fmt"
+	"sync"
+
+	"github.com/cloudwego/eino/adk"
+)
+
+// Config is the configuration for the tool search middleware.
+type Config struct {
+	Backend Backend
+	BaseDir string
+}
+
+// New creates a new plantask middleware that provides task management tools for agents.
+// It adds TaskCreate, TaskGet, TaskUpdate, and TaskList tools to the agent's tool set,
+// allowing agents to create and manage structured task lists during coding sessions.
+func New(ctx context.Context, config *Config) (adk.ChatModelAgentMiddleware, error) {
+	if config == nil {
+		return nil, fmt.Errorf("config is required")
+	}
+	if config.Backend == nil {
+		return nil, fmt.Errorf("backend is required")
+	}
+	if config.BaseDir == "" {
+		return nil, fmt.Errorf("baseDir is required")
+	}
+
+	return &middleware{backend: config.Backend, baseDir: config.BaseDir}, nil
+}
+
+type middleware struct {
+	adk.BaseChatModelAgentMiddleware
+	backend Backend
+	baseDir string
+}
+
+func (m *middleware) BeforeAgent(ctx context.Context, runCtx *adk.ChatModelAgentContext) (context.Context, *adk.ChatModelAgentContext, error) {
+	if runCtx == nil {
+		return ctx, runCtx, nil
+	}
+
+	nRunCtx := *runCtx
+	lock := sync.Mutex{}
+	nRunCtx.Tools = append(nRunCtx.Tools,
+		newTaskCreateTool(m.backend, m.baseDir, &lock),
+		newTaskGetTool(m.backend, m.baseDir, &lock),
+		newTaskUpdateTool(m.backend, m.baseDir, &lock),
+		newTaskListTool(m.backend, m.baseDir, &lock),
+	)
+
+	return ctx, &nRunCtx, nil
+}

adk/middlewares/plantask/plantask_test.go

@@ -0,0 +1,124 @@
+/*
+ * Copyright 2025 CloudWeGo Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package plantask
+
+import (
+	"context"
+	"sync"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/cloudwego/eino/adk"
+	"github.com/cloudwego/eino/components/tool"
+)
+
+func TestNew(t *testing.T) {
+	ctx := context.Background()
+
+	_, err := New(ctx, nil)
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "config is required")
+
+	_, err = New(ctx, &Config{})
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "backend is required")
+
+	_, err = New(ctx, &Config{Backend: newInMemoryBackend()})
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "baseDir is required")
+
+	m, err := New(ctx, &Config{Backend: newInMemoryBackend(), BaseDir: "/tmp/tasks"})
+	assert.NoError(t, err)
+	assert.NotNil(t, m)
+}
+
+func TestMiddlewareBeforeAgent(t *testing.T) {
+	ctx := context.Background()
+	backend := newInMemoryBackend()
+	baseDir := "/tmp/tasks"
+
+	m, err := New(ctx, &Config{Backend: backend, BaseDir: baseDir})
+	assert.NoError(t, err)
+
+	mw := m.(*middleware)
+
+	ctx, runCtx, err := mw.BeforeAgent(ctx, nil)
+	assert.NoError(t, err)
+	assert.Nil(t, runCtx)
+
+	runCtx = &adk.ChatModelAgentContext{
+		Tools: []tool.BaseTool{},
+	}
+	ctx, newRunCtx, err := mw.BeforeAgent(ctx, runCtx)
+	assert.NoError(t, err)
+	assert.NotNil(t, newRunCtx)
+	assert.Len(t, newRunCtx.Tools, 4)
+
+	toolNames := make([]string, 0, 4)
+	for _, t := range newRunCtx.Tools {
+		info, _ := t.Info(ctx)
+		toolNames = append(toolNames, info.Name)
+	}
+	assert.Contains(t, toolNames, "TaskCreate")
+	assert.Contains(t, toolNames, "TaskGet")
+	assert.Contains(t, toolNames, "TaskUpdate")
+	assert.Contains(t, toolNames, "TaskList")
+}
+
+func TestIntegration(t *testing.T) {
+	ctx := context.Background()
+	backend := newInMemoryBackend()
+	baseDir := "/tmp/tasks"
+	lock := &sync.Mutex{}
+
+	createTool := newTaskCreateTool(backend, baseDir, lock)
+	getTool := newTaskGetTool(backend, baseDir, lock)
+	updateTool := newTaskUpdateTool(backend, baseDir, lock)
+	listTool := newTaskListTool(backend, baseDir, lock)
+
+	result, err := createTool.InvokableRun(ctx, `{"subject": "Task 1", "description": "First task"}`)
+	assert.NoError(t, err)
+	assert.Contains(t, result, "Task #1")
+
+	result, err = createTool.InvokableRun(ctx, `{"subject": "Task 2", "description": "Second task"}`)
+	assert.NoError(t, err)
+	assert.Contains(t, result, "Task #2")
+
+	_, err = updateTool.InvokableRun(ctx, `{"taskId": "2", "addBlockedBy": ["1"]}`)
+	assert.NoError(t, err)
+
+	result, err = listTool.InvokableRun(ctx, `{}`)
+	assert.NoError(t, err)
+	assert.Contains(t, result, "#1 [pending] Task 1")
+	assert.Contains(t, result, "#2 [pending] Task 2")
+	assert.Contains(t, result, "[blocked by #1]")
+
+	_, err = updateTool.InvokableRun(ctx, `{"taskId": "1", "status": "in_progress"}`)
+	assert.NoError(t, err)
+
+	result, err = getTool.InvokableRun(ctx, `{"taskId": "1"}`)
+	assert.NoError(t, err)
+	assert.Contains(t, result, "Status: in_progress")
+
+	_, err = updateTool.InvokableRun(ctx, `{"taskId": "1", "status": "completed"}`)
+	assert.NoError(t, err)
+
+	result, err = listTool.InvokableRun(ctx, `{}`)
+	assert.NoError(t, err)
+	assert.Contains(t, result, "#1 [completed] Task 1")
+}

adk/middlewares/plantask/task.go

@@ -0,0 +1,123 @@
+/*
+ * Copyright 2025 CloudWeGo Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package plantask
+
+import (
+	"context"
+	"regexp"
+
+	"github.com/cloudwego/eino/adk/middlewares/filesystem"
+)
+
+var validTaskIDRegex = regexp.MustCompile(`^\d+$`)
+
+const highWatermarkFileName = ".highwatermark"
+
+type task struct {
+	ID          string         `json:"id"`
+	Subject     string         `json:"subject"`
+	Description string         `json:"description"`
+	Status      string         `json:"status"`
+	Blocks      []string       `json:"blocks"`
+	BlockedBy   []string       `json:"blockedBy"`
+	ActiveForm  string         `json:"activeForm,omitempty"`
+	Owner       string         `json:"owner,omitempty"`
+	Metadata    map[string]any `json:"metadata,omitempty"`
+}
+
+type taskOut struct {
+	Result string `json:"result"`
+}
+
+const (
+	taskStatusPending    = "pending"
+	taskStatusInProgress = "in_progress"
+	taskStatusCompleted  = "completed"
+	taskStatusDeleted    = "deleted"
+)
+
+type FileInfo = filesystem.FileInfo
+type LsInfoRequest = filesystem.LsInfoRequest
+type ReadRequest = filesystem.ReadRequest
+type WriteRequest = filesystem.WriteRequest
+
+type DeleteRequest struct {
+	FilePath string
+}
+
+// Backend defines the storage interface for task persistence.
+// Implementations can use local filesystem, remote storage, or any other storage backend.
+type Backend interface {
+	// LsInfo lists file information in the specified directory.
+	LsInfo(ctx context.Context, req *LsInfoRequest) ([]FileInfo, error)
+	// Read reads the content of a file.
+	Read(ctx context.Context, req *ReadRequest) (string, error)
+	// Write writes content to a file, creating it if it doesn't exist.
+	Write(ctx context.Context, req *WriteRequest) error
+	// Delete removes a file from storage.
+	Delete(ctx context.Context, req *DeleteRequest) error
+}
+
+func isValidTaskID(taskID string) bool {
+	return validTaskIDRegex.MatchString(taskID)
+}
+
+func appendUnique(slice []string, items ...string) []string {
+	seen := make(map[string]struct{}, len(slice))
+	for _, s := range slice {
+		seen[s] = struct{}{}
+	}
+	for _, item := range items {
+		if _, exists := seen[item]; !exists {
+			slice = append(slice, item)
+			seen[item] = struct{}{}
+		}
+	}
+	return slice
+}
+
+func hasCyclicDependency(taskMap map[string]*task, blockerID, blockedID string) bool {
+	if blockerID == blockedID {
+		return true
+	}
+
+	visited := make(map[string]bool)
+	return canReach(taskMap, blockedID, blockerID, visited)
+}
+
+func canReach(taskMap map[string]*task, fromID, toID string, visited map[string]bool) bool {
+	if fromID == toID {
+		return true
+	}
+	if visited[fromID] {
+		return false
+	}
+	visited[fromID] = true
+
+	fromTask, exists := taskMap[fromID]
+	if !exists {
+		return false
+	}
+
+	for _, blockedID := range fromTask.Blocks {
+		if canReach(taskMap, blockedID, toID, visited) {
+			return true
+		}
+	}
+
+	return false
+}