coder/codersdk/aitasks.go

package codersdk

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"strings"
	"time"

	"github.com/google/uuid"
	"golang.org/x/xerrors"
)

// CreateTaskRequest represents the request to create a new task.
type CreateTaskRequest struct {
	TemplateVersionID       uuid.UUID `json:"template_version_id" format:"uuid"`
	TemplateVersionPresetID uuid.UUID `json:"template_version_preset_id,omitempty" format:"uuid"`
	Input                   string    `json:"input"`
	Name                    string    `json:"name,omitempty"`
	DisplayName             string    `json:"display_name,omitempty"`
}

// CreateTask creates a new task.
func (c *Client) CreateTask(ctx context.Context, user string, request CreateTaskRequest) (Task, error) {
	res, err := c.Request(ctx, http.MethodPost, fmt.Sprintf("/api/v2/tasks/%s", user), request)
	if err != nil {
		return Task{}, err
	}
	defer res.Body.Close()

	if res.StatusCode != http.StatusCreated {
		return Task{}, ReadBodyAsError(res)
	}

	var task Task
	if err := json.NewDecoder(res.Body).Decode(&task); err != nil {
		return Task{}, err
	}

	return task, nil
}

// TaskStatus represents the status of a task.
type TaskStatus string

const (
	// TaskStatusPending indicates the task has been created but no workspace
	// has been provisioned yet, or the workspace build job status is unknown.
	TaskStatusPending TaskStatus = "pending"
	// TaskStatusInitializing indicates the workspace build is pending/running,
	// the agent is connecting, or apps are initializing.
	TaskStatusInitializing TaskStatus = "initializing"
	// TaskStatusActive indicates the task's workspace is running with a
	// successful start transition, the agent is connected, and all workspace
	// apps are either healthy or disabled.
	TaskStatusActive TaskStatus = "active"
	// TaskStatusPaused indicates the task's workspace has been stopped or
	// deleted (stop/delete transition with successful job status).
	TaskStatusPaused TaskStatus = "paused"
	// TaskStatusUnknown indicates the task's status cannot be determined
	// based on the workspace build, agent lifecycle, or app health states.
	TaskStatusUnknown TaskStatus = "unknown"
	// TaskStatusError indicates the task's workspace build job has failed,
	// or the workspace apps are reporting unhealthy status.
	TaskStatusError TaskStatus = "error"
)

func AllTaskStatuses() []TaskStatus {
	return []TaskStatus{
		TaskStatusPending,
		TaskStatusInitializing,
		TaskStatusActive,
		TaskStatusPaused,
		TaskStatusError,
		TaskStatusUnknown,
	}
}

// TaskState represents the high-level lifecycle of a task.
type TaskState string

// TaskState enums.
const (
	// TaskStateWorking indicates the AI agent is actively processing work.
	// Reported when the agent is performing actions or the screen is changing.
	TaskStateWorking TaskState = "working"
	// TaskStateIdle indicates the AI agent's screen is stable and no work
	// is being performed. Reported automatically by the screen watcher.
	TaskStateIdle TaskState = "idle"
	// TaskStateComplete indicates the AI agent has successfully completed
	// the task. Reported via the workspace app status.
	TaskStateComplete TaskState = "complete"
	// TaskStateFailed indicates the AI agent reported a failure state.
	// Reported via the workspace app status.
	TaskStateFailed TaskState = "failed"
)

// Task represents a task.
type Task struct {
	ID                      uuid.UUID                `json:"id" format:"uuid" table:"id"`
	OrganizationID          uuid.UUID                `json:"organization_id" format:"uuid" table:"organization id"`
	OwnerID                 uuid.UUID                `json:"owner_id" format:"uuid" table:"owner id"`
	OwnerName               string                   `json:"owner_name" table:"owner name"`
	OwnerAvatarURL          string                   `json:"owner_avatar_url,omitempty" table:"owner avatar url"`
	Name                    string                   `json:"name" table:"name,default_sort"`
	DisplayName             string                   `json:"display_name" table:"display_name"`
	TemplateID              uuid.UUID                `json:"template_id" format:"uuid" table:"template id"`
	TemplateVersionID       uuid.UUID                `json:"template_version_id" format:"uuid" table:"template version id"`
	TemplateName            string                   `json:"template_name" table:"template name"`
	TemplateDisplayName     string                   `json:"template_display_name" table:"template display name"`
	TemplateIcon            string                   `json:"template_icon" table:"template icon"`
	WorkspaceID             uuid.NullUUID            `json:"workspace_id" format:"uuid" table:"workspace id"`
	WorkspaceName           string                   `json:"workspace_name" table:"workspace name"`
	WorkspaceStatus         WorkspaceStatus          `json:"workspace_status,omitempty" enums:"pending,starting,running,stopping,stopped,failed,canceling,canceled,deleting,deleted" table:"workspace status"`
	WorkspaceBuildNumber    int32                    `json:"workspace_build_number,omitempty" table:"workspace build number"`
	WorkspaceAgentID        uuid.NullUUID            `json:"workspace_agent_id" format:"uuid" table:"workspace agent id"`
	WorkspaceAgentLifecycle *WorkspaceAgentLifecycle `json:"workspace_agent_lifecycle" table:"workspace agent lifecycle"`
	WorkspaceAgentHealth    *WorkspaceAgentHealth    `json:"workspace_agent_health" table:"workspace agent health"`
	WorkspaceAppID          uuid.NullUUID            `json:"workspace_app_id" format:"uuid" table:"workspace app id"`
	InitialPrompt           string                   `json:"initial_prompt" table:"initial prompt"`
	Status                  TaskStatus               `json:"status" enums:"pending,initializing,active,paused,unknown,error" table:"status"`
	CurrentState            *TaskStateEntry          `json:"current_state" table:"cs,recursive_inline,empty_nil"`
	CreatedAt               time.Time                `json:"created_at" format:"date-time" table:"created at"`
	UpdatedAt               time.Time                `json:"updated_at" format:"date-time" table:"updated at"`
}

// TaskStateEntry represents a single entry in the task's state history.
type TaskStateEntry struct {
	Timestamp time.Time `json:"timestamp" format:"date-time" table:"-"`
	State     TaskState `json:"state" enum:"working,idle,completed,failed" table:"state"`
	Message   string    `json:"message" table:"message"`
	URI       string    `json:"uri" table:"-"`
}

// TasksFilter filters the list of tasks.
type TasksFilter struct {
	// Owner can be a username, UUID, or "me".
	Owner string `json:"owner,omitempty"`
	// Organization can be an organization name or UUID.
	Organization string `json:"organization,omitempty"`
	// Status filters the tasks by their task status.
	Status TaskStatus `json:"status,omitempty"`
	// FilterQuery allows specifying a raw filter query.
	FilterQuery string `json:"filter_query,omitempty"`
}

// TaskListResponse is the response shape for tasks list.
type TasksListResponse struct {
	Tasks []Task `json:"tasks"`
	Count int    `json:"count"`
}

func (f TasksFilter) asRequestOption() RequestOption {
	return func(r *http.Request) {
		var params []string
		// Make sure all user input is quoted to ensure it's parsed as a single
		// string.
		if f.Owner != "" {
			params = append(params, fmt.Sprintf("owner:%q", f.Owner))
		}
		if f.Organization != "" {
			params = append(params, fmt.Sprintf("organization:%q", f.Organization))
		}
		if f.Status != "" {
			params = append(params, fmt.Sprintf("status:%q", string(f.Status)))
		}
		if f.FilterQuery != "" {
			// If custom stuff is added, just add it on here.
			params = append(params, f.FilterQuery)
		}

		q := r.URL.Query()
		q.Set("q", strings.Join(params, " "))
		r.URL.RawQuery = q.Encode()
	}
}

// Tasks lists all tasks belonging to the user or specified owner.
func (c *Client) Tasks(ctx context.Context, filter *TasksFilter) ([]Task, error) {
	if filter == nil {
		filter = &TasksFilter{}
	}

	res, err := c.Request(ctx, http.MethodGet, "/api/v2/tasks", nil, filter.asRequestOption())
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		return nil, ReadBodyAsError(res)
	}

	var tres TasksListResponse
	if err := json.NewDecoder(res.Body).Decode(&tres); err != nil {
		return nil, err
	}

	return tres.Tasks, nil
}

// TaskByID fetches a single task by its ID.
// Only tasks owned by codersdk.Me are supported.
func (c *Client) TaskByID(ctx context.Context, id uuid.UUID) (Task, error) {
	res, err := c.Request(ctx, http.MethodGet, fmt.Sprintf("/api/v2/tasks/%s/%s", "me", id.String()), nil)
	if err != nil {
		return Task{}, err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		return Task{}, ReadBodyAsError(res)
	}

	var task Task
	if err := json.NewDecoder(res.Body).Decode(&task); err != nil {
		return Task{}, err
	}

	return task, nil
}

// TaskByOwnerAndName fetches a single task by its owner and name.
func (c *Client) TaskByOwnerAndName(ctx context.Context, owner, ident string) (Task, error) {
	if owner == "" {
		owner = Me
	}
	res, err := c.Request(ctx, http.MethodGet, fmt.Sprintf("/api/v2/tasks/%s/%s", owner, ident), nil)
	if err != nil {
		return Task{}, err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		return Task{}, ReadBodyAsError(res)
	}

	var task Task
	if err := json.NewDecoder(res.Body).Decode(&task); err != nil {
		return Task{}, err
	}

	return task, nil
}

func splitTaskIdentifier(identifier string) (owner string, taskName string, err error) {
	parts := strings.Split(identifier, "/")

	switch len(parts) {
	case 1:
		owner = Me
		taskName = parts[0]
	case 2:
		owner = parts[0]
		taskName = parts[1]
	default:
		return "", "", xerrors.Errorf("invalid task identifier: %q", identifier)
	}
	return owner, taskName, nil
}

// TaskByIdentifier fetches and returns a task by an identifier, which may be
// either a UUID, a name (for a task owned by the current user), or a
// "user/task" combination, where user is either a username or UUID.
//
// Since there is no TaskByOwnerAndName endpoint yet, this function uses the
// list endpoint with filtering when a name is provided.
func (c *Client) TaskByIdentifier(ctx context.Context, identifier string) (Task, error) {
	identifier = strings.TrimSpace(identifier)

	// Try parsing as UUID first.
	if taskID, err := uuid.Parse(identifier); err == nil {
		return c.TaskByID(ctx, taskID)
	}

	// Not a UUID, treat as identifier.
	owner, taskName, err := splitTaskIdentifier(identifier)
	if err != nil {
		return Task{}, err
	}

	return c.TaskByOwnerAndName(ctx, owner, taskName)
}

// DeleteTask deletes a task by its ID.
func (c *Client) DeleteTask(ctx context.Context, user string, id uuid.UUID) error {
	res, err := c.Request(ctx, http.MethodDelete, fmt.Sprintf("/api/v2/tasks/%s/%s", user, id.String()), nil)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusAccepted {
		return ReadBodyAsError(res)
	}
	return nil
}

// TaskSendRequest is used to send task input to the tasks sidebar app.
type TaskSendRequest struct {
	Input string `json:"input"`
}

// TaskSend submits task input to the tasks sidebar app.
func (c *Client) TaskSend(ctx context.Context, user string, id uuid.UUID, req TaskSendRequest) error {
	res, err := c.Request(ctx, http.MethodPost, fmt.Sprintf("/api/v2/tasks/%s/%s/send", user, id.String()), req)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusNoContent {
		return ReadBodyAsError(res)
	}
	return nil
}

// UpdateTaskInputRequest is used to update a task's input.
type UpdateTaskInputRequest struct {
	Input string `json:"input"`
}

// UpdateTaskInput updates the task's input.
func (c *Client) UpdateTaskInput(ctx context.Context, user string, id uuid.UUID, req UpdateTaskInputRequest) error {
	res, err := c.Request(ctx, http.MethodPatch, fmt.Sprintf("/api/v2/tasks/%s/%s/input", user, id.String()), req)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusNoContent {
		return ReadBodyAsError(res)
	}
	return nil
}

// PauseTaskResponse represents the response from pausing a task.
type PauseTaskResponse struct {
	WorkspaceBuild *WorkspaceBuild `json:"workspace_build"`
}

// PauseTask pauses a task by stopping its workspace.
func (c *Client) PauseTask(ctx context.Context, user string, id uuid.UUID) (PauseTaskResponse, error) {
	res, err := c.Request(ctx, http.MethodPost, fmt.Sprintf("/api/v2/tasks/%s/%s/pause", user, id.String()), nil)
	if err != nil {
		return PauseTaskResponse{}, err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusAccepted {
		return PauseTaskResponse{}, ReadBodyAsError(res)
	}

	var resp PauseTaskResponse
	if err := json.NewDecoder(res.Body).Decode(&resp); err != nil {
		return PauseTaskResponse{}, err
	}

	return resp, nil
}

// ResumeTaskResponse represents the response from resuming a task.
type ResumeTaskResponse struct {
	WorkspaceBuild *WorkspaceBuild `json:"workspace_build"`
}

func (c *Client) ResumeTask(ctx context.Context, user string, id uuid.UUID) (ResumeTaskResponse, error) {
	res, err := c.Request(ctx, http.MethodPost, fmt.Sprintf("/api/v2/tasks/%s/%s/resume", user, id.String()), nil)
	if err != nil {
		return ResumeTaskResponse{}, err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusAccepted {
		return ResumeTaskResponse{}, ReadBodyAsError(res)
	}

	var resp ResumeTaskResponse
	if err := json.NewDecoder(res.Body).Decode(&resp); err != nil {
		return ResumeTaskResponse{}, err
	}

	return resp, nil
}

// TaskLogType indicates the source of a task log entry.
type TaskLogType string

// TaskLogType enums.
const (
	TaskLogTypeInput  TaskLogType = "input"
	TaskLogTypeOutput TaskLogType = "output"
)

// TaskLogEntry represents a single log entry for a task.
type TaskLogEntry struct {
	ID      int         `json:"id" table:"id"`
	Content string      `json:"content" table:"content"`
	Type    TaskLogType `json:"type" enum:"input,output" table:"type"`
	Time    time.Time   `json:"time" format:"date-time" table:"time,default_sort"`
}

// TaskLogsResponse contains task logs and metadata. When snapshot is false,
// logs are fetched live from the task app. When snapshot is true, logs are
// fetched from a stored snapshot captured during pause.
type TaskLogsResponse struct {
	Logs       []TaskLogEntry `json:"logs"`
	Snapshot   bool           `json:"snapshot,omitempty"`
	SnapshotAt *time.Time     `json:"snapshot_at,omitempty"`
}

// TaskLogs retrieves logs from the task app.
func (c *Client) TaskLogs(ctx context.Context, user string, id uuid.UUID) (TaskLogsResponse, error) {
	res, err := c.Request(ctx, http.MethodGet, fmt.Sprintf("/api/v2/tasks/%s/%s/logs", user, id.String()), nil)
	if err != nil {
		return TaskLogsResponse{}, err
	}
	defer res.Body.Close()

	if res.StatusCode != http.StatusOK {
		return TaskLogsResponse{}, ReadBodyAsError(res)
	}

	var logs TaskLogsResponse
	if err := json.NewDecoder(res.Body).Decode(&logs); err != nil {
		return TaskLogsResponse{}, xerrors.Errorf("decoding task logs response: %w", err)
	}

	return logs, nil
}