feat: add custom system prompt support for AI modes

Add ai:systemprompt and ai:systempromptmode fields to waveai.json schema
allowing users to customize the system prompt for their AI modes.

- ai:systemprompt: custom system prompt text
- ai:systempromptmode: 'replace' (default) or 'append'

Update documentation with examples for both modes.

Author: suruoxi

docs/docs/waveai-modes.mdx

@@ -430,6 +430,56 @@ When using providers like `openai` or `openrouter`, the secret name is automatic
 
 The `openai` provider automatically looks for the `OPENAI_KEY` secret. See the [Secrets documentation](./secrets.mdx) for more information on managing secrets securely in Wave.
 
+## Custom System Prompts
+
+You can customize the system prompt for any AI mode to control the AI's behavior and personality. This allows you to override or extend the default Wave AI system prompt.
+
+### System Prompt Modes
+
+There are two modes for applying custom system prompts:
+
+| Mode | Description |
+|------|-------------|
+| `"replace"` (default) | Completely replaces the built-in Wave AI system prompt with your custom prompt |
+| `"append"` | Adds your custom prompt after the built-in Wave AI system prompt |
+
+### Example: Replace Mode
+
+Use this when you want full control over the AI's behavior:
+
+```json
+{
+  "my-custom-assistant": {
+    "display:name": "My Coding Assistant",
+    "ai:provider": "openai",
+    "ai:model": "gpt-4o",
+    "ai:systemprompt": "You are a specialized coding assistant focused on Go and TypeScript. Always provide concise, well-commented code examples. Prefer modern language features and best practices.",
+    "ai:systempromptmode": "replace"
+  }
+}
+```
+
+### Example: Append Mode
+
+Use this when you want to add context to the default Wave AI behavior:
+
+```json
+{
+  "ollama-with-context": {
+    "display:name": "Ollama with Project Context",
+    "ai:model": "llama3.3:70b",
+    "ai:endpoint": "http://localhost:11434/v1/chat/completions",
+    "ai:apitoken": "ollama",
+    "ai:systemprompt": "Additional context: The user is working on a terminal emulator project called Wave Terminal. They may ask about SSH, file previews, or AI integration.",
+    "ai:systempromptmode": "append"
+  }
+}
+```
+
+:::tip
+When using `"replace"` mode, your custom prompt completely replaces Wave's built-in prompt. Make sure to include any important instructions about tool usage and capabilities if you want the AI to maintain full Wave integration.
+:::
+
 ## Multiple Modes Example
 
 You can define multiple AI modes and switch between them easily:
@@ -543,6 +593,8 @@ If you get "model not found" errors:
 | `ai:azureresourcename` | No | Azure resource name (for Azure providers) |
 | `ai:azuredeployment` | No | Azure deployment name (for `azure-legacy` provider) |
 | `ai:capabilities` | No | Array of supported capabilities: `"tools"`, `"images"`, `"pdfs"` |
+| `ai:systemprompt` | No | Custom system prompt to control AI behavior for this mode |
+| `ai:systempromptmode` | No | How to apply the custom system prompt: `"replace"` (default) or `"append"` |
 | `waveai:cloud` | No | Internal - for Wave Cloud AI configuration only |
 | `waveai:premium` | No | Internal - for Wave Cloud AI configuration only |
 

frontend/types/gotypes.d.ts

@@ -33,6 +33,8 @@ declare global {
         "ai:azuredeployment"?: string;
         "ai:capabilities"?: string[];
         "ai:switchcompat"?: string[];
+        "ai:systemprompt"?: string;
+        "ai:systempromptmode"?: string;
         "waveai:cloud"?: boolean;
         "waveai:premium"?: boolean;
     };

package.json

@@ -60,6 +60,7 @@
         "prettier-plugin-jsdoc": "^1.8.0",
         "prettier-plugin-organize-imports": "^4.3.0",
         "sass": "1.91.0",
+        "sharp": "^0.34.5",
         "tailwindcss": "^4.2.1",
         "tailwindcss-animate": "^1.0.7",
         "ts-node": "^10.9.2",

pkg/aiusechat/uctypes/uctypes.go

@@ -251,20 +251,22 @@ type WaveContinueResponse struct {
 
 // Wave Specific AI opts for configuration
 type AIOptsType struct {
-	Provider      string   `json:"provider,omitempty"`
-	APIType       string   `json:"apitype,omitempty"`
-	Model         string   `json:"model"`
-	APIToken      string   `json:"apitoken"`
-	APIVersion    string   `json:"apiversion,omitempty"`
-	Endpoint      string   `json:"endpoint,omitempty"`
-	ProxyURL      string   `json:"proxyurl,omitempty"`
-	MaxTokens     int      `json:"maxtokens,omitempty"`
-	TimeoutMs     int      `json:"timeoutms,omitempty"`
-	ThinkingLevel string   `json:"thinkinglevel,omitempty"` // ThinkingLevelLow, ThinkingLevelMedium, or ThinkingLevelHigh
-	Verbosity     string   `json:"verbosity,omitempty"`     // Text verbosity level (OpenAI Responses API only, ignored by other backends)
-	AIMode        string   `json:"aimode,omitempty"`
-	Capabilities  []string `json:"capabilities,omitempty"`
-	WaveAIPremium bool     `json:"waveaipremium,omitempty"`
+	Provider         string   `json:"provider,omitempty"`
+	APIType          string   `json:"apitype,omitempty"`
+	Model            string   `json:"model"`
+	APIToken         string   `json:"apitoken"`
+	APIVersion       string   `json:"apiversion,omitempty"`
+	Endpoint         string   `json:"endpoint,omitempty"`
+	ProxyURL         string   `json:"proxyurl,omitempty"`
+	MaxTokens        int      `json:"maxtokens,omitempty"`
+	TimeoutMs        int      `json:"timeoutms,omitempty"`
+	ThinkingLevel    string   `json:"thinkinglevel,omitempty"` // ThinkingLevelLow, ThinkingLevelMedium, or ThinkingLevelHigh
+	Verbosity        string   `json:"verbosity,omitempty"`     // Text verbosity level (OpenAI Responses API only, ignored by other backends)
+	AIMode           string   `json:"aimode,omitempty"`
+	Capabilities     []string `json:"capabilities,omitempty"`
+	WaveAIPremium    bool     `json:"waveaipremium,omitempty"`
+	SystemPrompt     string   `json:"systemprompt,omitempty"`     // Custom system prompt text
+	SystemPromptMode string   `json:"systempromptmode,omitempty"` // "replace" or "append" (defaults to "replace")
 }
 
 func (opts AIOptsType) IsWaveProxy() bool {

pkg/aiusechat/usechat.go

@@ -46,21 +46,34 @@ var (
 	activeChats = ds.MakeSyncMap[bool]() // key is chatid
 )
 
-func getSystemPrompt(apiType string, model string, isBuilder bool, hasToolsCapability bool, widgetAccess bool) []string {
+func getSystemPrompt(apiType string, model string, isBuilder bool, hasToolsCapability bool, widgetAccess bool, customPrompt string, customPromptMode string) []string {
 	if isBuilder {
 		return []string{}
 	}
+	// Normalize empty mode to "replace" (the default)
+	if customPromptMode == "" {
+		customPromptMode = "replace"
+	}
+	// If a custom system prompt is configured with "replace" mode, use it directly
+	if customPrompt != "" && customPromptMode == "replace" {
+		return []string{customPrompt}
+	}
 	useNoToolsPrompt := !hasToolsCapability || !widgetAccess
 	basePrompt := SystemPromptText_OpenAI
 	if useNoToolsPrompt {
 		basePrompt = SystemPromptText_NoTools
 	}
 	modelLower := strings.ToLower(model)
 	needsStrictToolAddOn, _ := regexp.MatchString(`(?i)\b(mistral|o?llama|qwen|mixtral|yi|phi|deepseek)\b`, modelLower)
+	prompts := []string{basePrompt}
 	if needsStrictToolAddOn && !useNoToolsPrompt {
-		return []string{basePrompt, SystemPromptText_StrictToolAddOn}
+		prompts = append(prompts, SystemPromptText_StrictToolAddOn)
 	}
-	return []string{basePrompt}
+	// If a custom system prompt is configured with "append" mode, append it
+	if customPrompt != "" && customPromptMode == "append" {
+		prompts = append(prompts, customPrompt)
+	}
+	return prompts
 }
 
 func isLocalEndpoint(endpoint string) bool {
@@ -106,6 +119,9 @@ func getWaveAISettings(premium bool, builderMode bool, rtInfo waveobj.ObjRTInfo,
 		return nil, fmt.Errorf("no ai:endpoint configured for AI mode %s", aiMode)
 	}
 
+	if config.SystemPromptMode != "" && config.SystemPromptMode != "replace" && config.SystemPromptMode != "append" {
+		return nil, fmt.Errorf("invalid ai:systempromptmode %q: must be \"replace\" or \"append\"", config.SystemPromptMode)
+	}
 	thinkingLevel := config.ThinkingLevel
 	if thinkingLevel == "" {
 		thinkingLevel = uctypes.ThinkingLevelMedium
@@ -115,17 +131,19 @@ func getWaveAISettings(premium bool, builderMode bool, rtInfo waveobj.ObjRTInfo,
 		verbosity = uctypes.VerbosityLevelMedium // default to medium
 	}
 	opts := &uctypes.AIOptsType{
-		Provider:      config.Provider,
-		APIType:       config.APIType,
-		Model:         config.Model,
-		MaxTokens:     maxTokens,
-		ThinkingLevel: thinkingLevel,
-		Verbosity:     verbosity,
-		AIMode:        aiMode,
-		Endpoint:      baseUrl,
-		ProxyURL:      config.ProxyURL,
-		Capabilities:  config.Capabilities,
-		WaveAIPremium: config.WaveAIPremium,
+		Provider:         config.Provider,
+		APIType:          config.APIType,
+		Model:            config.Model,
+		MaxTokens:        maxTokens,
+		ThinkingLevel:    thinkingLevel,
+		Verbosity:        verbosity,
+		AIMode:           aiMode,
+		Endpoint:         baseUrl,
+		ProxyURL:         config.ProxyURL,
+		Capabilities:     config.Capabilities,
+		WaveAIPremium:    config.WaveAIPremium,
+		SystemPrompt:     config.SystemPrompt,
+		SystemPromptMode: config.SystemPromptMode,
 	}
 	if apiToken != "" {
 		opts.APIToken = apiToken
@@ -692,7 +710,7 @@ func WaveAIPostMessageHandler(w http.ResponseWriter, r *http.Request) {
 		BuilderId:            req.BuilderId,
 		BuilderAppId:         req.BuilderAppId,
 	}
-	chatOpts.SystemPrompt = getSystemPrompt(chatOpts.Config.APIType, chatOpts.Config.Model, chatOpts.BuilderId != "", chatOpts.Config.HasCapability(uctypes.AICapabilityTools), chatOpts.WidgetAccess)
+	chatOpts.SystemPrompt = getSystemPrompt(chatOpts.Config.APIType, chatOpts.Config.Model, chatOpts.BuilderId != "", chatOpts.Config.HasCapability(uctypes.AICapabilityTools), chatOpts.WidgetAccess, chatOpts.Config.SystemPrompt, chatOpts.Config.SystemPromptMode)
 
 	if req.TabId != "" {
 		chatOpts.TabStateGenerator = func() (string, []uctypes.ToolDefinition, string, error) {

pkg/wconfig/settingsconfig.go

@@ -301,6 +301,8 @@ type AIModeConfigType struct {
 	AzureDeployment    string   `json:"ai:azuredeployment,omitempty"`
 	Capabilities       []string `json:"ai:capabilities,omitempty" jsonschema:"enum=pdfs,enum=images,enum=tools"`
 	SwitchCompat       []string `json:"ai:switchcompat,omitempty"`
+	SystemPrompt       string   `json:"ai:systemprompt,omitempty" jsonschema_description:"Custom system prompt to control AI behavior for this mode"`
+	SystemPromptMode   string   `json:"ai:systempromptmode,omitempty" jsonschema:"enum=replace,enum=append" jsonschema_description:"How to apply the custom system prompt: replace (fully replace built-in prompt) or append (add after built-in prompt). Defaults to replace."`
 	WaveAICloud        bool     `json:"waveai:cloud,omitempty"`
 	WaveAIPremium      bool     `json:"waveai:premium,omitempty"`
 }

schema/waveai.json

@@ -95,6 +95,18 @@
           },
           "type": "array"
         },
+        "ai:systemprompt": {
+          "type": "string",
+          "description": "Custom system prompt to control AI behavior for this mode"
+        },
+        "ai:systempromptmode": {
+          "type": "string",
+          "enum": [
+            "replace",
+            "append"
+          ],
+          "description": "How to apply the custom system prompt: replace (fully replace built-in prompt) or append (add after built-in prompt). Defaults to replace."
+        },
         "waveai:cloud": {
           "type": "boolean"
         },