The chat `read_template` tool returned the parameter defaults recorded at template import. Defaults that depend on the workspace owner, such as a region chosen from the owner's groups, were therefore wrong for many users, and an agent that omitted the parameter in `create_workspace` built a workspace with a different value than the tool had shown. `read_template` now evaluates the active version's parameters for the chat owner with no inputs, through `dynamicparameters.Prepare` and the same `Render` call `wsbuilder` makes for a first build, via a `RenderTemplateParametersFn` hook wired from coderd like the other chat hooks. The result carries a `parameters_note` naming the source: owner-evaluated build values, import rows for templates on the classic parameter flow (which `wsbuilder` also builds from), a retry note while the version is still importing, or import rows with a warning when evaluation fails. A parameter whose evaluated default fails its own validation is reported as `error` instead of a usable `default`. Only an evaluated default is checked: without one, preview and the static renderer validate an empty value, so required parameters and unevaluated defaults are never reported as broken, and their remaining errors surface at build time. Fields preview cannot evaluate before the build are shown as evaluated rather than filled from the import row, because preview's output does not distinguish a default, option set, or validation bound that is unknown (it depends on `data.coder_provisioner`) from one that is null for this owner: an unevaluated default carries a `default_note` saying so, an option with an unknown value is omitted, with preview's invalid-options error surfaced as `error` when the parameter has an evaluated default, and bounds appear exactly as rendered. The one import-row fill is for parameters a `module_not_loaded` render dropped, keyed on the same diagnostic code `wsbuilder` uses. Import rows carry no module provenance, so that fill also restores root-level rows the render omitted for this owner; every restored row carries a `note` marking it an import-time estimate. The build-values note is scoped to a request that omits every parameter and matches no preset, since a default that depends on another parameter is re-evaluated against the values `create_workspace` passes, a preset can match without a `preset_id`, and a claimed prebuilt workspace can keep its own values. When evaluation falls back, the warning logs only diagnostic codes, because diagnostic text can quote owner attributes. Measured on dogfood, evaluation adds about 4 ms for a two-parameter template and about 70 ms for the 6-parameter, 19-module `coder` template per `read_template` call, matching the workspace create form's evaluate endpoint, with no file cache growth across repeated calls. > Xum acted for Mike on this pull request.
471 lines
17 KiB
Go
471 lines
17 KiB
Go
package chattool
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"strings"
|
|
"time"
|
|
|
|
"charm.land/fantasy"
|
|
"github.com/google/uuid"
|
|
"golang.org/x/xerrors"
|
|
|
|
"cdr.dev/slog/v3"
|
|
"github.com/coder/coder/v2/coderd/database"
|
|
"github.com/coder/coder/v2/coderd/dynamicparameters"
|
|
"github.com/coder/coder/v2/codersdk"
|
|
previewtypes "github.com/coder/preview/types"
|
|
)
|
|
|
|
// ReadTemplateReadmeMaxRunes bounds the full README returned by read_template
|
|
// so one large README cannot dominate a single tool response.
|
|
const ReadTemplateReadmeMaxRunes = 8000
|
|
|
|
const (
|
|
readTemplateBuildDefaultsNote = "Parameter defaults are the values a " +
|
|
"build for this workspace owner uses when create_workspace omits " +
|
|
"every parameter and no preset applies. A default that depends on " +
|
|
"another parameter is re-evaluated against the values passed to " +
|
|
"create_workspace, so pass it explicitly when its value matters. A " +
|
|
"preset applies when its preset_id is passed or, without one, when " +
|
|
"every parameter it defines is passed with the preset's value; the " +
|
|
"matching preset defining the most parameters wins, and a preset " +
|
|
"defining none matches every request. A preset marked default is not " +
|
|
"applied implicitly. If a prebuilt workspace is claimed for the " +
|
|
"preset, omitted parameters can keep the prebuilt workspace's values " +
|
|
"instead of these defaults, and passing an immutable parameter the " +
|
|
"preset does not define with a value other than the prebuilt " +
|
|
"workspace's fails workspace creation."
|
|
readTemplateImportDefaultsNote = "Parameter defaults could not be " +
|
|
"evaluated for the workspace owner and are the values recorded at " +
|
|
"template import, which may differ from what a build uses. Pass " +
|
|
"parameters or a preset_id explicitly when the value matters."
|
|
readTemplateImportingNote = "The active template version is still " +
|
|
"importing, so its parameters are not available yet. Retry " +
|
|
"read_template shortly."
|
|
readTemplateModuleFallbackNote = "not evaluated for this owner because a " +
|
|
"module could not be loaded before the build; shown as recorded at " +
|
|
"template import, so it may not apply to this owner and its default " +
|
|
"may differ from the build value"
|
|
readTemplateUnresolvedDefaultNote = "no default could be evaluated for " +
|
|
"this owner before the build; omit the parameter to let the build " +
|
|
"resolve it, or pass a value explicitly"
|
|
)
|
|
|
|
// RenderTemplateParametersFn evaluates a template version's parameters as the
|
|
// workspace owner would see them on the creation form, so defaults derived
|
|
// from owner attributes such as groups resolve to the values a build uses.
|
|
// It returns dynamicparameters.ErrTemplateVersionNotReady while the version
|
|
// is still importing.
|
|
type RenderTemplateParametersFn func(
|
|
ctx context.Context,
|
|
ownerID uuid.UUID,
|
|
templateVersionID uuid.UUID,
|
|
) ([]codersdk.PreviewParameter, []codersdk.FriendlyDiagnostic, error)
|
|
|
|
// ReadTemplateOptions configures the read_template tool.
|
|
type ReadTemplateOptions struct {
|
|
OwnerID uuid.UUID
|
|
// RenderParameters resolves parameter defaults for the owner. When nil,
|
|
// or when evaluation fails, the tool falls back to the defaults recorded
|
|
// at template import and says so in the response.
|
|
RenderParameters RenderTemplateParametersFn
|
|
Logger slog.Logger
|
|
}
|
|
|
|
type readTemplateArgs struct {
|
|
TemplateID string `json:"template_id" description:"The UUIDv4 of the template to read details for. Obtain this from list_templates."`
|
|
}
|
|
|
|
// ReadTemplate returns a tool that retrieves details about a specific
|
|
// template, including its configurable rich parameters. The agent uses
|
|
// this after list_templates when it needs parameters or presets before
|
|
// create_workspace.
|
|
// db must not be nil.
|
|
func ReadTemplate(db database.Store, organizationID uuid.UUID, options ReadTemplateOptions) fantasy.AgentTool {
|
|
return fantasy.NewAgentTool(
|
|
"read_template",
|
|
"Get details about a workspace template, including its "+
|
|
"configurable parameters, available presets, and the active "+
|
|
"version README. Parameter defaults are the values "+
|
|
"create_workspace uses when every parameter is omitted, unless "+
|
|
"parameters_note in the result says otherwise. Use this after "+
|
|
"list_templates when you need parameter details, preset IDs, or "+
|
|
"the README before create_workspace.",
|
|
func(ctx context.Context, args readTemplateArgs, _ fantasy.ToolCall) (fantasy.ToolResponse, error) {
|
|
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, db, options.OwnerID)
|
|
if err != nil {
|
|
return fantasy.NewTextErrorResponse(err.Error()), nil
|
|
}
|
|
|
|
template, err := db.GetTemplateByID(ctx, templateID)
|
|
if err != nil {
|
|
return fantasy.NewTextErrorResponse("template not found"), nil
|
|
}
|
|
|
|
if template.OrganizationID != organizationID {
|
|
return fantasy.NewTextErrorResponse("template not found"), nil
|
|
}
|
|
if !template.AgentsAllowed {
|
|
return fantasy.NewTextErrorResponse(templateNotAvailableMessage), nil
|
|
}
|
|
|
|
paramList, paramNote := readTemplateParameters(ctx, db, template, options)
|
|
if paramList == nil {
|
|
return fantasy.NewTextErrorResponse(paramNote), nil
|
|
}
|
|
|
|
presets, err := db.GetPresetsByTemplateVersionID(ctx, template.ActiveVersionID)
|
|
if err != nil {
|
|
return fantasy.NewTextErrorResponse(
|
|
xerrors.Errorf("failed to get template presets: %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
|
|
}
|
|
// Best-effort: a missing or unreadable version must not fail
|
|
// read_template.
|
|
if version, err := db.GetTemplateVersionByID(ctx, template.ActiveVersionID); err == nil {
|
|
if r := readmeText(version.Readme, ReadTemplateReadmeMaxRunes); r != "" {
|
|
templateInfo["readme"] = r
|
|
}
|
|
}
|
|
|
|
result := map[string]any{
|
|
"template": templateInfo,
|
|
"parameters": paramList,
|
|
"parameters_note": paramNote,
|
|
}
|
|
|
|
// Include presets only when the template has them
|
|
// to avoid cluttering responses.
|
|
if len(presets) > 0 {
|
|
presetParams, err := db.GetPresetParametersByTemplateVersionID(ctx, template.ActiveVersionID)
|
|
if err != nil {
|
|
return fantasy.NewTextErrorResponse(
|
|
xerrors.Errorf("failed to get preset parameters: %w", err).Error(),
|
|
), nil
|
|
}
|
|
|
|
// Index preset parameters by preset ID for
|
|
// efficient lookup.
|
|
paramsByPreset := make(map[uuid.UUID][]map[string]any)
|
|
for _, pp := range presetParams {
|
|
paramsByPreset[pp.TemplateVersionPresetID] = append(
|
|
paramsByPreset[pp.TemplateVersionPresetID],
|
|
map[string]any{
|
|
"name": pp.Name,
|
|
"value": pp.Value,
|
|
},
|
|
)
|
|
}
|
|
|
|
presetList := make([]map[string]any, 0, len(presets))
|
|
for _, p := range presets {
|
|
preset := map[string]any{
|
|
"id": p.ID.String(),
|
|
"name": p.Name,
|
|
"default": p.IsDefault,
|
|
}
|
|
if desc := strings.TrimSpace(p.Description); desc != "" {
|
|
preset["description"] = desc
|
|
}
|
|
if icon := strings.TrimSpace(p.Icon); icon != "" {
|
|
preset["icon"] = icon
|
|
}
|
|
// Surface the prebuild count when set so the LLM can prefer
|
|
// presets backed by prebuilt workspaces. Match the toolsdk
|
|
// `desired_prebuild_instances` key for cross-surface consistency.
|
|
if p.DesiredInstances.Valid && p.DesiredInstances.Int32 > 0 {
|
|
preset["desired_prebuild_instances"] = p.DesiredInstances.Int32
|
|
}
|
|
if params, ok := paramsByPreset[p.ID]; ok {
|
|
preset["parameters"] = params
|
|
} else {
|
|
preset["parameters"] = []map[string]any{}
|
|
}
|
|
presetList = append(presetList, preset)
|
|
}
|
|
result["presets"] = presetList
|
|
}
|
|
|
|
return toolResponse(result), nil
|
|
},
|
|
)
|
|
}
|
|
|
|
// readTemplateParameters returns the parameter list for the active template
|
|
// version and a note describing how defaults were derived. It prefers
|
|
// owner-evaluated parameters and falls back to the import-time rows when no
|
|
// renderer is configured or evaluation cannot run. A nil list means the
|
|
// import-time rows could not be read and the note carries the error.
|
|
func readTemplateParameters(
|
|
ctx context.Context,
|
|
db database.Store,
|
|
template database.Template,
|
|
options ReadTemplateOptions,
|
|
) ([]map[string]any, string) {
|
|
rows, err := db.GetTemplateVersionParameters(ctx, template.ActiveVersionID)
|
|
if err != nil {
|
|
return nil, xerrors.Errorf("failed to get template parameters: %w", err).Error()
|
|
}
|
|
importEntries := func() []map[string]any {
|
|
paramList := make([]map[string]any, 0, len(rows))
|
|
for _, p := range rows {
|
|
paramList = append(paramList, staticParameterEntry(p))
|
|
}
|
|
return paramList
|
|
}
|
|
|
|
// Builds for classic-flow templates resolve parameters from the import
|
|
// rows (wsbuilder.getClassicParameters), so those are the build values.
|
|
if template.UseClassicParameterFlow {
|
|
return importEntries(), readTemplateBuildDefaultsNote
|
|
}
|
|
if options.RenderParameters == nil {
|
|
return importEntries(), readTemplateImportDefaultsNote
|
|
}
|
|
|
|
start := time.Now()
|
|
rendered, diags, err := options.RenderParameters(ctx, options.OwnerID, template.ActiveVersionID)
|
|
fields := []slog.Field{
|
|
slog.F("template_id", template.ID),
|
|
slog.F("template_version_id", template.ActiveVersionID),
|
|
slog.F("owner_id", options.OwnerID),
|
|
slog.F("duration", time.Since(start)),
|
|
}
|
|
switch {
|
|
case err == nil && !hasErrorDiagnostic(diags):
|
|
options.Logger.Debug(ctx, "read_template evaluated parameters for owner", fields...)
|
|
renderedNames := make(map[string]struct{}, len(rendered))
|
|
paramList := make([]map[string]any, 0, len(rows))
|
|
for _, p := range rendered {
|
|
renderedNames[p.Name] = struct{}{}
|
|
paramList = append(paramList, renderedParameterEntry(p))
|
|
}
|
|
// A module preview could not load takes every parameter it declares
|
|
// out of the render, but provisionerd still resolves the module at
|
|
// build time, so the import rows stand in for those parameters. This
|
|
// is the only import-row fill: the diagnostic code is a reliable
|
|
// signal, whereas preview's output cannot distinguish a default,
|
|
// option set, or validation bound that is unknown before the build
|
|
// from one that evaluates to null for this owner, so those are shown
|
|
// exactly as evaluated, as the create-workspace form does.
|
|
//
|
|
// Import rows record no module provenance, so a root-level parameter
|
|
// the render omitted for this owner (count = 0) is restored too. The
|
|
// import evaluates parameters as a member of the Everyone group only,
|
|
// so such rows exist. Every restored row is therefore labeled as an
|
|
// import-time estimate rather than an owner-evaluated parameter.
|
|
if incompleteRender(diags) {
|
|
for _, row := range rows {
|
|
if _, ok := renderedNames[row.Name]; ok {
|
|
continue
|
|
}
|
|
entry := staticParameterEntry(row)
|
|
entry["note"] = readTemplateModuleFallbackNote
|
|
paramList = append(paramList, entry)
|
|
}
|
|
}
|
|
return paramList, readTemplateBuildDefaultsNote
|
|
case errors.Is(err, dynamicparameters.ErrTemplateVersionNotReady):
|
|
options.Logger.Debug(ctx, "read_template skipped owner evaluation, template version still importing", fields...)
|
|
return importEntries(), readTemplateImportingNote
|
|
default:
|
|
// A canceled render is not an evaluation failure worth a warning.
|
|
if ctx.Err() != nil {
|
|
return importEntries(), readTemplateImportDefaultsNote
|
|
}
|
|
if err != nil {
|
|
fields = append(fields, slog.Error(err))
|
|
}
|
|
// Diagnostic text can quote owner attributes seeded into the render,
|
|
// so only the codes are logged.
|
|
var codes []string
|
|
for _, d := range diags {
|
|
if d.Severity == codersdk.DiagnosticSeverityError {
|
|
codes = append(codes, d.Extra.Code)
|
|
}
|
|
}
|
|
fields = append(fields, slog.F("diagnostic_codes", codes))
|
|
options.Logger.Warn(ctx, "read_template failed to evaluate parameters for owner, using import defaults", fields...)
|
|
return importEntries(), readTemplateImportDefaultsNote
|
|
}
|
|
}
|
|
|
|
func hasErrorDiagnostic(diags []codersdk.FriendlyDiagnostic) bool {
|
|
for _, d := range diags {
|
|
if d.Severity == codersdk.DiagnosticSeverityError {
|
|
return true
|
|
}
|
|
}
|
|
return false
|
|
}
|
|
|
|
// incompleteRender mirrors dynamicparameters.incompleteRender: a module the
|
|
// renderer could not load omits its parameters without an error.
|
|
func incompleteRender(diags []codersdk.FriendlyDiagnostic) bool {
|
|
for _, d := range diags {
|
|
if d.Extra.Code == previewtypes.DiagnosticModuleNotLoaded {
|
|
return true
|
|
}
|
|
}
|
|
return false
|
|
}
|
|
|
|
// renderedParameterEntry converts an owner-evaluated parameter into the same
|
|
// shape as staticParameterEntry so the model sees one schema either way.
|
|
func renderedParameterEntry(p codersdk.PreviewParameter) map[string]any {
|
|
param := map[string]any{
|
|
"name": p.Name,
|
|
"type": string(p.Type),
|
|
"required": p.Required,
|
|
"mutable": p.Mutable,
|
|
}
|
|
if display := strings.TrimSpace(p.DisplayName); display != "" {
|
|
param["display_name"] = display
|
|
}
|
|
if desc := strings.TrimSpace(p.Description); desc != "" {
|
|
param["description"] = truncateRunes(desc, 300)
|
|
}
|
|
// error flags an evaluated default the build would reject. Without one,
|
|
// both renderers validate an empty value instead, and the static renderer
|
|
// presents a required parameter's missing default as a valid empty string.
|
|
var paramErr string
|
|
if p.DefaultValue.Valid && !p.Required {
|
|
for _, d := range p.Diagnostics {
|
|
if d.Severity == codersdk.DiagnosticSeverityError {
|
|
paramErr = strings.TrimSpace(d.Summary + ": " + d.Detail)
|
|
break
|
|
}
|
|
}
|
|
}
|
|
switch {
|
|
case paramErr != "":
|
|
// A parameter-scoped error does not fail the whole render, but a
|
|
// build with this value is rejected, so never present it as a
|
|
// usable default.
|
|
param["error"] = fmt.Sprintf("%s; the evaluated default %q cannot be used, pass a value explicitly", paramErr, p.DefaultValue.Value)
|
|
case p.DefaultValue.Valid:
|
|
if p.DefaultValue.Value != "" {
|
|
param["default"] = p.DefaultValue.Value
|
|
}
|
|
case !p.Required:
|
|
// An invalid default is one preview could not evaluate before the
|
|
// build (data.coder_provisioner) or one that is null for this
|
|
// owner; the two are indistinguishable, so no value is guessed.
|
|
param["default_note"] = readTemplateUnresolvedDefaultNote
|
|
}
|
|
if p.Ephemeral {
|
|
param["ephemeral"] = true
|
|
}
|
|
if p.FormType != "" {
|
|
param["form_type"] = string(p.FormType)
|
|
}
|
|
if opts := renderedOptions(p.Options); len(opts) > 0 {
|
|
param["options"] = opts
|
|
}
|
|
for _, v := range p.Validations {
|
|
if v.Regex != nil && *v.Regex != "" {
|
|
param["validation_regex"] = *v.Regex
|
|
}
|
|
if v.Min != nil {
|
|
param["validation_min"] = *v.Min
|
|
}
|
|
if v.Max != nil {
|
|
param["validation_max"] = *v.Max
|
|
}
|
|
}
|
|
return param
|
|
}
|
|
|
|
// renderedOptions converts the rendered options, omitting any whose value is
|
|
// unknown before the build rather than presenting an empty value. Preview
|
|
// flags the parameter with an invalid-options error in that case, which the
|
|
// entry surfaces as error when the parameter has an evaluated default.
|
|
func renderedOptions(options []codersdk.PreviewParameterOption) []map[string]any {
|
|
opts := make([]map[string]any, 0, len(options))
|
|
for _, o := range options {
|
|
if !o.Value.Valid {
|
|
continue
|
|
}
|
|
opt := map[string]any{
|
|
"name": o.Name,
|
|
"value": o.Value.Value,
|
|
}
|
|
if desc := strings.TrimSpace(o.Description); desc != "" {
|
|
opt["description"] = desc
|
|
}
|
|
if icon := strings.TrimSpace(o.Icon); icon != "" {
|
|
opt["icon"] = icon
|
|
}
|
|
opts = append(opts, opt)
|
|
}
|
|
return opts
|
|
}
|
|
|
|
// staticParameterEntry converts an import-time parameter row into the tool's
|
|
// parameter shape.
|
|
func staticParameterEntry(p database.TemplateVersionParameter) map[string]any {
|
|
param := map[string]any{
|
|
"name": p.Name,
|
|
"type": p.Type,
|
|
"required": p.Required,
|
|
"mutable": p.Mutable,
|
|
}
|
|
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.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
|
|
}
|
|
return param
|
|
}
|