agent_tasks.go

// Copyright 2026 The go-github AUTHORS. All rights reserved.
//
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

package github

import (
	"context"
	"encoding/json"
	"fmt"
	"time"
)

// AgentTasksService handles communication with the agent tasks
// methods of the GitHub API.
//
// GitHub API docs: https://docs.github.com/rest/agent-tasks/agent-tasks?apiVersion=2026-03-10
type AgentTasksService service

// AgentTask represents a Copilot cloud agent task.
type AgentTask struct {
	ID           *string              `json:"id,omitempty"`
	URL          *string              `json:"url,omitempty"`
	HTMLURL      *string              `json:"html_url,omitempty"`
	Name         *string              `json:"name,omitempty"`
	Creator      *User                `json:"creator,omitempty"`
	CreatorType  *string              `json:"creator_type,omitempty"`
	Owner        *User                `json:"owner,omitempty"`
	Repository   *Repository          `json:"repository,omitempty"`
	State        *string              `json:"state,omitempty"`
	SessionCount *int                 `json:"session_count,omitempty"`
	Artifacts    []*AgentTaskArtifact `json:"artifacts,omitempty"`
	ArchivedAt   *Timestamp           `json:"archived_at,omitempty"`
	CreatedAt    *Timestamp           `json:"created_at,omitempty"`
	UpdatedAt    *Timestamp           `json:"updated_at,omitempty"`
	Sessions     []*AgentTaskSession  `json:"sessions,omitempty"`
}

// AgentTaskArtifact represents an artifact produced by an agent task.
type AgentTaskArtifact struct {
	Provider *string         `json:"provider,omitempty"`
	Type     *string         `json:"type,omitempty"`
	Data     json.RawMessage `json:"data,omitempty"`
}

// AgentTaskSession represents a session associated with an agent task.
type AgentTaskSession struct {
	ID          *string     `json:"id,omitempty"`
	Name        *string     `json:"name,omitempty"`
	User        *User       `json:"user,omitempty"`
	Owner       *User       `json:"owner,omitempty"`
	Repository  *Repository `json:"repository,omitempty"`
	TaskID      *string     `json:"task_id,omitempty"`
	State       *string     `json:"state,omitempty"`
	CreatedAt   *Timestamp  `json:"created_at,omitempty"`
	UpdatedAt   *Timestamp  `json:"updated_at,omitempty"`
	CompletedAt *Timestamp  `json:"completed_at,omitempty"`
	Prompt      *string     `json:"prompt,omitempty"`
	HeadRef     *string     `json:"head_ref,omitempty"`
	BaseRef     *string     `json:"base_ref,omitempty"`
	Model       *string     `json:"model,omitempty"`
}

// AgentTaskList represents a list of agent tasks.
type AgentTaskList struct {
	Tasks []*AgentTask `json:"tasks,omitempty"`
}

// AgentTaskListOptions specifies optional parameters to AgentTasksService.List.
type AgentTaskListOptions struct {
	// Sort specifies the field to sort results by. Possible values are: updated_at, created_at.
	Sort string `url:"sort,omitempty"`

	// Direction specifies the direction to sort results by. Possible values are: asc, desc.
	Direction string `url:"direction,omitempty"`

	// State is a comma-separated list of task states to filter by.
	State string `url:"state,omitempty"`

	// IsArchived filters tasks by archived status.
	IsArchived bool `url:"is_archived,omitempty"`

	// Since filters tasks updated at or after this time.
	Since *time.Time `url:"since,omitempty"`

	ListOptions
}

// AgentTaskListByRepoOptions specifies optional parameters to AgentTasksService.ListByRepo.
type AgentTaskListByRepoOptions struct {
	AgentTaskListOptions

	// CreatorID filters tasks by creator user ID.
	CreatorID int64 `url:"creator_id,omitempty"`
}

// CreateAgentTaskOptions represents the parameters for creating an agent task.
type CreateAgentTaskOptions struct {
	// Prompt is the user's prompt for the agent.
	Prompt string `json:"prompt"`

	// Model is the model to use for this task.
	Model *string `json:"model,omitempty"`

	// CreatePullRequest indicates whether to create a pull request.
	CreatePullRequest *bool `json:"create_pull_request,omitempty"`

	// BaseRef is the base ref for the new branch or pull request.
	BaseRef *string `json:"base_ref,omitempty"`
}

// ListByRepo lists tasks for a repository.
//
// GitHub API docs: https://docs.github.com/rest/agent-tasks/agent-tasks?apiVersion=2022-11-28#list-tasks-for-repository
//
//meta:operation GET /agents/repos/{owner}/{repo}/tasks
func (s *AgentTasksService) ListByRepo(ctx context.Context, owner, repo string, opts *AgentTaskListByRepoOptions) (*AgentTaskList, *Response, error) {
	u := fmt.Sprintf("agents/repos/%v/%v/tasks", owner, repo)
	u, err := addOptions(u, opts)
	if err != nil {
		return nil, nil, err
	}

	req, err := s.client.NewRequest(ctx, "GET", u, nil, WithVersion("2026-03-10"))
	if err != nil {
		return nil, nil, err
	}

	var tasks *AgentTaskList
	resp, err := s.client.Do(req, &tasks)
	if err != nil {
		return nil, resp, err
	}

	return tasks, resp, nil
}

// Create starts a new Copilot cloud agent task for a repository.
//
// GitHub API docs: https://docs.github.com/rest/agent-tasks/agent-tasks?apiVersion=2022-11-28#start-a-task
//
//meta:operation POST /agents/repos/{owner}/{repo}/tasks
func (s *AgentTasksService) Create(ctx context.Context, owner, repo string, opts *CreateAgentTaskOptions) (*AgentTask, *Response, error) {
	u := fmt.Sprintf("agents/repos/%v/%v/tasks", owner, repo)

	req, err := s.client.NewRequest(ctx, "POST", u, opts, WithVersion("2026-03-10"))
	if err != nil {
		return nil, nil, err
	}

	var task *AgentTask
	resp, err := s.client.Do(req, &task)
	if err != nil {
		return nil, resp, err
	}

	return task, resp, nil
}

// GetByRepoAndID gets a repository task by ID.
//
// GitHub API docs: https://docs.github.com/rest/agent-tasks/agent-tasks?apiVersion=2022-11-28#get-a-task-by-repo
//
//meta:operation GET /agents/repos/{owner}/{repo}/tasks/{task_id}
func (s *AgentTasksService) GetByRepoAndID(ctx context.Context, owner, repo, taskID string) (*AgentTask, *Response, error) {
	u := fmt.Sprintf("agents/repos/%v/%v/tasks/%v", owner, repo, taskID)

	req, err := s.client.NewRequest(ctx, "GET", u, nil, WithVersion("2026-03-10"))
	if err != nil {
		return nil, nil, err
	}

	var task *AgentTask
	resp, err := s.client.Do(req, &task)
	if err != nil {
		return nil, resp, err
	}

	return task, resp, nil
}

// List lists tasks for the authenticated user.
//
// GitHub API docs: https://docs.github.com/rest/agent-tasks/agent-tasks?apiVersion=2022-11-28#list-tasks
//
//meta:operation GET /agents/tasks
func (s *AgentTasksService) List(ctx context.Context, opts *AgentTaskListOptions) (*AgentTaskList, *Response, error) {
	return s.list(ctx, "agents/tasks", opts)
}

func (s *AgentTasksService) list(ctx context.Context, u string, opts *AgentTaskListOptions) (*AgentTaskList, *Response, error) {
	u, err := addOptions(u, opts)
	if err != nil {
		return nil, nil, err
	}

	req, err := s.client.NewRequest(ctx, "GET", u, nil, WithVersion("2026-03-10"))
	if err != nil {
		return nil, nil, err
	}

	var tasks *AgentTaskList
	resp, err := s.client.Do(req, &tasks)
	if err != nil {
		return nil, resp, err
	}

	return tasks, resp, nil
}

// Get gets a task by ID for the authenticated user.
//
// GitHub API docs: https://docs.github.com/rest/agent-tasks/agent-tasks?apiVersion=2022-11-28#get-a-task-by-id
//
//meta:operation GET /agents/tasks/{task_id}
func (s *AgentTasksService) Get(ctx context.Context, taskID string) (*AgentTask, *Response, error) {
	u := fmt.Sprintf("agents/tasks/%v", taskID)

	req, err := s.client.NewRequest(ctx, "GET", u, nil, WithVersion("2026-03-10"))
	if err != nil {
		return nil, nil, err
	}

	var task *AgentTask
	resp, err := s.client.Do(req, &task)
	if err != nil {
		return nil, resp, err
	}

	return task, resp, nil
}