WeKnora deployment source with the reviewed wiki identity, summary and recovery fixes

cli/cmd/agent/create.go

@@ -0,0 +1,384 @@
+package agentcmd
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"path/filepath"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/Tencent/WeKnora/cli/internal/cmdutil"
+	"github.com/Tencent/WeKnora/cli/internal/iostreams"
+	sdk "github.com/Tencent/WeKnora/client"
+)
+
+// CreateService is the narrow SDK surface this command depends on.
+// *sdk.Client satisfies it via duck typing.
+type CreateService interface {
+	CreateAgent(ctx context.Context, req *sdk.CreateAgentRequest) (*sdk.Agent, error)
+	CopyAgent(ctx context.Context, id string) (*sdk.Agent, error)
+	UpdateAgent(ctx context.Context, id string, req *sdk.UpdateAgentRequest) (*sdk.Agent, error)
+}
+
+// CreateOptions captures flag state. SystemPromptReader and ConfigFileBody
+// are populated from --system-prompt-file and --config-file respectively
+// (or stdin when the value is "-"). The embedded flags struct tracks "was
+// set" bits so MergeAgentConfig can distinguish "user passed --foo zero"
+// from "user did not pass --foo".
+type CreateOptions struct {
+	Name               string
+	Model              string
+	Description        string
+	SystemPrompt       string
+	SystemPromptReader io.Reader
+	AgentMode          string
+	KBs                []string
+	KBSelectionMode    string
+	RerankModel        string
+	Temperature        float64
+	From               string
+	ConfigFileBody     io.Reader
+	ConfigFileKind     string // "yaml" or "json"
+	GenerateSkeleton   bool
+	DryRun             bool
+
+	flags createFlagSet // populated in PreRunE for *Set bits
+}
+
+// createFlagSet records which hot-path flags the user explicitly passed so
+// MergeAgentConfig knows which fields to overlay onto the base config.
+type createFlagSet struct {
+	agentModeSet       bool
+	systemPromptSet    bool
+	rerankModelSet     bool
+	temperatureSet     bool
+	kbSelectionModeSet bool
+	kbsSet             bool
+}
+
+const agentCreateExample = `  weknora agent create "Support Bot" --model <model-id>
+  weknora agent create "Code Reviewer" --model <model-id> --system-prompt-file ./prompt.md --attach-kb kb_eng --attach-kb kb_arch
+  weknora agent create "From Template" --model <model-id> --from ag_existing
+  weknora agent create --generate-skeleton > my-agent.yaml
+  weknora agent create "Tuned" --model <model-id> --config-file ./my-agent.yaml`
+
+const agentCreateLong = `Create a new custom agent.
+
+--model is required (an agent without a model cannot invoke); discover a
+valid model id with 'weknora model list'. The 7
+optional hot-path flags cover the most frequently set AgentConfig fields;
+for the remaining 27 use --config-file with a YAML or JSON document
+matching the AgentConfig schema (run --generate-skeleton to get a
+ready-to-edit template).
+
+Precedence when both a config file and hot-path flags are supplied:
+  hot-path flag > config-file value > server default
+
+--from <id> copies an existing agent (SDK CopyAgent) then applies any
+hot-path overrides via UpdateAgent. --attach-kb on --from REPLACES the copied
+agent's KB list (not merge) — matches surgical-flag semantics.
+
+AI agents: writes a new resource server-side. Failure surfaces as a
+typed code on stderr: input.invalid_argument (bad flags, bad file, or
+bad model), resource.not_found (--from <missing>), auth.unauthenticated.`
+
+// NewCmdCreate builds `weknora agent create <name> --model <id>`.
+func NewCmdCreate(f *cmdutil.Factory) *cobra.Command {
+	opts := &CreateOptions{}
+	var systemPromptFile, configFile string
+
+	cmd := &cobra.Command{
+		Use:     "create <name>",
+		Short:   "Create a new custom agent",
+		Long:    agentCreateLong,
+		Example: agentCreateExample,
+		// Allow 0 args for --generate-skeleton; PreRunE enforces the real
+		// arity rule once it knows whether skeleton mode is active.
+		Args: cobra.MaximumNArgs(1),
+		PreRunE: func(cmd *cobra.Command, args []string) error {
+			if opts.GenerateSkeleton {
+				return nil
+			}
+			if len(args) != 1 {
+				return cmdutil.NewFlagError(fmt.Errorf("accepts 1 arg, received %d", len(args)))
+			}
+			opts.Name = args[0]
+			if opts.Model == "" {
+				return cmdutil.NewFlagError(fmt.Errorf(`required flag(s) "model" not set`))
+			}
+			opts.flags.agentModeSet = cmd.Flags().Changed("agent-mode")
+			opts.flags.systemPromptSet = cmd.Flags().Changed("system-prompt") || cmd.Flags().Changed("system-prompt-file")
+			opts.flags.rerankModelSet = cmd.Flags().Changed("rerank-model")
+			opts.flags.temperatureSet = cmd.Flags().Changed("temperature")
+			opts.flags.kbSelectionModeSet = cmd.Flags().Changed("kb-selection-mode")
+			opts.flags.kbsSet = cmd.Flags().Changed("attach-kb")
+
+			// --temperature is bounded 0.0..2.0. Reject out-of-range
+			// early with a typed input.invalid_argument so users don't
+			// burn a roundtrip on a value the server would also reject.
+			if opts.flags.temperatureSet && (opts.Temperature < 0.0 || opts.Temperature > 2.0) {
+				return cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
+					fmt.Sprintf("--temperature must be in 0.0..2.0, got %g", opts.Temperature))
+			}
+
+			// Reject an unknown --agent-mode / --kb-selection-mode up front
+			// (typed exit 5) rather than letting the server fail the create.
+			if err := validateAgentModeFlags(&opts.AgentMode, &opts.KBSelectionMode); err != nil {
+				return err
+			}
+
+			if systemPromptFile != "" {
+				r, err := cmdutil.OpenInput(systemPromptFile)
+				if err != nil {
+					return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, fmt.Sprintf("--system-prompt-file: %v", err))
+				}
+				opts.SystemPromptReader = r
+			}
+			if configFile != "" {
+				r, kind, err := openConfigFile(configFile)
+				if err != nil {
+					return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, fmt.Sprintf("--config-file: %v", err))
+				}
+				opts.ConfigFileBody = r
+				opts.ConfigFileKind = kind
+			}
+			return nil
+		},
+		RunE: func(cmd *cobra.Command, args []string) error {
+			fopts, err := cmdutil.CheckFormatFlag(cmd)
+			if err != nil {
+				return err
+			}
+			fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
+			planArgs := map[string]any{"name": opts.Name}
+			if configFile != "" {
+				planArgs["config"] = configFile
+			}
+			if handled, err := cmdutil.HandleDryRun(cmd, opts.DryRun, cmdutil.DryRunPlan{
+				Action: "agent.create",
+				Args:   planArgs,
+			}); handled {
+				return err
+			}
+			cli, err := f.Client()
+			if err != nil {
+				return err
+			}
+			// Resolve --model / --rerank-model (id or name) and validate they
+			// exist, matching the id-or-name policy of `kb config set`. A bogus name
+			// fails fast here instead of creating an agent whose model never
+			// resolves at run time.
+			if opts.Model, err = cmdutil.ResolveModelRef(cmd.Context(), cli, opts.Model, "KnowledgeQA"); err != nil {
+				return err
+			}
+			if opts.RerankModel, err = cmdutil.ResolveModelRef(cmd.Context(), cli, opts.RerankModel, "Rerank"); err != nil {
+				return err
+			}
+			// Resolve --attach-kb values (id or name) to canonical ids,
+			// matching the --kb flag's id-or-name policy. Without this a raw
+			// name is stored verbatim as a kb_id, silently creating an agent
+			// whose KB reference never resolves at run time.
+			if len(opts.KBs) > 0 {
+				resolved := make([]string, 0, len(opts.KBs))
+				for _, raw := range opts.KBs {
+					id, rerr := cmdutil.ResolveKBFlag(cmd.Context(), cli, raw)
+					if rerr != nil {
+						return rerr
+					}
+					resolved = append(resolved, id)
+				}
+				opts.KBs = resolved
+			}
+			return runCreate(cmd.Context(), opts, fopts, cli)
+		},
+	}
+
+	// Required (enforced in PreRunE rather than cmd.MarkFlagRequired so
+	// --generate-skeleton can bypass it — cobra's MarkFlagRequired runs
+	// before PreRunE and would otherwise block the skeleton path).
+	cmd.Flags().StringVar(&opts.Model, "model", "", "LLM model id or name (required, except with --generate-skeleton)")
+
+	// Hot-path (8 flag names, 7 distinct config fields)
+	cmd.Flags().StringVar(&opts.Description, "description", "", "Agent description")
+	cmd.Flags().StringVar(&opts.SystemPrompt, "system-prompt", "", "System prompt text (mutex with --system-prompt-file)")
+	cmd.Flags().StringVar(&systemPromptFile, "system-prompt-file", "", "Read system prompt from FILE, or '-' for stdin")
+	cmd.MarkFlagsMutuallyExclusive("system-prompt", "system-prompt-file")
+	cmd.Flags().StringVar(&opts.AgentMode, "agent-mode", "", "Agent operating mode: "+strings.Join(agentModeValues, " | "))
+	cmd.Flags().StringSliceVar(&opts.KBs, "attach-kb", nil, "Attach a knowledge base id (repeatable); aligns with 'agent update --add-kb'")
+	cmd.Flags().StringVar(&opts.KBSelectionMode, "kb-selection-mode", "", "KB selection mode: "+strings.Join(kbSelectionModeValues, " | "))
+	cmd.Flags().StringVar(&opts.RerankModel, "rerank-model", "", "Rerank model id or name")
+	cmd.Flags().Float64Var(&opts.Temperature, "temperature", 0.0, "Generation temperature (0.0..2.0)")
+
+	// Power-user / utility
+	cmd.Flags().StringVar(&opts.From, "from", "", "Copy from existing agent id (then apply other flags)")
+	cmd.Flags().StringVar(&configFile, "config-file", "", "Full AgentConfig YAML or JSON (use '-' for stdin)")
+	cmd.Flags().BoolVar(&opts.GenerateSkeleton, "generate-skeleton", false, "Emit blank AgentConfig YAML to stdout and exit")
+
+	cmdutil.AddFormatFlag(cmd, agentViewFields...)
+	cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
+	cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
+		UsedFor:       "Create a new custom agent. --model is required and accepts a model id or name; --attach-kb (repeatable) accepts KB ids or names. Emits the created Agent object.",
+		RequiredFlags: []string{"<name> (positional)", "--model"},
+		Examples: []string{
+			`weknora agent create "Support Bot" --model gpt-4o`,
+			`weknora agent create "Support Bot" --model gpt-4o --attach-kb kb_eng --system-prompt "You are a support assistant."`,
+			`weknora agent create --generate-skeleton   # print a blank config to fill in (no --model needed)`,
+		},
+		Output: "envelope.data is the created Agent object with id, name, config",
+	})
+	return cmd
+}
+
+func runCreate(ctx context.Context, opts *CreateOptions, fopts *cmdutil.FormatOptions, svc CreateService) error {
+	if opts.GenerateSkeleton {
+		return cmdutil.GenerateAgentSkeleton(iostreams.IO.Out)
+	}
+
+	// 1. Build base AgentConfig from --config-file (if any), else zero.
+	// (For --from, the copied agent's existing config becomes the base
+	// instead — set after CopyAgent below, before MergeAgentConfig.)
+	var base sdk.AgentConfig
+	if opts.ConfigFileBody != nil {
+		parsed, err := cmdutil.LoadAgentConfig(opts.ConfigFileBody, opts.ConfigFileKind)
+		if err != nil {
+			return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, err.Error())
+		}
+		base = *parsed
+	}
+
+	// 2. Resolve system prompt (file/stdin > flag string)
+	if opts.SystemPromptReader != nil {
+		body, err := io.ReadAll(opts.SystemPromptReader)
+		if err != nil {
+			return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, fmt.Sprintf("--system-prompt-file read: %v", err))
+		}
+		opts.SystemPrompt = strings.TrimSpace(string(body))
+	}
+
+	// 3. Either copy-then-update, or create from scratch. For --from we
+	// must seed `base` from the copied agent's existing config FIRST so
+	// MergeAgentConfig preserves source fields the user did not override
+	// (e.g. SystemPrompt, AgentMode, KB list). Without this seeding the
+	// surgical overrides would ship UpdateAgent with the other 33 fields
+	// zeroed, clobbering source state.
+	if opts.From != "" {
+		copied, err := svc.CopyAgent(ctx, opts.From)
+		if err != nil {
+			return cmdutil.WrapHTTP(err, "copy agent %s", opts.From)
+		}
+		if copied.Config != nil {
+			base = *copied.Config
+		}
+
+		// --attach-kb on --from REPLACES the copied KB list; when --attach-kb
+		// is not set, KnowledgeBasesSet stays false inside applyCreateOverrides
+		// and the copy's KB list passes through unchanged.
+		cfg := applyCreateOverrides(&base, opts)
+
+		// Apply overrides on top of copied state via UpdateAgent (no
+		// server-side template-parameters route, so we do two roundtrips).
+		updateReq := &sdk.UpdateAgentRequest{
+			Name:        opts.Name,
+			Description: opts.Description,
+			Config:      cfg,
+		}
+		updated, err := svc.UpdateAgent(ctx, copied.ID, updateReq)
+		if err != nil {
+			return cmdutil.WrapHTTP(err, "update copied agent %s", copied.ID)
+		}
+		return emitAgent(fopts, updated)
+	}
+
+	// 4. Plain create path: apply hot-path flag overrides onto base
+	// (zero-valued unless --config-file supplied content).
+	cfg := applyCreateOverrides(&base, opts)
+
+	req := &sdk.CreateAgentRequest{
+		Name:        opts.Name,
+		Description: opts.Description,
+		Config:      cfg,
+	}
+	created, err := svc.CreateAgent(ctx, req)
+	if err != nil {
+		return cmdutil.WrapHTTP(err, "create agent")
+	}
+	return emitAgent(fopts, created)
+}
+
+// agentModeValues / kbSelectionModeValues are the closed server enums for the
+// --agent-mode / --kb-selection-mode flags, sourced from the SDK enumerators so
+// the CLI can't drift from the server vocabulary.
+var (
+	agentModeValues       = cmdutil.EnumStrings(sdk.AllAgentModes())
+	kbSelectionModeValues = cmdutil.EnumStrings(sdk.AllKBSelectionModes())
+)
+
+// validateAgentModeFlags validates and canonicalises --agent-mode and
+// --kb-selection-mode in place against the SDK enums. An empty value passes
+// through (flag unset → no override). Rejecting a typo here gives a fast,
+// typed input.invalid_argument instead of a confusing server-side failure.
+// Shared by `agent create` and `agent update`.
+func validateAgentModeFlags(agentMode, kbSelectionMode *string) error {
+	v, err := cmdutil.ValidateEnum("agent-mode", *agentMode, agentModeValues)
+	if err != nil {
+		return err
+	}
+	*agentMode = v
+	v, err = cmdutil.ValidateEnum("kb-selection-mode", *kbSelectionMode, kbSelectionModeValues)
+	if err != nil {
+		return err
+	}
+	*kbSelectionMode = v
+	return nil
+}
+
+// applyCreateOverrides merges hot-path flag overrides into the base config,
+// then applies the "--attach-kb implies --kb-selection-mode=selected" fallback.
+// Shared by the --from path (base=copied agent's config) and the plain
+// create path (base=zero or --config-file). Keeping both paths on one
+// helper prevents silent divergence when future flags are added.
+func applyCreateOverrides(base *sdk.AgentConfig, opts *CreateOptions) *sdk.AgentConfig {
+	overrides := cmdutil.AgentConfigFlags{
+		AgentMode: opts.AgentMode, AgentModeSet: opts.flags.agentModeSet,
+		SystemPrompt: opts.SystemPrompt, SystemPromptSet: opts.flags.systemPromptSet,
+		ModelID: opts.Model, ModelIDSet: true, // --model is required
+		RerankModelID: opts.RerankModel, RerankModelIDSet: opts.flags.rerankModelSet,
+		Temperature: opts.Temperature, TemperatureSet: opts.flags.temperatureSet,
+		KBSelectionMode: opts.KBSelectionMode, KBSelectionModeSet: opts.flags.kbSelectionModeSet,
+		KnowledgeBases: opts.KBs, KnowledgeBasesSet: opts.flags.kbsSet,
+	}
+	cfg := cmdutil.MergeAgentConfig(base, overrides)
+
+	// --attach-kb without explicit --kb-selection-mode implies "selected".
+	if opts.flags.kbsSet && !opts.flags.kbSelectionModeSet && cfg.KBSelectionMode == "" {
+		cfg.KBSelectionMode = "selected"
+	}
+	return cfg
+}
+
+// openConfigFile returns a Reader, the detected kind ("yaml"/"json"), or
+// an error. Format is inferred from file extension; "-" defaults to YAML.
+func openConfigFile(path string) (io.Reader, string, error) {
+	r, err := cmdutil.OpenInput(path)
+	if err != nil {
+		return nil, "", err
+	}
+	kind := "yaml"
+	if strings.EqualFold(filepath.Ext(path), ".json") {
+		kind = "json"
+	}
+	return r, kind, nil
+}
+
+// emitAgent writes the Agent to stdout (bare SDK shape for --format json,
+// text KV otherwise). Shared by create and edit; defined here for proximity
+// to the create flow.
+func emitAgent(fopts *cmdutil.FormatOptions, ag *sdk.Agent) error {
+	if fopts.WantsJSON() {
+		return fopts.Emit(iostreams.IO.Out, ag, nil)
+	}
+	renderAgent(iostreams.IO.Out, ag)
+	return nil
+}