refactor(prompt): modular system prompt with identity-first ordering

- Extract prompt assembly into prompt_modules.go with per-mode module lists
  (Agent: 13 modules, Chatbot: 12 modules, Customize: 3 modules)
- Move SOUL.md/IDENTITY.md to top of prompt (primacy bias) with identity
  anchor + tail reinforcement (recency bias) to fix persona amnesia
- Chatbot mode: add web_search, web_fetch, exec, load_skill to tool
  allowlist; add sandbox/skills/chatbot_tools modules; cap tool iterations
  at 5 (configurable per-agent); block pip/npm install commands
- Add FASTCLAW_DEBUG_MODE env var for debug output (prompt dump etc.)
- set_timezone: write to USER.md (primary) + database (secondary) so
  timezone persists across sessions without extra DB lookup
- Date line: distinguish explicit vs fallback timezone to prevent model
  from re-asking timezone every new session
- WeChat inbound: handle image messages (download + AES-ECB decrypt from
  CDN → base64 data URL → vision model), with debug logging

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: idoubi

internal/agent/context.go

@@ -3066,10 +3066,10 @@ func (a *Agent) RegisteredTools() []tools.ToolInfo {
 // (cron-triggered greetings, multi-recipient broadcasts) should fall
 // back to `agent` mode or write a plugin.
 //
-// Also absent: exec, web_fetch / web_search, scheduling, delegation
-// — all agent-loop machinery that doesn't belong in a chat persona's
-// voice. Add new built-ins here only when they're universally useful
-// for chatbot products; everything else belongs in a plugin.
+// Still absent: scheduling (create_cron_job), delegation (delegate_task),
+// start_app_preview — agent-loop machinery that doesn't belong in a
+// chat persona. Add new built-ins here only when they're universally
+// useful for chatbot products; everything else belongs in a plugin.
 var chatbotBuiltinAllowlist = []string{
 	"image_gen",
 	"tts",
@@ -3078,12 +3078,15 @@ var chatbotBuiltinAllowlist = []string{
 	// set_timezone keeps "their local time" right for chat (greetings,
 	// "晚安" timing) — chatbots need it as much as full agents do.
 	"set_timezone",
-	// Coding-agent preview tools. Only ever REGISTERED when a project
-	// runtime is wired (SetProjectRuntime), so listing them here is a
-	// harmless no-op for ordinary chat personas and makes the preview
-	// usable regardless of the agent's prompt mode.
-	"start_app_preview",
-	"app_preview_logs",
+	// Web tools let the chatbot answer real-time questions (weather,
+	// news, prices, etc.) without requiring full agent mode.
+	"web_search",
+	"web_fetch",
+	// exec + load_skill let the chatbot invoke installed skills
+	// (e.g. image generation, data lookup). Skills are the primary
+	// extension mechanism — without exec the chatbot can't run them.
+	"exec",
+	"load_skill",
 }
 
 // builtinAllowForMode returns the built-in tool name allowlist for the

internal/agent/loop.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"strings"
 	"time"
 
 	"github.com/fastclaw-ai/fastclaw/internal/scope"
@@ -14,20 +15,21 @@ type setTimezoneArgs struct {
 	Timezone string `json:"timezone"`
 }
 
-// RegisterTimezoneTool registers set_timezone — the structured
-// counterpart to "write the chatter's timezone into USER.md". USER.md
-// is free text the model may or may not act on; this tool persists the
-// timezone where the RUNTIME reads it (scope prefs), so the system
-// prompt's date line and cron scheduling switch to the chatter's local
-// time deterministically instead of relying on the model doing offset
-// arithmetic.
+// RegisterTimezoneTool registers set_timezone. The tool persists the
+// timezone in TWO places:
 //
-// The chatter is resolved at execute time via r.ChatterUserID() —
-// bindSession stamps it per-turn — so one registration serves every
-// sender the agent talks to.
+//  1. USER.md — the chatter profile loaded into every system prompt.
+//     This is the primary path: chatterLocation() reads USER.md first,
+//     so the date line shows the correct timezone on every new session
+//     without depending on a database query.
+//  2. scope prefs (database) — used by cron scheduling so jobs fire at
+//     the chatter's local time. This is the secondary path.
+//
+// Writing to both guarantees the timezone survives across sessions and
+// is visible to the model in the system prompt.
 func RegisterTimezoneTool(r *Registry, st store.Store) {
 	r.Register("set_timezone",
-		"Record the current chatter's timezone. Call this whenever the chatter tells you their timezone, city, or country (e.g. \"我在北京\" → Asia/Shanghai), or when their messages imply one. The runtime uses it to show you their local time and to fire their scheduled tasks at the right local hour — do NOT just note the timezone in USER.md, that does not affect scheduling.",
+		"Record the current chatter's timezone. Call this whenever the chatter tells you their timezone, city, or country (e.g. \"我在北京\" → Asia/Shanghai). This persists the timezone to the chatter's profile so future sessions use their local time automatically.",
 		map[string]interface{}{
 			"type": "object",
 			"properties": map[string]interface{}{
@@ -51,9 +53,6 @@ func makeSetTimezone(st store.Store, r *Registry) ToolFunc {
 		if args.Timezone == "" {
 			return "", fmt.Errorf("timezone is required")
 		}
-		// "Local" is technically loadable but meaningless to persist —
-		// it would pin the chatter to whatever the server's TZ happens
-		// to be at read time.
 		if args.Timezone == "Local" {
 			return "", fmt.Errorf("timezone must be a concrete IANA name like 'Asia/Shanghai', not 'Local'")
 		}
@@ -65,10 +64,52 @@ func makeSetTimezone(st store.Store, r *Registry) ToolFunc {
 		if chatterUID == "" {
 			return "", fmt.Errorf("no chatter identity on this turn — cannot persist timezone")
 		}
-		if err := scope.SaveUserTimezone(ctx, st, chatterUID, args.Timezone); err != nil {
-			return "", fmt.Errorf("save timezone: %w", err)
+
+		// 1. Write to USER.md — primary persistence path.
+		// chatterLocation() reads USER.md first, so this guarantees the
+		// date line shows the correct timezone on every future session.
+		if r.systemFileStore != nil {
+			userMDUID := r.systemFileUserID("USER.md")
+			upsertUserMDTimezone(ctx, r, userMDUID, args.Timezone)
+		}
+
+		// 2. Write to scope prefs (database) — secondary path for cron.
+		if st != nil {
+			_ = scope.SaveUserTimezone(ctx, st, chatterUID, args.Timezone)
 		}
-		return fmt.Sprintf("Timezone saved: %s. The chatter's local time is now %s. New scheduled tasks will fire in this timezone; existing ones keep the timezone they were created with.",
+
+		return fmt.Sprintf("Timezone saved: %s. The chatter's local time is now %s.",
 			args.Timezone, time.Now().In(loc).Format("2006-01-02 15:04:05 -0700 (Monday)")), nil
 	}
 }
+
+// upsertUserMDTimezone reads the current USER.md, adds or updates a
+// "Timezone: <tz>" line, and writes it back. If USER.md doesn't exist
+// yet, it creates a minimal one with just the timezone.
+func upsertUserMDTimezone(ctx context.Context, r *Registry, userID, tz string) {
+	const filename = "USER.md"
+	const tzPrefix = "- Timezone: "
+
+	content := ""
+	if data, err := r.readSystemFileForUser(ctx, userID, filename); err == nil {
+		content = strings.TrimSpace(string(data))
+	}
+
+	// Check if there's already a Timezone line and update it.
+	if idx := strings.Index(content, tzPrefix); idx >= 0 {
+		// Find end of the line.
+		end := strings.Index(content[idx:], "\n")
+		if end < 0 {
+			end = len(content) - idx
+		}
+		content = content[:idx] + tzPrefix + tz + content[idx+end:]
+	} else if content != "" {
+		// Append to existing content.
+		content = content + "\n" + tzPrefix + tz
+	} else {
+		// Create new USER.md with timezone.
+		content = "# Current Chatter\n" + tzPrefix + tz
+	}
+
+	_ = r.systemFileStore.SaveWorkspaceFile(ctx, r.agentID, userID, filename, []byte(content))
+}

internal/agent/prompt_modules.go

@@ -392,12 +392,40 @@ func (w *WeChat) dispatchInbound(m wechatMessage) {
 	}
 
 	var text string
+	var imageURLs []string
 	for _, item := range m.ItemList {
 		switch item.Type {
 		case wechatItemTypeText:
 			if item.TextItem != nil && item.TextItem.Text != "" {
 				text = item.TextItem.Text
 			}
+		case wechatItemTypeImage:
+			if item.ImageItem == nil {
+				continue
+			}
+			// Log the raw image item for debugging — need to understand
+			// what iLink actually sends before deciding how to process.
+			slog.Info("wechat inbound image item",
+				"account", w.accountID, "from", m.FromUserID,
+				"has_url", item.ImageItem.URL != "",
+				"url_preview", truncate(item.ImageItem.URL, 80),
+				"has_media", item.ImageItem.Media != nil,
+				"encrypt_query_param", truncateMediaParam(item.ImageItem.Media),
+				"mid_size", item.ImageItem.MidSize)
+			// Download + decrypt from CDN, encode as data URL.
+			// iLink CDN URLs are encrypted/auth-only — the model cannot
+			// fetch them directly. Must download and decrypt first.
+			if item.ImageItem.Media != nil && item.ImageItem.Media.EncryptQueryParam != "" {
+				if dataURL, err := w.downloadAndDecryptImage(item.ImageItem); err != nil {
+					slog.Warn("wechat image download failed",
+						"account", w.accountID, "from", m.FromUserID, "error", err)
+				} else {
+					imageURLs = append(imageURLs, dataURL)
+				}
+			} else if item.ImageItem.URL != "" {
+				// Fallback: try direct URL if no encrypted media present.
+				imageURLs = append(imageURLs, item.ImageItem.URL)
+			}
 		case wechatItemTypeVoice:
 			// iLink ships speech-to-text transcription alongside the
 			// audio bytes — use it directly so the agent sees the
@@ -407,15 +435,17 @@ func (w *WeChat) dispatchInbound(m wechatMessage) {
 				text = item.VoiceItem.Text
 			}
 		}
-		if text != "" {
-			break
-		}
 	}
-	if text == "" {
+	if text == "" && len(imageURLs) == 0 {
 		slog.Debug("wechat skipping unsupported message",
 			"account", w.accountID, "from", m.FromUserID, "items", len(m.ItemList))
 		return
 	}
+	// Image-only messages: give the model a text cue so it knows to
+	// describe or act on the image rather than seeing an empty turn.
+	if text == "" && len(imageURLs) > 0 {
+		text = "[image]"
+	}
 
 	// iLink doesn't distinguish DM vs group at the protocol level the
 	// way Telegram does — every message has a from_user_id and a
@@ -442,6 +472,7 @@ func (w *WeChat) dispatchInbound(m wechatMessage) {
 		UserID:    m.FromUserID,
 		MessageID: strconv.FormatInt(m.MessageID, 10),
 		Text:      text,
+		PhotoURLs: imageURLs,
 		PeerKind:  "dm",
 	}
 }
@@ -1134,6 +1165,95 @@ func wechatAESECBEncrypt(plaintext, key []byte) ([]byte, error) {
 	return encrypted, nil
 }
 
+// downloadAndDecryptImage fetches an AES-128-ECB encrypted image from
+// the iLink CDN and returns a base64 data URL the vision model can read.
+func (w *WeChat) downloadAndDecryptImage(img *wechatImageItem) (string, error) {
+	if img.Media == nil || img.Media.EncryptQueryParam == "" {
+		return "", fmt.Errorf("no media info")
+	}
+	// Reconstruct the CDN download URL from the encrypt_query_param.
+	cdnURL := fmt.Sprintf("%s/download?encrypted_query_param=%s",
+		wechatCDNBaseURL, url.QueryEscape(img.Media.EncryptQueryParam))
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, cdnURL, nil)
+	if err != nil {
+		return "", err
+	}
+	resp, err := w.httpClient.Do(req)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("CDN HTTP %d", resp.StatusCode)
+	}
+	ciphertext, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", err
+	}
+
+	// Decode the AES key. Wire format: base64(hex_string).
+	aesKeyB64 := img.Media.AESKey
+	aesKeyHex, err := base64.StdEncoding.DecodeString(aesKeyB64)
+	if err != nil {
+		return "", fmt.Errorf("decode aes key base64: %w", err)
+	}
+	aesKey, err := hex.DecodeString(string(aesKeyHex))
+	if err != nil {
+		return "", fmt.Errorf("decode aes key hex: %w", err)
+	}
+
+	plaintext, err := wechatAESECBDecrypt(ciphertext, aesKey)
+	if err != nil {
+		return "", fmt.Errorf("decrypt: %w", err)
+	}
+
+	// Detect content type and encode as data URL.
+	ct := http.DetectContentType(plaintext)
+	b64 := base64.StdEncoding.EncodeToString(plaintext)
+	return fmt.Sprintf("data:%s;base64,%s", ct, b64), nil
+}
+
+// wechatAESECBDecrypt is the inverse of wechatAESECBEncrypt — PKCS7 unpad.
+func wechatAESECBDecrypt(ciphertext, key []byte) ([]byte, error) {
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, err
+	}
+	if len(ciphertext)%aes.BlockSize != 0 {
+		return nil, fmt.Errorf("ciphertext not aligned to block size")
+	}
+	plaintext := make([]byte, len(ciphertext))
+	for i := 0; i < len(ciphertext); i += aes.BlockSize {
+		block.Decrypt(plaintext[i:i+aes.BlockSize], ciphertext[i:i+aes.BlockSize])
+	}
+	// PKCS7 unpad.
+	if len(plaintext) == 0 {
+		return plaintext, nil
+	}
+	padLen := int(plaintext[len(plaintext)-1])
+	if padLen > aes.BlockSize || padLen == 0 {
+		return plaintext, nil // not padded or invalid — return as-is
+	}
+	return plaintext[:len(plaintext)-padLen], nil
+}
+
+func truncate(s string, n int) string {
+	if len(s) <= n {
+		return s
+	}
+	return s[:n] + "..."
+}
+
+func truncateMediaParam(m *wechatMediaInfo) string {
+	if m == nil {
+		return ""
+	}
+	return truncate(m.EncryptQueryParam, 40)
+}
+
 func wechatAESECBPaddedSize(plaintextSize int) int {
 	return (plaintextSize/aes.BlockSize + 1) * aes.BlockSize
 }

internal/agent/tools/timezone.go

@@ -857,6 +857,17 @@ func (cfg *Config) MergedAgentConfig(entry AgentEntry) ResolvedAgent {
 		}
 	}
 
+	// Chatbot mode: cap tool iterations at a lower default (5) unless
+	// the operator explicitly set a value on the agent entry. Chatbots
+	// are conversational — 20 tool rounds burns tokens and makes the
+	// user wait too long.
+	if resolved.PromptMode == PromptModeChatbot && entry.MaxToolIterations == 0 {
+		const chatbotDefaultIter = 5
+		if resolved.MaxToolIterations > chatbotDefaultIter {
+			resolved.MaxToolIterations = chatbotDefaultIter
+		}
+	}
+
 	return resolved
 }
 

internal/channels/wechat.go

@@ -43,7 +43,8 @@ type EnvSandbox struct {
 }
 
 type EnvLog struct {
-	Level string // FASTCLAW_LOG_LEVEL — "debug" / "info" / "warn" / "error"
+	Level string // FASTCLAW_LOG_LEVEL    — "debug" / "info" / "warn" / "error"
+	Debug bool   // FASTCLAW_DEBUG_MODE   — enable verbose debug output (prompt dump, etc.)
 }
 
 // LoadEnv reads the bootstrap configuration from FASTCLAW_* environment
@@ -106,6 +107,9 @@ func LoadEnv() *EnvConfig {
 	if v := os.Getenv("FASTCLAW_LOG_LEVEL"); v != "" {
 		cfg.Log.Level = v
 	}
+	if v := os.Getenv("FASTCLAW_DEBUG_MODE"); v == "true" || v == "1" {
+		cfg.Log.Debug = true
+	}
 	return cfg
 }
 
@@ -147,6 +151,15 @@ func applyObjectStoreEnv(cfg *Config) {
 	}
 }
 
+// debugMode is read once at package init. All debug-gated output in
+// the codebase checks this via DebugMode().
+var debugMode = os.Getenv("FASTCLAW_DEBUG_MODE") == "true" || os.Getenv("FASTCLAW_DEBUG_MODE") == "1"
+
+// DebugMode returns true when FASTCLAW_DEBUG_MODE=true|1. Use this to
+// gate verbose output (prompt dumps, request traces, etc.) that is
+// useful during development but noisy in production.
+func DebugMode() bool { return debugMode }
+
 // ScrubBootSecrets removes credential-bearing env vars from the
 // process environment AFTER bootstrap config has been read. Call once
 // from the daemon entry point after gateway construction.