Files
coder/codersdk/toolsdk/workspace.go
T

385 lines
13 KiB
Go

package toolsdk
import (
"context"
"strings"
"time"
"golang.org/x/xerrors"
"github.com/coder/coder/v2/codersdk/toolsdk/tooldef"
"github.com/coder/coder/v2/codersdk/toolsdk/workspacetools"
"github.com/coder/coder/v2/codersdk/workspacesdk"
)
// The workspace file and process tools share their arguments, behavior,
// and results with the Coder Agents tools (see workspacetools). The MCP
// versions add a workspace argument because an MCP session is not bound
// to a single workspace, and they report invalid arguments and agent API
// failures as MCP tool errors. A parity test in coderd/mcp keeps the
// schemas aligned.
// workspaceToolNames are the MCP names of the workspace tools, used in
// shared descriptions and follow-up hints.
var workspaceToolNames = workspacetools.ToolNames{
Execute: ToolNameWorkspaceExecute,
ProcessOutput: ToolNameWorkspaceProcessOutput,
ProcessList: ToolNameWorkspaceProcessList,
ReadFile: ToolNameWorkspaceReadFile,
}
// maxWorkspaceToolWait bounds how long an MCP call blocks on a command.
// Each MCP request must return before the client gives up, otherwise the
// background_process_id needed to follow up is lost. It matches the
// agent's maximum blocking wait for process output.
const maxWorkspaceToolWait = 5 * time.Minute
func workspaceProperty() map[string]any {
return map[string]any{
"type": "string",
"description": workspaceAgentDescription,
}
}
// workspaceToolError converts an agent API error to the tool error
// returned to the model, dropping transport metadata.
func workspaceToolError(err error) error {
return xerrors.New(workspacetools.AgentAPIErrorMessage(err))
}
// WorkspaceReadFileArgs are the arguments of WorkspaceReadFile.
type WorkspaceReadFileArgs struct {
Workspace string `json:"workspace"`
Path string `json:"path"`
Offset *int64 `json:"offset,omitempty"`
Limit *int64 `json:"limit,omitempty"`
}
// WorkspaceReadFile reads line-numbered content from a workspace file.
var WorkspaceReadFile = Tool[WorkspaceReadFileArgs, workspacetools.ReadFileResult]{
Tool: tooldef.Tool{
Name: ToolNameWorkspaceReadFile,
Description: workspacetools.ReadFileDescription,
Schema: tooldef.Schema{
Properties: map[string]any{
"workspace": workspaceProperty(),
"path": map[string]any{"type": "string"},
"offset": map[string]any{"type": "integer"},
"limit": map[string]any{"type": "integer"},
},
Required: []string{"workspace", "path"},
},
},
MCPAnnotations: mcpReadOnlyAnnotations,
UserClientOptional: true,
Handler: func(ctx context.Context, deps Deps, args WorkspaceReadFileArgs) (workspacetools.ReadFileResult, error) {
conn, err := openAgentConn(ctx, deps, args.Workspace)
if err != nil {
return workspacetools.ReadFileResult{}, err
}
defer conn.Close()
res, err := workspacetools.ReadFile(ctx, conn, args.Path, args.Offset, args.Limit)
if err != nil {
return workspacetools.ReadFileResult{}, workspaceToolError(err)
}
return res, nil
},
}
// WorkspaceWriteFileArgs are the arguments of WorkspaceWriteFile.
type WorkspaceWriteFileArgs struct {
Workspace string `json:"workspace"`
Path string `json:"path"`
Content string `json:"content"`
}
// WorkspaceWriteFile creates or replaces a workspace file.
var WorkspaceWriteFile = Tool[WorkspaceWriteFileArgs, workspacetools.OKResult]{
Tool: tooldef.Tool{
Name: ToolNameWorkspaceWriteFile,
Description: "Create a file in the workspace or overwrite an existing one with the given content. " +
"Use " + ToolNameWorkspaceEditFiles + " for targeted changes to an existing file.",
Schema: tooldef.Schema{
Properties: map[string]any{
"workspace": workspaceProperty(),
"path": map[string]any{
"type": "string",
"description": "Absolute path of the file to write.",
},
"content": map[string]any{
"type": "string",
"description": workspacetools.WriteFileContentDescription,
},
},
Required: []string{"workspace", "path", "content"},
},
},
MCPAnnotations: mcpDestructiveAnnotations,
UserClientOptional: true,
Handler: func(ctx context.Context, deps Deps, args WorkspaceWriteFileArgs) (workspacetools.OKResult, error) {
path := strings.TrimSpace(args.Path)
if path == "" {
return workspacetools.OKResult{}, xerrors.New("path is required")
}
conn, err := openAgentConn(ctx, deps, args.Workspace)
if err != nil {
return workspacetools.OKResult{}, err
}
defer conn.Close()
if err := conn.WriteFile(ctx, path, strings.NewReader(args.Content)); err != nil {
return workspacetools.OKResult{}, workspaceToolError(err)
}
return workspacetools.OKResult{OK: true}, nil
},
}
// WorkspaceEditFilesArgs are the arguments of WorkspaceEditFiles.
type WorkspaceEditFilesArgs struct {
Workspace string `json:"workspace"`
Files []workspacesdk.FileEdits `json:"files"`
}
// WorkspaceEditFiles applies text replacements to workspace files.
var WorkspaceEditFiles = Tool[WorkspaceEditFilesArgs, workspacetools.EditFilesResult]{
Tool: tooldef.Tool{
Name: ToolNameWorkspaceEditFiles,
Description: workspacetools.EditFilesDescription,
Schema: tooldef.Schema{
Properties: map[string]any{
"workspace": workspaceProperty(),
"files": map[string]any{
"type": "array",
"description": workspacetools.EditFilesFilesDescription,
"items": map[string]any{
"type": "object",
"properties": map[string]any{
"path": map[string]any{
"type": "string",
"description": "The absolute path of the file to edit, for example /home/coder/project/main.go.",
},
"edits": map[string]any{
"type": "array",
"description": "Edits that replace old text with new text, applied to this file in order.",
"items": map[string]any{
"type": "object",
"properties": map[string]any{
"old_text": map[string]any{
"type": "string",
"description": "Existing text in the file to replace. Matching is fuzzy: whitespace and indentation differences are tolerated.",
},
"new_text": map[string]any{
"type": "string",
"description": "Text that replaces old_text.",
},
"replace_all": map[string]any{
"type": "boolean",
"description": "Replace every match of old_text instead of erroring when it matches more than once.",
},
},
"required": []string{"old_text", "new_text"},
},
},
},
"required": []string{"path", "edits"},
},
},
},
Required: []string{"workspace", "files"},
},
},
MCPAnnotations: mcpDestructiveAnnotations,
UserClientOptional: true,
Handler: func(ctx context.Context, deps Deps, args WorkspaceEditFilesArgs) (workspacetools.EditFilesResult, error) {
if err := workspacetools.ValidateFileEdits(args.Files); err != nil {
return workspacetools.EditFilesResult{}, err
}
conn, err := openAgentConn(ctx, deps, args.Workspace)
if err != nil {
return workspacetools.EditFilesResult{}, err
}
defer conn.Close()
res, err := workspacetools.EditFiles(ctx, conn, args.Files)
if err != nil {
return workspacetools.EditFilesResult{}, workspaceToolError(err)
}
return res, nil
},
}
// WorkspaceExecuteArgs are the arguments of WorkspaceExecute.
type WorkspaceExecuteArgs struct {
Workspace string `json:"workspace"`
Command string `json:"command"`
Timeout *string `json:"timeout,omitempty"`
WorkDir *string `json:"workdir,omitempty"`
RunInBackground *bool `json:"run_in_background,omitempty"`
}
// WorkspaceExecute runs a shell command in a workspace.
var WorkspaceExecute = Tool[WorkspaceExecuteArgs, workspacetools.ExecuteResult]{
Tool: tooldef.Tool{
Name: ToolNameWorkspaceExecute,
Description: workspacetools.ExecuteDescription(workspaceToolNames),
Schema: tooldef.Schema{
Properties: map[string]any{
"workspace": workspaceProperty(),
"command": map[string]any{
"type": "string",
"description": workspacetools.ExecuteCommandDescription,
},
"timeout": map[string]any{
"type": "string",
"description": workspacetools.ExecuteTimeoutDescription,
},
"workdir": map[string]any{
"type": "string",
"description": workspacetools.ExecuteWorkDirDescription,
},
"run_in_background": map[string]any{
"type": "boolean",
"description": workspacetools.ExecuteRunInBackgroundDescription(workspaceToolNames),
},
},
Required: []string{"workspace", "command"},
},
},
MCPAnnotations: mcpDestructiveAnnotations,
Handler: func(ctx context.Context, deps Deps, args WorkspaceExecuteArgs) (workspacetools.ExecuteResult, error) {
if args.Command == "" {
return workspacetools.ExecuteResult{}, xerrors.New("command is required")
}
conn, err := openAgentConn(ctx, deps, args.Workspace)
if err != nil {
return workspacetools.ExecuteResult{}, err
}
defer conn.Close()
req := workspacetools.ExecuteRequest{
Command: args.Command,
Timeout: args.Timeout,
RunInBackground: args.RunInBackground != nil && *args.RunInBackground,
MaxTimeout: maxWorkspaceToolWait,
Names: workspaceToolNames,
}
if args.WorkDir != nil {
req.WorkDir = *args.WorkDir
}
return workspacetools.Execute(ctx, conn, req)
},
}
// WorkspaceProcessOutputArgs are the arguments of WorkspaceProcessOutput.
type WorkspaceProcessOutputArgs struct {
Workspace string `json:"workspace"`
ProcessID string `json:"process_id"`
WaitTimeout *string `json:"wait_timeout,omitempty"`
}
// WorkspaceProcessOutput retrieves the output of a workspace process.
var WorkspaceProcessOutput = Tool[WorkspaceProcessOutputArgs, workspacetools.ExecuteResult]{
Tool: tooldef.Tool{
Name: ToolNameWorkspaceProcessOutput,
Description: workspacetools.ProcessOutputDescription(workspaceToolNames),
Schema: tooldef.Schema{
Properties: map[string]any{
"workspace": workspaceProperty(),
"process_id": map[string]any{"type": "string"},
"wait_timeout": map[string]any{
"type": "string",
"description": workspacetools.ProcessOutputWaitTimeoutDescription,
},
},
Required: []string{"workspace", "process_id"},
},
},
MCPAnnotations: mcpReadOnlyAnnotations,
Handler: func(ctx context.Context, deps Deps, args WorkspaceProcessOutputArgs) (workspacetools.ExecuteResult, error) {
if args.ProcessID == "" {
return workspacetools.ExecuteResult{}, xerrors.New("process_id is required")
}
conn, err := openAgentConn(ctx, deps, args.Workspace)
if err != nil {
return workspacetools.ExecuteResult{}, err
}
defer conn.Close()
return workspacetools.ProcessOutput(ctx, conn, workspacetools.ProcessOutputRequest{
ProcessID: args.ProcessID,
WaitTimeout: args.WaitTimeout,
MaxWait: maxWorkspaceToolWait,
})
},
}
// WorkspaceProcessListArgs are the arguments of WorkspaceProcessList.
type WorkspaceProcessListArgs struct {
Workspace string `json:"workspace"`
}
// WorkspaceProcessList lists processes started outside a chat in a
// workspace.
var WorkspaceProcessList = Tool[WorkspaceProcessListArgs, workspacesdk.ListProcessesResponse]{
Tool: tooldef.Tool{
Name: ToolNameWorkspaceProcessList,
Description: workspacetools.ProcessListDescription,
Schema: tooldef.Schema{
Properties: map[string]any{
"workspace": workspaceProperty(),
},
Required: []string{"workspace"},
},
},
MCPAnnotations: mcpReadOnlyAnnotations,
Handler: func(ctx context.Context, deps Deps, args WorkspaceProcessListArgs) (workspacesdk.ListProcessesResponse, error) {
conn, err := openAgentConn(ctx, deps, args.Workspace)
if err != nil {
return workspacesdk.ListProcessesResponse{}, err
}
defer conn.Close()
resp, err := conn.ListProcesses(ctx)
if err != nil {
return workspacesdk.ListProcessesResponse{}, xerrors.Errorf("list processes: %s", workspacetools.AgentAPIErrorMessage(err))
}
return resp, nil
},
}
// WorkspaceProcessSignalArgs are the arguments of WorkspaceProcessSignal.
type WorkspaceProcessSignalArgs struct {
Workspace string `json:"workspace"`
ProcessID string `json:"process_id"`
Signal string `json:"signal"`
}
// WorkspaceProcessSignal terminates or kills a workspace process.
var WorkspaceProcessSignal = Tool[WorkspaceProcessSignalArgs, workspacetools.SignalResult]{
Tool: tooldef.Tool{
Name: ToolNameWorkspaceProcessSignal,
Description: workspacetools.ProcessSignalDescription(workspaceToolNames),
Schema: tooldef.Schema{
Properties: map[string]any{
"workspace": workspaceProperty(),
"process_id": map[string]any{"type": "string"},
"signal": map[string]any{"type": "string"},
},
Required: []string{"workspace", "process_id", "signal"},
},
},
MCPAnnotations: mcpDestructiveAnnotations,
Handler: func(ctx context.Context, deps Deps, args WorkspaceProcessSignalArgs) (workspacetools.SignalResult, error) {
if args.ProcessID == "" {
return workspacetools.SignalResult{}, xerrors.New("process_id is required")
}
if err := workspacetools.ValidateSignal(args.Signal); err != nil {
return workspacetools.SignalResult{}, err
}
conn, err := openAgentConn(ctx, deps, args.Workspace)
if err != nil {
return workspacetools.SignalResult{}, err
}
defer conn.Close()
if err := conn.SignalProcess(ctx, args.ProcessID, args.Signal); err != nil {
return workspacetools.SignalResult{}, xerrors.Errorf("signal process: %s", workspacetools.AgentAPIErrorMessage(err))
}
return workspacetools.SignalSent(args.ProcessID, args.Signal), nil
},
}