feat: add experimental agents support (#22290)

feat: add AI chat system with agent tools and chat UI

Introduce the chatd subsystem and Agents UI for AI-powered chat
within Coder workspaces.

- Add chatd package with chat loop, message compaction, prompt
  management, and LLM provider integration (OpenAI, Anthropic)
- Add agent tools: create workspace, list/read templates, read/write/
  edit files, execute commands
- Add chat API endpoints with streaming, message editing, and
  durable reconnection
- Add database schema and migrations for chats, chat messages, chat
  providers, and chat model configs
- Add RBAC policies and dbauthz enforcement for chat resources
- Add Agents UI pages with conversation timeline, queued messages
  list, diff viewer, and model configuration panel
- Add comprehensive test coverage including coderd integration tests,
  chatd unit tests, and Storybook stories
- Gate feature behind experiments flag

---------

Co-authored-by: Cian Johnston <cian@coder.com>
Co-authored-by: Danielle Maywood <danielle@themaywoods.com>
Co-authored-by: Jeremy Ruppel <jeremy@coder.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

coderd/chatd/chattool/chattool.go

@@ -0,0 +1,33 @@
+package chattool
+
+import (
+	"encoding/json"
+	"unicode/utf8"
+
+	"charm.land/fantasy"
+)
+
+// toolResponse builds a fantasy.ToolResponse from a JSON-serializable
+// result payload.
+func toolResponse(result map[string]any) fantasy.ToolResponse {
+	data, err := json.Marshal(result)
+	if err != nil {
+		return fantasy.NewTextResponse("{}")
+	}
+	return fantasy.NewTextResponse(string(data))
+}
+
+func truncateRunes(value string, maxLen int) string {
+	if maxLen <= 0 || value == "" {
+		return ""
+	}
+	if utf8.RuneCountInString(value) <= maxLen {
+		return value
+	}
+
+	runes := []rune(value)
+	if maxLen > len(runes) {
+		maxLen = len(runes)
+	}
+	return string(runes[:maxLen])
+}

coderd/chatd/chattool/createworkspace.go

@@ -0,0 +1,426 @@
+package chattool
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+
+	"charm.land/fantasy"
+	"github.com/google/uuid"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/coderd/database"
+	"github.com/coder/coder/v2/coderd/util/namesgenerator"
+	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
+)
+
+const (
+	// buildPollInterval is how often we check if the workspace
+	// build has completed.
+	buildPollInterval = 2 * time.Second
+	// buildTimeout is the maximum time to wait for a workspace
+	// build to complete before giving up.
+	buildTimeout = 10 * time.Minute
+	// agentConnectTimeout is the maximum time to wait for the
+	// workspace agent to become reachable after a successful build.
+	agentConnectTimeout = 2 * time.Minute
+	// agentRetryInterval is how often we retry connecting to the
+	// workspace agent.
+	agentRetryInterval = 2 * time.Second
+	// agentAttemptTimeout is the timeout for a single connection
+	// attempt to the workspace agent during the retry loop.
+	agentAttemptTimeout = 5 * time.Second
+	// agentPingTimeout is the timeout for a single agent ping
+	// when checking whether an existing workspace is alive.
+	agentPingTimeout = 5 * time.Second
+)
+
+// CreateWorkspaceFn creates a workspace for the given owner.
+type CreateWorkspaceFn func(
+	ctx context.Context,
+	ownerID uuid.UUID,
+	req codersdk.CreateWorkspaceRequest,
+) (codersdk.Workspace, error)
+
+// AgentConnFunc provides access to workspace agent connections.
+type AgentConnFunc func(
+	ctx context.Context,
+	agentID uuid.UUID,
+) (workspacesdk.AgentConn, func(), error)
+
+// CreateWorkspaceOptions configures the create_workspace tool.
+type CreateWorkspaceOptions struct {
+	DB          database.Store
+	OwnerID     uuid.UUID
+	ChatID      uuid.UUID
+	CreateFn    CreateWorkspaceFn
+	AgentConnFn AgentConnFunc
+	WorkspaceMu *sync.Mutex
+}
+
+type createWorkspaceArgs struct {
+	TemplateID string            `json:"template_id"`
+	Name       string            `json:"name,omitempty"`
+	Parameters map[string]string `json:"parameters,omitempty"`
+}
+
+// CreateWorkspace returns a tool that creates a new workspace from a
+// template. The tool is idempotent: if the chat already has a
+// workspace that is building or running, it returns the existing
+// workspace instead of creating a new one. A mutex prevents parallel
+// calls from creating duplicate workspaces.
+func CreateWorkspace(options CreateWorkspaceOptions) fantasy.AgentTool {
+	return fantasy.NewAgentTool(
+		"create_workspace",
+		"Create a new workspace from a template. Requires a "+
+			"template_id (from list_templates). Optionally provide "+
+			"a name and parameter values (from read_template). "+
+			"If no name is given, one will be generated. "+
+			"This tool is idempotent — if the chat already has a "+
+			"workspace that is building or running, the existing "+
+			"workspace is returned.",
+		func(ctx context.Context, args createWorkspaceArgs, _ fantasy.ToolCall) (fantasy.ToolResponse, error) {
+			if options.CreateFn == nil {
+				return fantasy.NewTextErrorResponse("workspace creator is not configured"), nil
+			}
+
+			templateIDStr := strings.TrimSpace(args.TemplateID)
+			if templateIDStr == "" {
+				return fantasy.NewTextErrorResponse("template_id is required; use list_templates to find one"), nil
+			}
+			templateID, err := uuid.Parse(templateIDStr)
+			if err != nil {
+				return fantasy.NewTextErrorResponse(
+					xerrors.Errorf("invalid template_id: %w", err).Error(),
+				), nil
+			}
+
+			// Serialize workspace creation to prevent parallel
+			// tool calls from creating duplicate workspaces.
+			if options.WorkspaceMu != nil {
+				options.WorkspaceMu.Lock()
+				defer options.WorkspaceMu.Unlock()
+			}
+
+			// Check for an existing workspace on the chat.
+			if options.DB != nil && options.ChatID != uuid.Nil {
+				existing, done, existErr := checkExistingWorkspace(
+					ctx, options.DB, options.ChatID,
+					options.AgentConnFn,
+				)
+				if existErr != nil {
+					return fantasy.NewTextErrorResponse(existErr.Error()), nil
+				}
+				if done {
+					return toolResponse(existing), nil
+				}
+			}
+
+			ownerID := options.OwnerID
+
+			// Set up dbauthz context for DB lookups.
+			if options.DB != nil {
+				ownerCtx, ownerErr := asOwner(ctx, options.DB, ownerID)
+				if ownerErr != nil {
+					return fantasy.NewTextErrorResponse(ownerErr.Error()), nil
+				}
+				ctx = ownerCtx
+			}
+
+			createReq := codersdk.CreateWorkspaceRequest{
+				TemplateID: templateID,
+			}
+
+			// Resolve workspace name.
+			name := strings.TrimSpace(args.Name)
+			if name == "" {
+				seed := "workspace"
+				if options.DB != nil {
+					if t, lookupErr := options.DB.GetTemplateByID(ctx, templateID); lookupErr == nil {
+						seed = t.Name
+					}
+				}
+				name = generatedWorkspaceName(seed)
+			} else if err := codersdk.NameValid(name); err != nil {
+				name = generatedWorkspaceName(name)
+			}
+			createReq.Name = name
+
+			// Map parameters.
+			for k, v := range args.Parameters {
+				createReq.RichParameterValues = append(
+					createReq.RichParameterValues,
+					codersdk.WorkspaceBuildParameter{Name: k, Value: v},
+				)
+			}
+
+			workspace, err := options.CreateFn(ctx, ownerID, createReq)
+			if err != nil {
+				return fantasy.NewTextErrorResponse(err.Error()), nil
+			}
+
+			// Wait for the build to complete and the agent to
+			// come online so subsequent tools can use the
+			// workspace immediately.
+			if options.DB != nil {
+				if err := waitForBuild(ctx, options.DB, workspace.ID); err != nil {
+					return fantasy.NewTextErrorResponse(
+						xerrors.Errorf("workspace build failed: %w", err).Error(),
+					), nil
+				}
+			}
+
+			// Look up the first agent so we can link it to the chat.
+			workspaceAgentID := uuid.Nil
+			if options.DB != nil {
+				agents, agentErr := options.DB.GetWorkspaceAgentsInLatestBuildByWorkspaceID(ctx, workspace.ID)
+				if agentErr == nil && len(agents) > 0 {
+					workspaceAgentID = agents[0].ID
+				}
+			}
+
+			// Persist workspace + agent association on the chat.
+			if options.DB != nil && options.ChatID != uuid.Nil {
+				_, _ = options.DB.UpdateChatWorkspace(ctx, database.UpdateChatWorkspaceParams{
+					ID: options.ChatID,
+					WorkspaceID: uuid.NullUUID{
+						UUID:  workspace.ID,
+						Valid: true,
+					},
+					WorkspaceAgentID: uuid.NullUUID{
+						UUID:  workspaceAgentID,
+						Valid: workspaceAgentID != uuid.Nil,
+					},
+				})
+			}
+
+			// Wait for the agent to come online.
+			if workspaceAgentID != uuid.Nil && options.AgentConnFn != nil {
+				if err := waitForAgent(ctx, options.AgentConnFn, workspaceAgentID); err != nil {
+					// Non-fatal: the workspace was created
+					// successfully, the agent just isn't ready
+					// yet. The model can retry.
+					return toolResponse(map[string]any{
+						"created":        true,
+						"workspace_name": workspace.FullName(),
+						"agent_status":   "not_ready",
+						"agent_error":    err.Error(),
+					}), nil
+				}
+			}
+
+			return toolResponse(map[string]any{
+				"created":        true,
+				"workspace_name": workspace.FullName(),
+			}), nil
+		},
+	)
+}
+
+// checkExistingWorkspace checks whether the chat already has a usable
+// workspace. Returns the result map and true if the caller should
+// return early (workspace exists and is alive or building). Returns
+// false if the caller should proceed with creation (workspace is dead
+// or missing).
+func checkExistingWorkspace(
+	ctx context.Context,
+	db database.Store,
+	chatID uuid.UUID,
+	agentConnFn AgentConnFunc,
+) (map[string]any, bool, error) {
+	chat, err := db.GetChatByID(ctx, chatID)
+	if err != nil {
+		return nil, false, xerrors.Errorf("load chat: %w", err)
+	}
+	if !chat.WorkspaceID.Valid {
+		return nil, false, nil
+	}
+
+	// Check if workspace still exists.
+	ws, err := db.GetWorkspaceByID(ctx, chat.WorkspaceID.UUID)
+	if err != nil {
+		if xerrors.Is(err, sql.ErrNoRows) {
+			// Workspace was deleted — allow creation.
+			return nil, false, nil
+		}
+		return nil, false, xerrors.Errorf("load workspace: %w", err)
+	}
+
+	// Check the latest build status.
+	build, err := db.GetLatestWorkspaceBuildByWorkspaceID(ctx, ws.ID)
+	if err != nil {
+		// Can't determine status — allow creation.
+		return nil, false, nil
+	}
+
+	job, err := db.GetProvisionerJobByID(ctx, build.JobID)
+	if err != nil {
+		return nil, false, nil
+	}
+
+	switch job.JobStatus {
+	case database.ProvisionerJobStatusPending,
+		database.ProvisionerJobStatusRunning:
+		// Build is in progress — wait for it instead of
+		// creating a new workspace.
+		if err := waitForBuild(ctx, db, ws.ID); err != nil {
+			return nil, false, xerrors.Errorf(
+				"existing workspace build failed: %w", err,
+			)
+		}
+		return map[string]any{
+			"created":        false,
+			"workspace_name": ws.Name,
+			"status":         "already_exists",
+			"message":        "workspace was already being built and is now ready",
+		}, true, nil
+
+	case database.ProvisionerJobStatusSucceeded:
+		// Build succeeded — check if agent is reachable.
+		if chat.WorkspaceAgentID.Valid && agentConnFn != nil {
+			pingCtx, cancel := context.WithTimeout(
+				ctx, agentPingTimeout,
+			)
+			defer cancel()
+
+			conn, release, connErr := agentConnFn(
+				pingCtx, chat.WorkspaceAgentID.UUID,
+			)
+			if connErr == nil {
+				release()
+				_ = conn
+				return map[string]any{
+					"created":        false,
+					"workspace_name": ws.Name,
+					"status":         "already_exists",
+					"message":        "workspace is already running and reachable",
+				}, true, nil
+			}
+			// Agent unreachable — workspace is dead, allow
+			// creation.
+		}
+		// No agent ID or no conn func — allow creation.
+		return nil, false, nil
+
+	default:
+		// Failed, canceled, etc — allow creation.
+		return nil, false, nil
+	}
+}
+
+// waitForBuild polls the workspace's latest build until it
+// completes or the context expires.
+func waitForBuild(
+	ctx context.Context,
+	db database.Store,
+	workspaceID uuid.UUID,
+) error {
+	buildCtx, cancel := context.WithTimeout(ctx, buildTimeout)
+	defer cancel()
+
+	ticker := time.NewTicker(buildPollInterval)
+	defer ticker.Stop()
+
+	for {
+		build, err := db.GetLatestWorkspaceBuildByWorkspaceID(
+			buildCtx, workspaceID,
+		)
+		if err != nil {
+			return xerrors.Errorf("get latest build: %w", err)
+		}
+
+		job, err := db.GetProvisionerJobByID(buildCtx, build.JobID)
+		if err != nil {
+			return xerrors.Errorf("get provisioner job: %w", err)
+		}
+
+		switch job.JobStatus {
+		case database.ProvisionerJobStatusSucceeded:
+			return nil
+		case database.ProvisionerJobStatusFailed:
+			errMsg := "build failed"
+			if job.Error.Valid {
+				errMsg = job.Error.String
+			}
+			return xerrors.New(errMsg)
+		case database.ProvisionerJobStatusCanceled:
+			return xerrors.New("build was canceled")
+		case database.ProvisionerJobStatusPending,
+			database.ProvisionerJobStatusRunning,
+			database.ProvisionerJobStatusCanceling:
+			// Still in progress — keep waiting.
+		default:
+			return xerrors.Errorf("unexpected job status: %s", job.JobStatus)
+		}
+
+		select {
+		case <-buildCtx.Done():
+			return xerrors.Errorf(
+				"timed out waiting for workspace build: %w",
+				buildCtx.Err(),
+			)
+		case <-ticker.C:
+		}
+	}
+}
+
+// waitForAgent retries connecting to the workspace agent until it
+// succeeds or the timeout expires.
+func waitForAgent(
+	ctx context.Context,
+	agentConnFn AgentConnFunc,
+	agentID uuid.UUID,
+) error {
+	agentCtx, cancel := context.WithTimeout(ctx, agentConnectTimeout)
+	defer cancel()
+
+	ticker := time.NewTicker(agentRetryInterval)
+	defer ticker.Stop()
+
+	var lastErr error
+	for {
+		attemptCtx, attemptCancel := context.WithTimeout(agentCtx, agentAttemptTimeout)
+		conn, release, err := agentConnFn(attemptCtx, agentID)
+		attemptCancel()
+		if err == nil {
+			release()
+			_ = conn
+			return nil
+		}
+		lastErr = err
+
+		select {
+		case <-agentCtx.Done():
+			return xerrors.Errorf(
+				"timed out waiting for workspace agent: %w",
+				lastErr,
+			)
+		case <-ticker.C:
+		}
+	}
+}
+
+func generatedWorkspaceName(seed string) string {
+	base := codersdk.UsernameFrom(strings.TrimSpace(strings.ToLower(seed)))
+	if strings.TrimSpace(base) == "" {
+		base = "workspace"
+	}
+
+	suffix := strings.ReplaceAll(uuid.NewString(), "-", "")[:4]
+	if len(base) > 27 {
+		base = strings.Trim(base[:27], "-")
+	}
+	if base == "" {
+		base = "workspace"
+	}
+
+	name := fmt.Sprintf("%s-%s", base, suffix)
+	if err := codersdk.NameValid(name); err == nil {
+		return name
+	}
+	return namesgenerator.NameDigitWith("-")
+}

coderd/chatd/chattool/editfiles.go

@@ -0,0 +1,50 @@
+package chattool
+
+import (
+	"context"
+
+	"charm.land/fantasy"
+
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
+)
+
+type EditFilesOptions struct {
+	GetWorkspaceConn func(context.Context) (workspacesdk.AgentConn, error)
+}
+
+type EditFilesArgs struct {
+	Files []workspacesdk.FileEdits `json:"files"`
+}
+
+func EditFiles(options EditFilesOptions) fantasy.AgentTool {
+	return fantasy.NewAgentTool(
+		"edit_files",
+		"Perform search-and-replace edits on one or more files in the workspace."+
+			" Each file can have multiple edits applied atomically.",
+		func(ctx context.Context, args EditFilesArgs, _ fantasy.ToolCall) (fantasy.ToolResponse, error) {
+			if options.GetWorkspaceConn == nil {
+				return fantasy.NewTextErrorResponse("workspace connection resolver is not configured"), nil
+			}
+			conn, err := options.GetWorkspaceConn(ctx)
+			if err != nil {
+				return fantasy.NewTextErrorResponse(err.Error()), nil
+			}
+			return executeEditFilesTool(ctx, conn, args)
+		},
+	)
+}
+
+func executeEditFilesTool(
+	ctx context.Context,
+	conn workspacesdk.AgentConn,
+	args EditFilesArgs,
+) (fantasy.ToolResponse, error) {
+	if len(args.Files) == 0 {
+		return fantasy.NewTextErrorResponse("files is required"), nil
+	}
+
+	if err := conn.EditFiles(ctx, workspacesdk.FileEditRequest{Files: args.Files}); err != nil {
+		return fantasy.NewTextErrorResponse(err.Error()), nil
+	}
+	return toolResponse(map[string]any{"ok": true}), nil
+}

coderd/chatd/chattool/execute.go

@@ -0,0 +1,133 @@
+package chattool
+
+import (
+	"context"
+	"time"
+
+	"charm.land/fantasy"
+	"golang.org/x/crypto/ssh"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
+)
+
+const (
+	defaultExecuteTimeout    = 60 * time.Second
+	chatAgentEnvVar          = "CODER_CHAT_AGENT"
+	gitAuthRequiredPrefix    = "CODER_GITAUTH_REQUIRED:"
+	authRequiredResultReason = "authentication_required"
+)
+
+type ExecuteOptions struct {
+	GetWorkspaceConn func(context.Context) (workspacesdk.AgentConn, error)
+	DefaultTimeout   time.Duration
+}
+
+type ExecuteArgs struct {
+	Command        string `json:"command"`
+	TimeoutSeconds *int   `json:"timeout_seconds,omitempty"`
+}
+
+func Execute(options ExecuteOptions) fantasy.AgentTool {
+	return fantasy.NewAgentTool(
+		"execute",
+		"Execute a shell command in the workspace.",
+		func(ctx context.Context, args ExecuteArgs, _ fantasy.ToolCall) (fantasy.ToolResponse, error) {
+			if options.GetWorkspaceConn == nil {
+				return fantasy.NewTextErrorResponse("workspace connection resolver is not configured"), nil
+			}
+			conn, err := options.GetWorkspaceConn(ctx)
+			if err != nil {
+				return fantasy.NewTextErrorResponse(err.Error()), nil
+			}
+			return executeTool(ctx, conn, args, options.DefaultTimeout), nil
+		},
+	)
+}
+
+func executeTool(
+	ctx context.Context,
+	conn workspacesdk.AgentConn,
+	args ExecuteArgs,
+	defaultTimeout time.Duration,
+) fantasy.ToolResponse {
+	if args.Command == "" {
+		return fantasy.NewTextErrorResponse("command is required")
+	}
+
+	timeout := defaultTimeout
+	if timeout <= 0 {
+		timeout = defaultExecuteTimeout
+	}
+	if args.TimeoutSeconds != nil {
+		timeout = time.Duration(*args.TimeoutSeconds) * time.Second
+	}
+	cmdCtx, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+
+	output, exitCode, err := runCommand(cmdCtx, conn, args.Command)
+	if err != nil {
+		return fantasy.NewTextErrorResponse(err.Error())
+	}
+	return toolResponse(map[string]any{
+		"output":    output,
+		"exit_code": exitCode,
+	})
+}
+
+func runCommand(
+	ctx context.Context,
+	conn workspacesdk.AgentConn,
+	command string,
+) (string, int, error) {
+	sshClient, err := conn.SSHClient(ctx)
+	if err != nil {
+		return "", 0, err
+	}
+	defer sshClient.Close()
+
+	session, err := sshClient.NewSession()
+	if err != nil {
+		return "", 0, err
+	}
+	defer session.Close()
+	if err := session.Setenv(chatAgentEnvVar, "true"); err != nil {
+		return "", 0, xerrors.Errorf("set %s: %w", chatAgentEnvVar, err)
+	}
+
+	resultCh := make(chan struct {
+		output   string
+		exitCode int
+		err      error
+	}, 1)
+
+	go func() {
+		output, err := session.CombinedOutput(command)
+		exitCode := 0
+		if err != nil {
+			var exitErr *ssh.ExitError
+			if xerrors.As(err, &exitErr) {
+				exitCode = exitErr.ExitStatus()
+			} else {
+				exitCode = 1
+			}
+		}
+		resultCh <- struct {
+			output   string
+			exitCode int
+			err      error
+		}{
+			output:   string(output),
+			exitCode: exitCode,
+			err:      err,
+		}
+	}()
+
+	select {
+	case <-ctx.Done():
+		_ = session.Close()
+		return "", 0, ctx.Err()
+	case result := <-resultCh:
+		return result.output, result.exitCode, result.err
+	}
+}

coderd/chatd/chattool/listtemplates.go

@@ -0,0 +1,94 @@
+package chattool
+
+import (
+	"context"
+	"database/sql"
+	"strings"
+
+	"charm.land/fantasy"
+	"github.com/google/uuid"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/coderd/database"
+	"github.com/coder/coder/v2/coderd/database/dbauthz"
+	"github.com/coder/coder/v2/coderd/httpmw"
+	"github.com/coder/coder/v2/coderd/rbac"
+)
+
+// ListTemplatesOptions configures the list_templates tool.
+type ListTemplatesOptions struct {
+	DB      database.Store
+	OwnerID uuid.UUID
+}
+
+type listTemplatesArgs struct {
+	Query string `json:"query,omitempty"`
+}
+
+// ListTemplates returns a tool that lists available workspace templates.
+// The agent uses this to discover templates before creating a workspace.
+func ListTemplates(options ListTemplatesOptions) fantasy.AgentTool {
+	return fantasy.NewAgentTool(
+		"list_templates",
+		"List available workspace templates. Optionally filter by a "+
+			"search query matching template name or description. "+
+			"Use this to find a template before creating a workspace.",
+		func(ctx context.Context, args listTemplatesArgs, _ fantasy.ToolCall) (fantasy.ToolResponse, error) {
+			if options.DB == nil {
+				return fantasy.NewTextErrorResponse("database is not configured"), nil
+			}
+
+			ctx, err := asOwner(ctx, options.DB, options.OwnerID)
+			if err != nil {
+				return fantasy.NewTextErrorResponse(err.Error()), nil
+			}
+
+			filterParams := database.GetTemplatesWithFilterParams{
+				Deleted: false,
+				Deprecated: sql.NullBool{
+					Bool:  false,
+					Valid: true,
+				},
+			}
+			query := strings.TrimSpace(args.Query)
+			if query != "" {
+				filterParams.FuzzyName = query
+			}
+
+			templates, err := options.DB.GetTemplatesWithFilter(ctx, filterParams)
+			if err != nil {
+				return fantasy.NewTextErrorResponse(err.Error()), nil
+			}
+
+			items := make([]map[string]any, 0, len(templates))
+			for _, t := range templates {
+				item := map[string]any{
+					"id":   t.ID.String(),
+					"name": t.Name,
+				}
+				if display := strings.TrimSpace(t.DisplayName); display != "" {
+					item["display_name"] = display
+				}
+				if desc := strings.TrimSpace(t.Description); desc != "" {
+					item["description"] = truncateRunes(desc, 200)
+				}
+				items = append(items, item)
+			}
+
+			return toolResponse(map[string]any{
+				"templates": items,
+				"count":     len(items),
+			}), nil
+		},
+	)
+}
+
+// asOwner sets up a dbauthz context for the given owner so that
+// subsequent database calls are scoped to what that user can access.
+func asOwner(ctx context.Context, db database.Store, ownerID uuid.UUID) (context.Context, error) {
+	actor, _, err := httpmw.UserRBACSubject(ctx, db, ownerID, rbac.ScopeAll)
+	if err != nil {
+		return ctx, xerrors.Errorf("load user authorization: %w", err)
+	}
+	return dbauthz.As(ctx, actor), nil
+}

coderd/chatd/chattool/readfile.go

@@ -0,0 +1,72 @@
+package chattool
+
+import (
+	"context"
+	"io"
+
+	"charm.land/fantasy"
+
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
+)
+
+type ReadFileOptions struct {
+	GetWorkspaceConn func(context.Context) (workspacesdk.AgentConn, error)
+}
+
+type ReadFileArgs struct {
+	Path   string `json:"path"`
+	Offset *int64 `json:"offset,omitempty"`
+	Limit  *int64 `json:"limit,omitempty"`
+}
+
+func ReadFile(options ReadFileOptions) fantasy.AgentTool {
+	return fantasy.NewAgentTool(
+		"read_file",
+		"Read a file from the workspace.",
+		func(ctx context.Context, args ReadFileArgs, _ fantasy.ToolCall) (fantasy.ToolResponse, error) {
+			if options.GetWorkspaceConn == nil {
+				return fantasy.NewTextErrorResponse("workspace connection resolver is not configured"), nil
+			}
+			conn, err := options.GetWorkspaceConn(ctx)
+			if err != nil {
+				return fantasy.NewTextErrorResponse(err.Error()), nil
+			}
+			return executeReadFileTool(ctx, conn, args)
+		},
+	)
+}
+
+func executeReadFileTool(
+	ctx context.Context,
+	conn workspacesdk.AgentConn,
+	args ReadFileArgs,
+) (fantasy.ToolResponse, error) {
+	if args.Path == "" {
+		return fantasy.NewTextErrorResponse("path is required"), nil
+	}
+
+	offset := int64(0)
+	limit := int64(0)
+	if args.Offset != nil {
+		offset = *args.Offset
+	}
+	if args.Limit != nil {
+		limit = *args.Limit
+	}
+
+	reader, mimeType, err := conn.ReadFile(ctx, args.Path, offset, limit)
+	if err != nil {
+		return fantasy.NewTextErrorResponse(err.Error()), nil
+	}
+	defer reader.Close()
+
+	data, err := io.ReadAll(reader)
+	if err != nil {
+		return fantasy.NewTextErrorResponse(err.Error()), nil
+	}
+
+	return toolResponse(map[string]any{
+		"content":   string(data),
+		"mime_type": mimeType,
+	}), nil
+}

coderd/chatd/chattool/readtemplate.go

@@ -0,0 +1,130 @@
+package chattool
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+
+	"charm.land/fantasy"
+	"github.com/google/uuid"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/coderd/database"
+)
+
+// ReadTemplateOptions configures the read_template tool.
+type ReadTemplateOptions struct {
+	DB      database.Store
+	OwnerID uuid.UUID
+}
+
+type readTemplateArgs struct {
+	TemplateID string `json:"template_id"`
+}
+
+// ReadTemplate returns a tool that retrieves details about a specific
+// template, including its configurable rich parameters. The agent
+// uses this after list_templates and before create_workspace.
+func ReadTemplate(options ReadTemplateOptions) fantasy.AgentTool {
+	return fantasy.NewAgentTool(
+		"read_template",
+		"Get details about a workspace template, including its "+
+			"configurable parameters. Use this after finding a "+
+			"template with list_templates and before creating a "+
+			"workspace with create_workspace.",
+		func(ctx context.Context, args readTemplateArgs, _ fantasy.ToolCall) (fantasy.ToolResponse, error) {
+			if options.DB == nil {
+				return fantasy.NewTextErrorResponse("database is not configured"), nil
+			}
+
+			templateIDStr := strings.TrimSpace(args.TemplateID)
+			if templateIDStr == "" {
+				return fantasy.NewTextErrorResponse("template_id is required"), nil
+			}
+			templateID, err := uuid.Parse(templateIDStr)
+			if err != nil {
+				return fantasy.NewTextErrorResponse(
+					xerrors.Errorf("invalid template_id: %w", err).Error(),
+				), nil
+			}
+
+			ctx, err = asOwner(ctx, options.DB, options.OwnerID)
+			if err != nil {
+				return fantasy.NewTextErrorResponse(err.Error()), nil
+			}
+
+			template, err := options.DB.GetTemplateByID(ctx, templateID)
+			if err != nil {
+				return fantasy.NewTextErrorResponse("template not found"), nil
+			}
+
+			params, err := options.DB.GetTemplateVersionParameters(ctx, template.ActiveVersionID)
+			if err != nil {
+				return fantasy.NewTextErrorResponse(
+					xerrors.Errorf("failed to get template parameters: %w", err).Error(),
+				), nil
+			}
+
+			templateInfo := map[string]any{
+				"id":                template.ID.String(),
+				"name":              template.Name,
+				"active_version_id": template.ActiveVersionID.String(),
+			}
+			if display := strings.TrimSpace(template.DisplayName); display != "" {
+				templateInfo["display_name"] = display
+			}
+			if desc := strings.TrimSpace(template.Description); desc != "" {
+				templateInfo["description"] = desc
+			}
+
+			paramList := make([]map[string]any, 0, len(params))
+			for _, p := range params {
+				param := map[string]any{
+					"name":     p.Name,
+					"type":     p.Type,
+					"required": p.Required,
+				}
+				if display := strings.TrimSpace(p.DisplayName); display != "" {
+					param["display_name"] = display
+				}
+				if desc := strings.TrimSpace(p.Description); desc != "" {
+					param["description"] = truncateRunes(desc, 300)
+				}
+				if p.DefaultValue != "" {
+					param["default"] = p.DefaultValue
+				}
+				if p.Mutable {
+					param["mutable"] = true
+				}
+				if p.Ephemeral {
+					param["ephemeral"] = true
+				}
+				if p.FormType != "" {
+					param["form_type"] = string(p.FormType)
+				}
+				if len(p.Options) > 0 && string(p.Options) != "null" && string(p.Options) != "[]" {
+					var opts []map[string]any
+					if err := json.Unmarshal(p.Options, &opts); err == nil && len(opts) > 0 {
+						param["options"] = opts
+					}
+				}
+				if p.ValidationRegex != "" {
+					param["validation_regex"] = p.ValidationRegex
+				}
+				if p.ValidationMin.Valid {
+					param["validation_min"] = p.ValidationMin.Int32
+				}
+				if p.ValidationMax.Valid {
+					param["validation_max"] = p.ValidationMax.Int32
+				}
+
+				paramList = append(paramList, param)
+			}
+
+			return toolResponse(map[string]any{
+				"template":   templateInfo,
+				"parameters": paramList,
+			}), nil
+		},
+	)
+}

coderd/chatd/chattool/writefile.go

@@ -0,0 +1,51 @@
+package chattool
+
+import (
+	"context"
+	"strings"
+
+	"charm.land/fantasy"
+
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
+)
+
+type WriteFileOptions struct {
+	GetWorkspaceConn func(context.Context) (workspacesdk.AgentConn, error)
+}
+
+type WriteFileArgs struct {
+	Path    string `json:"path"`
+	Content string `json:"content"`
+}
+
+func WriteFile(options WriteFileOptions) fantasy.AgentTool {
+	return fantasy.NewAgentTool(
+		"write_file",
+		"Write a file to the workspace.",
+		func(ctx context.Context, args WriteFileArgs, _ fantasy.ToolCall) (fantasy.ToolResponse, error) {
+			if options.GetWorkspaceConn == nil {
+				return fantasy.NewTextErrorResponse("workspace connection resolver is not configured"), nil
+			}
+			conn, err := options.GetWorkspaceConn(ctx)
+			if err != nil {
+				return fantasy.NewTextErrorResponse(err.Error()), nil
+			}
+			return executeWriteFileTool(ctx, conn, args)
+		},
+	)
+}
+
+func executeWriteFileTool(
+	ctx context.Context,
+	conn workspacesdk.AgentConn,
+	args WriteFileArgs,
+) (fantasy.ToolResponse, error) {
+	if args.Path == "" {
+		return fantasy.NewTextErrorResponse("path is required"), nil
+	}
+
+	if err := conn.WriteFile(ctx, args.Path, strings.NewReader(args.Content)); err != nil {
+		return fantasy.NewTextErrorResponse(err.Error()), nil
+	}
+	return toolResponse(map[string]any{"ok": true}), nil
+}