center">
- 
-
- PicoClaw: Ultra-Efficient AI Assistant in Go
- -$10 Hardware · <10MB RAM · <1s Boot · 皮皮虾，我们走！
-
- 
- 
- -SipeedIO-black?style=flat&logo=x&logoColor=white){kind=icon}
|
-
- |
-
-
- |
-
- 
-
-
-
-## ✨ Features
-
-🪶 **Ultra-Lightweight**: <10MB Memory footprint — 99% smaller than OpenClaw core functionality.*
-
-💰 **Minimal Cost**: Efficient enough to run on $10 Hardware — 98% cheaper than a Mac mini.
-
-⚡️ **Lightning Fast**: 400X Faster startup time, boot in <1 second even on 0.6GHz single core.
-
-🌍 **True Portability**: Single self-contained binary across RISC-V, ARM, MIPS, and x86, One-click to Go!
-
-🤖 **AI-Bootstrapped**: Autonomous Go-native implementation — 95% Agent-generated core with human-in-the-loop refinement.
-
-🔌 **MCP Support**: Native [Model Context Protocol](https://modelcontextprotocol.io/) integration — connect any MCP server to extend agent capabilities.
-
-👁️ **Vision Pipeline**: Send images and files directly to the agent — automatic base64 encoding for multimodal LLMs.
-
-🧠 **Smart Routing**: Rule-based model routing — simple queries go to lightweight models, saving API costs.
-
-_*Recent versions may use 10–20MB due to rapid feature merges. Resource optimization is planned. Startup comparison based on 0.8GHz single-core benchmarks (see table below)._
-
-| | OpenClaw | NanoBot | **PicoClaw** |
-| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- |
-| **Language** | TypeScript | Python | **Go** |
-| **RAM** | >1GB | >100MB | **< 10MB*** |
-| **Startup**(0.8GHz core) | >500s | >30s | **<1s** |
-| **Cost** | Mac Mini $599 | Most Linux SBC ~$50 | **Any Linux Board****As low as $10** |
-
-Older news...
- -2026-02-16 🎉 PicoClaw hit 12K stars in one week! Community maintainer roles and [roadmap](ROADMAP.md) officially posted. - -2026-02-13 🎉 PicoClaw hit 5000 stars in 4 days! Project Roadmap and Developer Group setup underway. - -2026-02-09 🎉 **PicoClaw Launched!** Built in 1 day to bring AI Agents to $10 hardware with <10MB RAM. 🦐 PicoClaw，Let's Go！ - -
-
-> 📋 **[Hardware Compatibility List](docs/hardware-compatibility.md)** — See all tested boards, from $5 RISC-V to Raspberry Pi to Android phones. Your board not listed? Submit a PR!
-
-## 🦾 Demonstration
-
-### 🛠️ Standard Assistant Workflows
-
-🧩 Full-Stack Engineer |
- 🗂️ Logging & Planning Management |
- 🔎 Web Search & Learning |
-
|---|---|---|
|
-
|
-
|
-
| Develop • Deploy • Scale | -Schedule • Automate • Memory | -Discovery • Insights • Trends | -
+PicoClaw stores data in your configured workspace (default: `~/.picoclaw/workspace`):
-### 🐜 Innovative Low-Footprint Deploy
+```
+~/.picoclaw/workspace/
+├── sessions/ # Conversation sessions and history
+├── memory/ # Long-term memory (MEMORY.md)
+├── state/ # Persistent state (last channel, etc.)
+├── cron/ # Scheduled jobs database
+├── skills/ # Workspace-specific skills
+├── AGENT.md # Structured agent definition and system prompt
+├── SOUL.md # Agent soul
+├── USER.md # User profile and preferences for this workspace
+├── HEARTBEAT.md # Periodic task prompts (checked every 30 min)
+└── ...
+```
-PicoClaw can be deployed on almost any Linux device!
+### Skill Sources
-- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(Ethernet) or W(WiFi6) version, for Minimal Home Assistant
-- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), or $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) for Automated Server Maintenance
-- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) or $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) for Smart Monitoring
+By default, skills are loaded from:
-
+
+
+Zhipu
+ +**1. Get API key and base URL** + +* Get [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) + +**2. Configure** + +```json +{ + "agents": { + "defaults": { + "workspace": "~/.picoclaw/workspace", + "model": "glm-4.7", + "max_tokens": 8192, + "temperature": 0.7, + "max_tool_iterations": 20 + } + }, + "providers": { + "zhipu": { + "api_key": "Your API Key", + "api_base": "https://open.bigmodel.cn/api/paas/v4" + } + } +} +``` + +**3. Run** + +```bash +picoclaw agent -m "Hello" +``` + +
+
Join the Agent Social Network
-
-Connect Picoclaw to the Agent Social Network simply by sending a single message via the CLI or any integrated Chat App.
-
-**Read `https://clawdchat.ai/skill.md` and follow the instructions to join [ClawdChat.ai](https://clawdchat.ai)**
-
## 🖥️ CLI Reference
| Command | Description |
| ------------------------- | ----------------------------- |
| `picoclaw onboard` | Initialize config & workspace |
+| `picoclaw onboard weixin` | Connect WeChat account via QR |
| `picoclaw agent -m "..."` | Chat with the agent |
| `picoclaw agent` | Interactive chat mode |
| `picoclaw gateway` | Start the gateway |
| `picoclaw status` | Show status |
| `picoclaw version` | Show version info |
+| `picoclaw model` | Show or change default model |
| `picoclaw cron list` | List all scheduled jobs |
| `picoclaw cron add ...` | Add a scheduled job |
| `picoclaw cron disable` | Disable a scheduled job |
@@ -1492,52 +1426,5 @@ User Groups:
discord:
-
-
-## Join the Agent Social Network
-
-Connect Picoclaw to the Agent Social Network simply by sending a single message via the CLI or any integrated Chat App.
-
-**Read `https://clawdchat.ai/skill.md` and follow the instructions to join [ClawdChat.ai](https://clawdchat.ai)**
-
-## 🖥️ CLI Reference
-
-| Command | Description |
-| ------------------------- | ----------------------------- |
-| `picoclaw onboard` | Initialize config & workspace |
-| `picoclaw agent -m "..."` | Chat with the agent |
-| `picoclaw agent` | Interactive chat mode |
-| `picoclaw gateway` | Start the gateway |
-| `picoclaw status` | Show status |
-| `picoclaw version` | Show version info |
-| `picoclaw cron list` | List all scheduled jobs |
-| `picoclaw cron add ...` | Add a scheduled job |
-| `picoclaw cron disable` | Disable a scheduled job |
-| `picoclaw cron remove` | Remove a scheduled job |
-| `picoclaw skills list` | List installed skills |
-| `picoclaw skills install` | Install a skill |
-| `picoclaw migrate` | Migrate data from older versions |
-| `picoclaw auth login` | Authenticate with providers |
-| `picoclaw model` | View or switch the default model |
-
-### Scheduled Tasks / Reminders
-
-PicoClaw supports scheduled reminders and recurring tasks through the `cron` tool:
-
-* **One-time reminders**: "Remind me in 10 minutes" → triggers once after 10min
-* **Recurring tasks**: "Remind me every 2 hours" → triggers every 2 hours
-* **Cron expressions**: "Remind me at 9am daily" → uses cron expression
-
-## 🤝 Contribute & Roadmap
-
-PRs welcome! The codebase is intentionally small and readable. 🤗
-
-See our full [Community Roadmap](https://github.com/sipeed/picoclaw/blob/main/ROADMAP.md).
-
-Developer group building, join after your first merged PR!
-
-User Groups:
-
-discord:
-
-
+WeChat:
+
diff --git a/README.zh.md b/README.zh.md
index db34f57d..1bc5d1a4 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -218,6 +218,7 @@ make install
| 命令 | 说明 |
| ------------------------- | ---------------------- |
| `picoclaw onboard` | 初始化配置与工作区 |
+| `picoclaw onboard weixin` | 扫码连接微信个人号 |
| `picoclaw agent -m "..."` | 与 Agent 对话 |
| `picoclaw agent` | 交互式对话模式 |
| `picoclaw gateway` | 启动网关 |
diff --git a/assets/wechat.png b/assets/wechat.png
index 6512421e..effb4dab 100644
Binary files a/assets/wechat.png and b/assets/wechat.png differ
diff --git a/cmd/picoclaw/internal/agent/helpers.go b/cmd/picoclaw/internal/agent/helpers.go
index c3ddbb77..0af743bb 100644
--- a/cmd/picoclaw/internal/agent/helpers.go
+++ b/cmd/picoclaw/internal/agent/helpers.go
@@ -23,16 +23,16 @@ func agentCmd(message, sessionKey, model string, debug bool) error {
sessionKey = "cli:default"
}
- if debug {
- logger.SetLevel(logger.DEBUG)
- fmt.Println("🔍 Debug mode enabled")
- }
-
cfg, err := internal.LoadConfig()
if err != nil {
return fmt.Errorf("error loading config: %w", err)
}
+ if debug {
+ logger.SetLevel(logger.DEBUG)
+ fmt.Println("🔍 Debug mode enabled")
+ }
+
if model != "" {
cfg.Agents.Defaults.ModelName = model
}
diff --git a/cmd/picoclaw/internal/helpers.go b/cmd/picoclaw/internal/helpers.go
index 6b2d65c9..ae1d58c2 100644
--- a/cmd/picoclaw/internal/helpers.go
+++ b/cmd/picoclaw/internal/helpers.go
@@ -5,6 +5,7 @@ import (
"path/filepath"
"github.com/sipeed/picoclaw/pkg/config"
+ "github.com/sipeed/picoclaw/pkg/logger"
)
const Logo = "🦞"
@@ -27,7 +28,12 @@ func GetConfigPath() string {
}
func LoadConfig() (*config.Config, error) {
- return config.LoadConfig(GetConfigPath())
+ cfg, err := config.LoadConfig(GetConfigPath())
+ if err != nil {
+ return nil, err
+ }
+ logger.SetLevelFromString(cfg.Agents.Defaults.LogLevel)
+ return cfg, nil
}
// FormatVersion returns the version string with optional git commit
diff --git a/cmd/picoclaw/internal/onboard/command.go b/cmd/picoclaw/internal/onboard/command.go
index 9f8b288c..1f94c671 100644
--- a/cmd/picoclaw/internal/onboard/command.go
+++ b/cmd/picoclaw/internal/onboard/command.go
@@ -16,14 +16,22 @@ func NewOnboardCommand() *cobra.Command {
cmd := &cobra.Command{
Use: "onboard",
Aliases: []string{"o"},
- Short: "Initialize picoclaw configuration and workspace",
+ Short: "Initialize picoclaw configuration, workspace, and channel accounts",
+ // Run without subcommands → original onboard flow
Run: func(cmd *cobra.Command, args []string) {
- onboard(encrypt)
+ if len(args) == 0 {
+ onboard(encrypt)
+ } else {
+ _ = cmd.Help()
+ }
},
}
cmd.Flags().BoolVar(&encrypt, "enc", false,
"Enable credential encryption (generates SSH key and prompts for passphrase)")
+ // Channel onboarding subcommands
+ cmd.AddCommand(newWeixinCommand())
+
return cmd
}
diff --git a/cmd/picoclaw/internal/onboard/command_test.go b/cmd/picoclaw/internal/onboard/command_test.go
index 56936190..6b9fb6e9 100644
--- a/cmd/picoclaw/internal/onboard/command_test.go
+++ b/cmd/picoclaw/internal/onboard/command_test.go
@@ -13,7 +13,7 @@ func TestNewOnboardCommand(t *testing.T) {
require.NotNil(t, cmd)
assert.Equal(t, "onboard", cmd.Use)
- assert.Equal(t, "Initialize picoclaw configuration and workspace", cmd.Short)
+ assert.Equal(t, "Initialize picoclaw configuration, workspace, and channel accounts", cmd.Short)
assert.Len(t, cmd.Aliases, 1)
assert.True(t, cmd.HasAlias("o"))
@@ -28,5 +28,6 @@ func TestNewOnboardCommand(t *testing.T) {
encFlag := cmd.Flags().Lookup("enc")
require.NotNil(t, encFlag, "expected --enc flag to be registered")
assert.Equal(t, "false", encFlag.DefValue, "--enc should default to false")
- assert.False(t, cmd.HasSubCommands())
+ assert.True(t, cmd.HasSubCommands())
+ assert.NotNil(t, cmd.Commands())
}
diff --git a/cmd/picoclaw/internal/onboard/helpers_test.go b/cmd/picoclaw/internal/onboard/helpers_test.go
index f3e0c92e..23fc97c5 100644
--- a/cmd/picoclaw/internal/onboard/helpers_test.go
+++ b/cmd/picoclaw/internal/onboard/helpers_test.go
@@ -6,20 +6,32 @@ import (
"testing"
)
-func TestCopyEmbeddedToTargetUsesAgentsMarkdown(t *testing.T) {
+func TestCopyEmbeddedToTargetUsesStructuredAgentFiles(t *testing.T) {
targetDir := t.TempDir()
if err := copyEmbeddedToTarget(targetDir); err != nil {
t.Fatalf("copyEmbeddedToTarget() error = %v", err)
}
- agentsPath := filepath.Join(targetDir, "AGENTS.md")
- if _, err := os.Stat(agentsPath); err != nil {
- t.Fatalf("expected %s to exist: %v", agentsPath, err)
+ agentPath := filepath.Join(targetDir, "AGENT.md")
+ if _, err := os.Stat(agentPath); err != nil {
+ t.Fatalf("expected %s to exist: %v", agentPath, err)
}
- legacyPath := filepath.Join(targetDir, "AGENT.md")
- if _, err := os.Stat(legacyPath); !os.IsNotExist(err) {
- t.Fatalf("expected legacy file %s to be absent, got err=%v", legacyPath, err)
+ soulPath := filepath.Join(targetDir, "SOUL.md")
+ if _, err := os.Stat(soulPath); err != nil {
+ t.Fatalf("expected %s to exist: %v", soulPath, err)
+ }
+
+ userPath := filepath.Join(targetDir, "USER.md")
+ if _, err := os.Stat(userPath); err != nil {
+ t.Fatalf("expected %s to exist: %v", userPath, err)
+ }
+
+ for _, legacyName := range []string{"AGENTS.md", "IDENTITY.md"} {
+ legacyPath := filepath.Join(targetDir, legacyName)
+ if _, err := os.Stat(legacyPath); !os.IsNotExist(err) {
+ t.Fatalf("expected legacy file %s to be absent, got err=%v", legacyPath, err)
+ }
}
}
diff --git a/cmd/picoclaw/internal/onboard/weixin.go b/cmd/picoclaw/internal/onboard/weixin.go
new file mode 100644
index 00000000..721b4f0e
--- /dev/null
+++ b/cmd/picoclaw/internal/onboard/weixin.go
@@ -0,0 +1,124 @@
+package onboard
+
+import (
+ "context"
+ "fmt"
+ "time"
+
+ "github.com/spf13/cobra"
+
+ "github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+ "github.com/sipeed/picoclaw/pkg/channels/weixin"
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+func newWeixinCommand() *cobra.Command {
+ var baseURL string
+ var proxy string
+ var timeout int
+
+ cmd := &cobra.Command{
+ Use: "weixin",
+ Short: "Connect a WeChat personal account via QR code",
+ Long: `Start the interactive Weixin (WeChat personal) QR code login flow.
+
+A QR code is displayed in the terminal. Scan it with the WeChat mobile app
+to authorize your account. On success, the bot token is saved to the picoclaw
+config so you can start the gateway immediately.
+
+Example:
+ picoclaw onboard weixin`,
+ RunE: func(cmd *cobra.Command, _ []string) error {
+ return runWeixinOnboard(baseURL, proxy, time.Duration(timeout)*time.Second)
+ },
+ }
+
+ cmd.Flags().StringVar(&baseURL, "base-url", "https://ilinkai.weixin.qq.com/", "iLink API base URL")
+ cmd.Flags().StringVar(&proxy, "proxy", "", "HTTP proxy URL (e.g. http://localhost:7890)")
+ cmd.Flags().IntVar(&timeout, "timeout", 300, "Login timeout in seconds")
+
+ return cmd
+}
+
+func runWeixinOnboard(baseURL, proxy string, timeout time.Duration) error {
+ fmt.Println("Starting Weixin (WeChat personal) login...")
+ fmt.Println()
+
+ botToken, userID, accountID, returnedBaseURL, err := weixin.PerformLoginInteractive(
+ context.Background(),
+ weixin.AuthFlowOpts{
+ BaseURL: baseURL,
+ Timeout: timeout,
+ Proxy: proxy,
+ },
+ )
+ if err != nil {
+ return fmt.Errorf("login failed: %w", err)
+ }
+
+ fmt.Println()
+ fmt.Println("✅ Login successful!")
+ fmt.Printf(" Account ID : %s\n", accountID)
+ if userID != "" {
+ fmt.Printf(" User ID : %s\n", userID)
+ }
+ fmt.Println()
+
+ // Prefer the server-returned base URL (may be region-specific)
+ effectiveBaseURL := returnedBaseURL
+ if effectiveBaseURL == "" {
+ effectiveBaseURL = baseURL
+ }
+
+ if err := saveWeixinConfig(botToken, effectiveBaseURL, proxy); err != nil {
+ fmt.Printf("⚠️ Could not auto-save to config: %v\n", err)
+ printManualWeixinConfig(botToken, effectiveBaseURL)
+ return nil
+ }
+
+ fmt.Println("✓ Config updated. Start the gateway with:")
+ fmt.Println()
+ fmt.Println(" picoclaw gateway")
+ fmt.Println()
+ fmt.Println("To restrict which WeChat users can send messages, add their user IDs")
+ fmt.Println("to channels.weixin.allow_from in your config.")
+
+ return nil
+}
+
+// saveWeixinConfig patches channels.weixin in the config and saves it.
+func saveWeixinConfig(token, baseURL, proxy string) error {
+ cfgPath := internal.GetConfigPath()
+
+ cfg, err := config.LoadConfig(cfgPath)
+ if err != nil {
+ return fmt.Errorf("failed to load config: %w", err)
+ }
+
+ cfg.Channels.Weixin.Enabled = true
+ cfg.Channels.Weixin.Token = token
+ const defaultBase = "https://ilinkai.weixin.qq.com/"
+ if baseURL != "" && baseURL != defaultBase {
+ cfg.Channels.Weixin.BaseURL = baseURL
+ }
+ if proxy != "" {
+ cfg.Channels.Weixin.Proxy = proxy
+ }
+
+ return config.SaveConfig(cfgPath, cfg)
+}
+
+func printManualWeixinConfig(token, baseURL string) {
+ fmt.Println()
+ fmt.Println("Add the following to the channels section of your picoclaw config:")
+ fmt.Println()
+ fmt.Println(` "weixin": {`)
+ fmt.Println(` "enabled": true,`)
+ fmt.Printf(" \"token\": %q,\n", token)
+ const defaultBase = "https://ilinkai.weixin.qq.com/"
+ if baseURL != "" && baseURL != defaultBase {
+ fmt.Printf(" \"base_url\": %q,\n", baseURL)
+ }
+ fmt.Println(` "allow_from": []`)
+ fmt.Println(` }`)
+}
diff --git a/config/config.example.json b/config/config.example.json
index 81c9014e..28b29dfa 100644
--- a/config/config.example.json
+++ b/config/config.example.json
@@ -1,10 +1,12 @@
{
"agents": {
"defaults": {
+ "log_level": "fatal",
"workspace": "~/.picoclaw/workspace",
"restrict_to_workspace": true,
"model_name": "gpt-5.4",
"max_tokens": 8192,
+ "context_window": 131072,
"temperature": 0.7,
"max_tool_iterations": 20,
"summarize_message_threshold": 20,
@@ -548,6 +550,14 @@
"voice": {
"echo_transcription": false
},
+ "hooks": {
+ "enabled": true,
+ "defaults": {
+ "observer_timeout_ms": 500,
+ "interceptor_timeout_ms": 5000,
+ "approval_timeout_ms": 60000
+ }
+ },
"gateway": {
"host": "127.0.0.1",
"port": 18790,
diff --git a/docs/agent-refactor/context.md b/docs/agent-refactor/context.md
new file mode 100644
index 00000000..2269d925
--- /dev/null
+++ b/docs/agent-refactor/context.md
@@ -0,0 +1,164 @@
+# Context
+
+## What this document covers
+
+This document makes explicit the boundaries of context management in the agent loop:
+
+- what fills the context window and how space is divided
+- what is stored in session history vs. built at request time
+- when and how context compression happens
+- how token budgets are estimated
+
+These are existing concepts. This document clarifies their boundaries rather than introducing new ones.
+
+---
+
+## Context window regions
+
+The context window is the model's total input capacity. Four regions fill it:
+
+| Region | Assembled by | Stored in session? |
+|---|---|---|
+| System prompt | `BuildMessages()` — static + dynamic parts | No |
+| Summary | `SetSummary()` stores it; `BuildMessages()` injects it | Separate from history |
+| Session history | User / assistant / tool messages | Yes |
+| Tool definitions | Provider adapter injects at call time | No |
+
+`MaxTokens` (the output generation limit) must also be reserved from the total budget.
+
+The available space for history is therefore:
+
+```
+history_budget = ContextWindow - system_prompt - summary - tool_definitions - MaxTokens
+```
+
+---
+
+## ContextWindow vs MaxTokens
+
+These serve different purposes:
+
+- **MaxTokens** — maximum tokens the LLM may generate in one response. Sent as the `max_tokens` request parameter.
+- **ContextWindow** — the model's total input context capacity.
+
+These were previously set to the same value, which caused the summarization threshold to fire either far too early (at the default 32K) or not at all (when a user raised `max_tokens`).
+
+Current default when not explicitly configured: `ContextWindow = MaxTokens * 4`.
+
+---
+
+## Session history
+
+Session history stores only conversation messages:
+
+- `user` — user input
+- `assistant` — LLM response (may include `ToolCalls`)
+- `tool` — tool execution results
+
+Session history does **not** contain:
+
+- System prompts — assembled at request time by `BuildMessages`
+- Summary content — stored separately via `SetSummary`, injected by `BuildMessages`
+
+This distinction matters: any code that operates on session history — compression, boundary detection, token estimation — must not assume a system message is present.
+
+---
+
+## Turn
+
+A **Turn** is one complete cycle:
+
+> user message -> LLM iterations (possibly including tool calls) -> final assistant response
+
+This definition comes from the agent loop design (#1316). In session history, Turn boundaries are identified by `user`-role messages.
+
+Turn is the atomic unit for compression. Cutting inside a Turn can orphan tool-call sequences — an assistant message with `ToolCalls` separated from its corresponding `tool` results. Compressing at Turn boundaries avoids this by construction.
+
+`parseTurnBoundaries(history)` returns the starting index of each Turn.
+`findSafeBoundary(history, targetIndex)` snaps a target cut point to the nearest Turn boundary.
+
+---
+
+## Compression paths
+
+Three compression paths exist, in order of preference:
+
+### 1. Async summarization
+
+`maybeSummarize` runs after each Turn completes.
+
+Triggers when message count exceeds a threshold, or when estimated history tokens exceed a percentage of `ContextWindow`. If triggered, a background goroutine calls the LLM to produce a summary of the oldest messages. The summary is stored via `SetSummary`; `BuildMessages` injects it into the system prompt on the next call.
+
+Cut point uses `findSafeBoundary` so no Turn is split.
+
+### 2. Proactive budget check
+
+`isOverContextBudget` runs before each LLM call.
+
+Uses the full budget formula: `message_tokens + tool_def_tokens + MaxTokens > ContextWindow`. If over budget, triggers `forceCompression` and rebuilds messages before calling the LLM.
+
+This prevents wasted (and billed) LLM calls that would otherwise fail with a context-window error.
+
+### 3. Emergency compression (reactive)
+
+`forceCompression` runs when the LLM returns a context-window error despite the proactive check.
+
+Drops the oldest ~50% of Turns. If the history is a single Turn with no safe split point (e.g. one user message followed by a massive tool response), falls back to keeping only the most recent user message — breaking Turn atomicity as a last resort to avoid a context-exceeded loop.
+
+Stores a compression note in the session summary (not in history messages) so `BuildMessages` can include it in the next system prompt.
+
+This is the fallback for when the token estimate undershoots reality.
+
+---
+
+## Token estimation
+
+Estimation uses a heuristic of ~2.5 characters per token (`chars * 2 / 5`).
+
+`estimateMessageTokens` counts:
+
+- `Content` (rune count, for multibyte correctness)
+- `ReasoningContent` (extended thinking / chain-of-thought)
+- `ToolCalls` — ID, type, function name, arguments
+- `ToolCallID` (tool result metadata)
+- Per-message overhead (role label, JSON structure)
+- `Media` items — flat per-item token estimate, added directly to the final count (not through the character heuristic, since actual cost depends on resolution and provider-specific image tokenization)
+
+`estimateToolDefsTokens` counts tool definition overhead: name, description, JSON schema of parameters.
+
+These are deliberately heuristic. The proactive check handles the common case; the reactive path catches estimation errors.
+
+---
+
+## Interface boundaries
+
+Context budget functions (`parseTurnBoundaries`, `findSafeBoundary`, `estimateMessageTokens`, `isOverContextBudget`) are **pure functions**. They take `[]providers.Message` and integer parameters. They have no dependency on `AgentLoop` or any other runtime struct.
+
+`BuildMessages` is the sole assembler of the final message array sent to the LLM. Budget functions inform compression decisions but do not construct messages.
+
+`forceCompression` and `summarizeSession` mutate session state (history and summary). `BuildMessages` reads that state to construct context. The flow is:
+
+```
+budget check --> compression decision --> mutate session --> BuildMessages reads session --> LLM call
+```
+
+---
+
+## Known gaps
+
+These are recognized limitations in the current implementation, documented here for visibility:
+
+- **Summarization trigger does not use the full budget formula.** `maybeSummarize` compares estimated history tokens against a percentage of `ContextWindow`. It does not account for system prompt size, tool definition overhead, or `MaxTokens` reserve. The proactive check covers the critical path (preventing 400 errors), but the summarization trigger could be aligned with the same budget model for more accurate early compression.
+
+- **Token estimation is heuristic.** It does not account for provider-specific tokenization, exact system prompt size (assembled separately), or variable image token costs. The two-path design (proactive + reactive) is intended to tolerate this imprecision.
+
+- **Reactive retry does not preserve media.** When the reactive path rebuilds context after compression, it currently passes empty values for media references. This is a pre-existing issue in the main loop, not introduced by the budget system.
+
+---
+
+## What this document does not cover
+
+- How `AGENT.md` frontmatter configures context parameters — that is part of the Agent definition work
+- How the context builder assembles context in the new architecture — that is upcoming work
+- How compression events surface through the event system — that is part of the event model (#1316)
+- Subagent context isolation — that is a separate track
diff --git a/docs/channels/weixin/README.md b/docs/channels/weixin/README.md
new file mode 100644
index 00000000..22687fec
--- /dev/null
+++ b/docs/channels/weixin/README.md
@@ -0,0 +1,58 @@
+# 💬 Weixin (WeChat Personal) Channel
+
+PicoClaw supports connecting to your personal WeChat account using the official Tencent iLink API.
+
+## 🚀 Quick Onboarding
+
+The easiest way to set up the Weixin channel is using the interactive onboarding command:
+
+```bash
+picoclaw onboard weixin
+```
+
+This command will:
+1. Request a QR code from the iLink API and display it in your terminal.
+2. Wait for you to scan the QR code with your WeChat mobile app.
+3. Upon approval, automatically save the generated access token to your `~/.picoclaw/config.json`.
+
+After onboarding, you can start the gateway:
+
+```bash
+picoclaw gateway
+```
+
+---
+
+## ⚙️ Configuration
+
+You can also manually configure the filter rules in `config.json` under the `channels.weixin` section.
+
+```json
+{
+ "channels": {
+ "weixin": {
+ "enabled": true,
+ "token": "YOUR_WEIXIN_TOKEN",
+ "allow_from": [
+ "user_id_1",
+ "user_id_2"
+ ],
+ "proxy": ""
+ }
+ }
+}
+```
+
+### Configuration Fields
+
+| Field | Description |
+|---|---|
+| `enabled` | Set to `true` to enable the channel at startup. |
+| `token` | The authentication token obtained via QR login. |
+| `allow_from` | (Optional) List of WeChat User IDs permitted to interact with the bot. If empty, anyone who can send messages to the connected account can trigger the bot. |
+| `proxy` | (Optional) HTTP proxy address (e.g. `http://localhost:7890`) for environments where connection to `ilinkai.weixin.qq.com` is restricted. |
+
+## ⚠️ Important Notes
+
+- **One Account Only**: The iLink token binds to a single session. Starting a new interaction generally invalidates older tokens if another device authorizes.
+- **Message Rate Limits**: To avoid getting your account restricted by WeChat anti-spam systems, avoid loop triggers or high-frequency broadcasts.
diff --git a/docs/channels/weixin/README.zh.md b/docs/channels/weixin/README.zh.md
new file mode 100644
index 00000000..d5e6f0a4
--- /dev/null
+++ b/docs/channels/weixin/README.zh.md
@@ -0,0 +1,58 @@
+# 💬 微信个人号渠道 (Weixin)
+
+PicoClaw 支持使用腾讯官方 iLink API 连接您的个人微信账号。
+
+## 🚀 快速激活
+
+最简单的方法是使用交互式 onboarding 命令进行一键激活：
+
+```bash
+picoclaw onboard weixin
+```
+
+该命令将：
+1. 从 iLink API 获取二维码并在终端中打印。
+2. 等待您使用手机微信 App 扫码。
+3. 扫码确认后，自动将生成的 Access Token 保存至您的 `~/.picoclaw/config.json` 中。
+
+配置完成后，即可启动网关：
+
+```bash
+picoclaw gateway
+```
+
+---
+
+## ⚙️ 配置说明
+
+您也可以在 `config.json` 的 `channels.weixin` 段目下进行手动维护。
+
+```json
+{
+ "channels": {
+ "weixin": {
+ "enabled": true,
+ "token": "YOUR_WEIXIN_TOKEN",
+ "allow_from": [
+ "user_id_1",
+ "user_id_2"
+ ],
+ "proxy": ""
+ }
+ }
+}
+```
+
+### 字段解析
+
+| 字段 | 说明 |
+|---|---|
+| `enabled` | 设置为 `true` 以在启动时激活该频道。 |
+| `token` | 通过扫码获取的认证令牌。 |
+| `allow_from` | (可选) 允许与机器人交互的微信 User ID 列表。如果为空，任何能给此微信号发消息的人都可以触发机器人。 |
+| `proxy` | (可选) HTTP 代理地址（例如 `http://localhost:7890`），适合网络访问受限环境。 |
+
+## ⚠️ 注意事项
+
+- **单端绑定**: iLink 令牌通常与单个会话绑定。在其他地方重新扫码激活可能会导致旧令牌失效。
+- **频率控制**: 为避免触发微信的风控反垃圾机制，请避免设置死循环触发、高频广播等恶意行为。
diff --git a/docs/chat-apps.md b/docs/chat-apps.md
index 3ed37e81..07297952 100644
--- a/docs/chat-apps.md
+++ b/docs/chat-apps.md
@@ -13,6 +13,7 @@ Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk,
| **Telegram** | ⭐ Easy | Recommended, voice-to-text, long polling (no public IP needed) | [Docs](../channels/telegram/README.md) |
| **Discord** | ⭐ Easy | Socket Mode, group/DM support, rich bot ecosystem | [Docs](../channels/discord/README.md) |
| **WhatsApp** | ⭐ Easy | Native (QR scan) or Bridge URL | [Docs](#whatsapp) |
+| **Weixin** | ⭐ Easy | Native QR scan (Tencent iLink API) | [Docs](../channels/weixin/README.md) |
| **Slack** | ⭐ Easy | **Socket Mode** (no public IP needed), enterprise | [Docs](../channels/slack/README.md) |
| **Matrix** | ⭐⭐ Medium | Federated protocol, self-hosting supported | [Docs](../channels/matrix/README.md) |
| **QQ** | ⭐⭐ Medium | Official bot API, Chinese community | [Docs](../channels/qq/README.md) |
@@ -169,6 +170,39 @@ If `session_store_path` is empty, the session is stored in `/whatsapp
+Full config example
+ +```json +{ + "agents": { + "defaults": { + "model": "anthropic/claude-opus-4-5" + } + }, + "session": { + "dm_scope": "per-channel-peer", + "backlog_limit": 20 + }, + "providers": { + "openrouter": { + "api_key": "sk-or-v1-xxx" + }, + "groq": { + "api_key": "gsk_xxx" + } + }, + "channels": { + "telegram": { + "enabled": true, + "token": "123456:ABC...", + "allow_from": ["123456789"] + }, + "discord": { + "enabled": true, + "token": "", + "allow_from": [""] + }, + "whatsapp": { + "enabled": false, + "bridge_url": "ws://localhost:3001", + "use_native": false, + "session_store_path": "", + "allow_from": [] + }, + "feishu": { + "enabled": false, + "app_id": "cli_xxx", + "app_secret": "xxx", + "encrypt_key": "", + "verification_token": "", + "allow_from": [] + }, + "qq": { + "enabled": false, + "app_id": "", + "app_secret": "", + "allow_from": [] + } + }, "tools": { "web": { "brave": { "enabled": false, - "api_key": "YOUR_BRAVE_API_KEY", - "max_results": 5 - }, - "tavily": { - "enabled": false, - "api_key": "YOUR_TAVILY_API_KEY", + "api_key": "BSA...", "max_results": 5 }, "duckduckgo": { @@ -1059,410 +1363,40 @@ picoclaw onboard }, "perplexity": { "enabled": false, - "api_key": "YOUR_PERPLEXITY_API_KEY", + "api_key": "", "max_results": 5 }, "searxng": { "enabled": false, - "base_url": "http://your-searxng-instance:8888", + "base_url": "http://localhost:8888", "max_results": 5 } + }, + "cron": { + "exec_timeout_minutes": 5 } + }, + "heartbeat": { + "enabled": true, + "interval": 30 } } ``` -> **New**: The `model_list` configuration format allows zero-code provider addition. See [Model Configuration](#model-configuration-model_list) for details. -> `request_timeout` is optional and uses seconds. If omitted or set to `<= 0`, PicoClaw uses the default timeout (120s). - -**3. Get API Keys** - -* **LLM Provider**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys) -* **Web Search** (optional): - * [Brave Search](https://brave.com/search/api) - Paid ($5/1000 queries, ~$5-6/month) - * [Perplexity](https://www.perplexity.ai) - AI-powered search with chat interface - * [SearXNG](https://github.com/searxng/searxng) - Self-hosted metasearch engine (free, no API key needed) - * [Tavily](https://tavily.com) - Optimized for AI Agents (1000 requests/month) - * DuckDuckGo - Built-in fallback (no API key required) - -> **Note**: See `config.example.json` for a complete configuration template. - -**4. Chat** - -```bash -picoclaw agent -m "What is 2+2?" -``` - -That's it! You have a working AI assistant in 2 minutes. - ---- - -## 💬 Chat Apps - -Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk, LINE, or WeCom - -> **Note**: All webhook-based channels (LINE, WeCom, etc.) are served on a single shared Gateway HTTP server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). There are no per-channel ports to configure. Note: Feishu uses WebSocket/SDK mode and does not use the shared HTTP webhook server. - -| Channel | Setup | -| ------------ | ---------------------------------- | -| **Telegram** | Easy (just a token) | -| **Discord** | Easy (bot token + intents) | -| **WhatsApp** | Easy (native: QR scan; or bridge URL) | -| **Matrix** | Medium (homeserver + bot access token) | -| **QQ** | Easy (AppID + AppSecret) | -| **DingTalk** | Medium (app credentials) | -| **LINE** | Medium (credentials + webhook URL) | -| **WeCom AI Bot** | Medium (Token + AES key) | - -
-
-
-Telegram (Recommended)
- -**1. Create a bot** - -* Open Telegram, search `@BotFather` -* Send `/newbot`, follow prompts -* Copy the token - -**2. Configure** - -```json -{ - "channels": { - "telegram": { - "enabled": true, - "token": "YOUR_BOT_TOKEN", - "allow_from": ["YOUR_USER_ID"] - } - } -} -``` - -> Get your user ID from `@userinfobot` on Telegram. - -**3. Run** - -```bash -picoclaw gateway -``` - -**4. Telegram command menu (auto-registered at startup)** - -PicoClaw now keeps command definitions in one shared registry. On startup, Telegram will automatically register supported bot commands (for example `/start`, `/help`, `/show`, `/list`) so command menu and runtime behavior stay in sync. -Telegram command menu registration remains channel-local discovery UX; generic command execution is handled centrally in the agent loop via the commands executor. - -If command registration fails (network/API transient errors), the channel still starts and PicoClaw retries registration in the background. - -
-
-* Create an application → Bot → Add Bot
-* Copy the bot token
-
-**2. Enable intents**
-
-* In the Bot settings, enable **MESSAGE CONTENT INTENT**
-* (Optional) Enable **SERVER MEMBERS INTENT** if you plan to use allow lists based on member data
-
-**3. Get your User ID**
-* Discord Settings → Advanced → enable **Developer Mode**
-* Right-click your avatar → **Copy User ID**
-
-**4. Configure**
-
-```json
-{
- "channels": {
- "discord": {
- "enabled": true,
- "token": "YOUR_BOT_TOKEN",
- "allow_from": ["YOUR_USER_ID"]
- }
- }
-}
-```
-
-**5. Invite the bot**
-
-* OAuth2 → URL Generator
-* Scopes: `bot`
-* Bot Permissions: `Send Messages`, `Read Message History`
-* Open the generated invite URL and add the bot to your server
-
-**Optional: Group trigger mode**
-
-By default the bot responds to all messages in a server channel. To restrict responses to @-mentions only, add:
-
-```json
-{
- "channels": {
- "discord": {
- "group_trigger": { "mention_only": true }
- }
- }
-}
-```
-
-You can also trigger by keyword prefixes (e.g. `!bot`):
-
-```json
-{
- "channels": {
- "discord": {
- "group_trigger": { "prefixes": ["!bot"] }
- }
- }
-}
-```
-
-**6. Run**
-
-```bash
-picoclaw gateway
-```
-
-Discord
- -**1. Create a bot** - -* Go to
-
-
-WhatsApp (native via whatsmeow)
- -PicoClaw can connect to WhatsApp in two ways: - -- **Native (recommended):** In-process using [whatsmeow](https://github.com/tulir/whatsmeow). No separate bridge. Set `"use_native": true` and leave `bridge_url` empty. On first run, scan the QR code with WhatsApp (Linked Devices). Session is stored under your workspace (e.g. `workspace/whatsapp/`). The native channel is **optional** to keep the default binary small; build with `-tags whatsapp_native` (e.g. `make build-whatsapp-native` or `go build -tags whatsapp_native ./cmd/...`). -- **Bridge:** Connect to an external WebSocket bridge. Set `bridge_url` (e.g. `ws://localhost:3001`) and keep `use_native` false. - -**Configure (native)** - -```json -{ - "channels": { - "whatsapp": { - "enabled": true, - "use_native": true, - "session_store_path": "", - "allow_from": [] - } - } -} -``` - -If `session_store_path` is empty, the session is stored in `<workspace>/whatsapp/`. Run `picoclaw gateway`; on first run, scan the QR code printed in the terminal with WhatsApp → Linked Devices. - -
-QQ
- -**1. Create a bot** - -- Go to [QQ Open Platform](https://q.qq.com/#) -- Create an application → Get **AppID** and **AppSecret** - -**2. Configure** - -```json -{ - "channels": { - "qq": { - "enabled": true, - "app_id": "YOUR_APP_ID", - "app_secret": "YOUR_APP_SECRET", - "allow_from": [] - } - } -} -``` - -> Set `allow_from` to empty to allow all users, or specify QQ numbers to restrict access. - -**3. Run** - -```bash -picoclaw gateway -``` - -
-
-
-
-
-DingTalk
- -**1. Create a bot** - -* Go to [Open Platform](https://open.dingtalk.com/) -* Create an internal app -* Copy Client ID and Client Secret - -**2. Configure** - -```json -{ - "channels": { - "dingtalk": { - "enabled": true, - "client_id": "YOUR_CLIENT_ID", - "client_secret": "YOUR_CLIENT_SECRET", - "allow_from": [] - } - } -} -``` - -> Set `allow_from` to empty to allow all users, or specify DingTalk user IDs to restrict access. - -**3. Run** - -```bash -picoclaw gateway -``` -
-
-
-Matrix
- -**1. Prepare bot account** - -* Use your preferred homeserver (e.g. `https://matrix.org` or self-hosted) -* Create a bot user and obtain its access token - -**2. Configure** - -```json -{ - "channels": { - "matrix": { - "enabled": true, - "homeserver": "https://matrix.org", - "user_id": "@your-bot:matrix.org", - "access_token": "YOUR_MATRIX_ACCESS_TOKEN", - "allow_from": [] - } - } -} -``` - -**3. Run** - -```bash -picoclaw gateway -``` - -For full options (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`, `reasoning_channel_id`), see [Matrix Channel Configuration Guide](docs/channels/matrix/README.md). - -
-
-
-LINE
- -**1. Create a LINE Official Account** - -- Go to [LINE Developers Console](https://developers.line.biz/) -- Create a provider → Create a Messaging API channel -- Copy **Channel Secret** and **Channel Access Token** - -**2. Configure** - -```json -{ - "channels": { - "line": { - "enabled": true, - "channel_secret": "YOUR_CHANNEL_SECRET", - "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN", - "webhook_path": "/webhook/line", - "allow_from": [] - } - } -} -``` - -> LINE webhook is served on the shared Gateway server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). - -**3. Set up Webhook URL** - -LINE requires HTTPS for webhooks. Use a reverse proxy or tunnel: - -```bash -# Example with ngrok (gateway default port is 18790) -ngrok http 18790 -``` - -Then set the Webhook URL in LINE Developers Console to `https://your-domain/webhook/line` and enable **Use webhook**. - -**4. Run** - -```bash -picoclaw gateway -``` - -> In group chats, the bot responds only when @mentioned. Replies quote the original message. - -
-
-
-## WeCom (企业微信)
- -PicoClaw supports three types of WeCom integration: - -**Option 1: WeCom Bot (Bot)** - Easier setup, supports group chats -**Option 2: WeCom App (Custom App)** - More features, proactive messaging, private chat only -**Option 3: WeCom AI Bot (AI Bot)** - Official AI Bot, streaming replies, supports group & private chat - -See [WeCom AI Bot Configuration Guide](docs/channels/wecom/wecom_aibot/README.zh.md) for detailed setup instructions. - -**Quick Setup - WeCom AI Bot:** - -**1. Create an AI Bot** - -* Go to WeCom Admin Console → AI Bot -* Create a new AI Bot → Set name, avatar, etc. -* Copy **Bot ID** and **Secret** - -**2. Configure** - -```json -{ - "channels": { - "wecom_aibot": { - "enabled": true, - "bot_id": "YOUR_BOT_ID", - "secret": "YOUR_SECRET", - "allow_from": [], - "welcome_message": "Hello! How can I help you?" - } - } -} -``` - -**3. Run** - -```bash -picoclaw gateway -``` - -> **Note**: WeCom AI Bot uses streaming pull protocol — no reply timeout concerns. Long tasks (>30 seconds) automatically switch to `response_url` push delivery. - - Join the Agent Social Network
-
-Connect Picoclaw to the Agent Social Network simply by sending a single message via the CLI or any integrated Chat App.
-
-**Read `https://clawdchat.ai/skill.md` and follow the instructions to join [ClawdChat.ai](https://clawdchat.ai)**
-
## 🖥️ CLI Reference
| Command | Description |
| ------------------------- | ----------------------------- |
| `picoclaw onboard` | Initialize config & workspace |
+| `picoclaw onboard weixin` | Connect WeChat account via QR |
| `picoclaw agent -m "..."` | Chat with the agent |
| `picoclaw agent` | Interactive chat mode |
| `picoclaw gateway` | Start the gateway |
| `picoclaw status` | Show status |
| `picoclaw version` | Show version info |
+| `picoclaw model` | Show or change default model |
| `picoclaw cron list` | List all scheduled jobs |
| `picoclaw cron add ...` | Add a scheduled job |
| `picoclaw cron disable` | Disable a scheduled job |
@@ -1492,52 +1426,5 @@ User Groups:
discord:
-
-## Join the Agent Social Network
-
-Connect Picoclaw to the Agent Social Network simply by sending a single message via the CLI or any integrated Chat App.
-
-**Read `https://clawdchat.ai/skill.md` and follow the instructions to join [ClawdChat.ai](https://clawdchat.ai)**
-
-## 🖥️ CLI Reference
-
-| Command | Description |
-| ------------------------- | ----------------------------- |
-| `picoclaw onboard` | Initialize config & workspace |
-| `picoclaw agent -m "..."` | Chat with the agent |
-| `picoclaw agent` | Interactive chat mode |
-| `picoclaw gateway` | Start the gateway |
-| `picoclaw status` | Show status |
-| `picoclaw version` | Show version info |
-| `picoclaw cron list` | List all scheduled jobs |
-| `picoclaw cron add ...` | Add a scheduled job |
-| `picoclaw cron disable` | Disable a scheduled job |
-| `picoclaw cron remove` | Remove a scheduled job |
-| `picoclaw skills list` | List installed skills |
-| `picoclaw skills install` | Install a skill |
-| `picoclaw migrate` | Migrate data from older versions |
-| `picoclaw auth login` | Authenticate with providers |
-| `picoclaw model` | View or switch the default model |
-
-### Scheduled Tasks / Reminders
-
-PicoClaw supports scheduled reminders and recurring tasks through the `cron` tool:
-
-* **One-time reminders**: "Remind me in 10 minutes" → triggers once after 10min
-* **Recurring tasks**: "Remind me every 2 hours" → triggers every 2 hours
-* **Cron expressions**: "Remind me at 9am daily" → uses cron expression
-
-## 🤝 Contribute & Roadmap
-
-PRs welcome! The codebase is intentionally small and readable. 🤗
-
-See our full [Community Roadmap](https://github.com/sipeed/picoclaw/blob/main/ROADMAP.md).
-
-Developer group building, join after your first merged PR!
-
-User Groups:
-
-discord:
+WeChat:
+
diff --git a/README.zh.md b/README.zh.md
index db34f57d..1bc5d1a4 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -218,6 +218,7 @@ make install
| 命令 | 说明 |
| ------------------------- | ---------------------- |
| `picoclaw onboard` | 初始化配置与工作区 |
+| `picoclaw onboard weixin` | 扫码连接微信个人号 |
| `picoclaw agent -m "..."` | 与 Agent 对话 |
| `picoclaw agent` | 交互式对话模式 |
| `picoclaw gateway` | 启动网关 |
diff --git a/assets/wechat.png b/assets/wechat.png
index 6512421e..effb4dab 100644
Binary files a/assets/wechat.png and b/assets/wechat.png differ
diff --git a/cmd/picoclaw/internal/agent/helpers.go b/cmd/picoclaw/internal/agent/helpers.go
index c3ddbb77..0af743bb 100644
--- a/cmd/picoclaw/internal/agent/helpers.go
+++ b/cmd/picoclaw/internal/agent/helpers.go
@@ -23,16 +23,16 @@ func agentCmd(message, sessionKey, model string, debug bool) error {
sessionKey = "cli:default"
}
- if debug {
- logger.SetLevel(logger.DEBUG)
- fmt.Println("🔍 Debug mode enabled")
- }
-
cfg, err := internal.LoadConfig()
if err != nil {
return fmt.Errorf("error loading config: %w", err)
}
+ if debug {
+ logger.SetLevel(logger.DEBUG)
+ fmt.Println("🔍 Debug mode enabled")
+ }
+
if model != "" {
cfg.Agents.Defaults.ModelName = model
}
diff --git a/cmd/picoclaw/internal/helpers.go b/cmd/picoclaw/internal/helpers.go
index 6b2d65c9..ae1d58c2 100644
--- a/cmd/picoclaw/internal/helpers.go
+++ b/cmd/picoclaw/internal/helpers.go
@@ -5,6 +5,7 @@ import (
"path/filepath"
"github.com/sipeed/picoclaw/pkg/config"
+ "github.com/sipeed/picoclaw/pkg/logger"
)
const Logo = "🦞"
@@ -27,7 +28,12 @@ func GetConfigPath() string {
}
func LoadConfig() (*config.Config, error) {
- return config.LoadConfig(GetConfigPath())
+ cfg, err := config.LoadConfig(GetConfigPath())
+ if err != nil {
+ return nil, err
+ }
+ logger.SetLevelFromString(cfg.Agents.Defaults.LogLevel)
+ return cfg, nil
}
// FormatVersion returns the version string with optional git commit
diff --git a/cmd/picoclaw/internal/onboard/command.go b/cmd/picoclaw/internal/onboard/command.go
index 9f8b288c..1f94c671 100644
--- a/cmd/picoclaw/internal/onboard/command.go
+++ b/cmd/picoclaw/internal/onboard/command.go
@@ -16,14 +16,22 @@ func NewOnboardCommand() *cobra.Command {
cmd := &cobra.Command{
Use: "onboard",
Aliases: []string{"o"},
- Short: "Initialize picoclaw configuration and workspace",
+ Short: "Initialize picoclaw configuration, workspace, and channel accounts",
+ // Run without subcommands → original onboard flow
Run: func(cmd *cobra.Command, args []string) {
- onboard(encrypt)
+ if len(args) == 0 {
+ onboard(encrypt)
+ } else {
+ _ = cmd.Help()
+ }
},
}
cmd.Flags().BoolVar(&encrypt, "enc", false,
"Enable credential encryption (generates SSH key and prompts for passphrase)")
+ // Channel onboarding subcommands
+ cmd.AddCommand(newWeixinCommand())
+
return cmd
}
diff --git a/cmd/picoclaw/internal/onboard/command_test.go b/cmd/picoclaw/internal/onboard/command_test.go
index 56936190..6b9fb6e9 100644
--- a/cmd/picoclaw/internal/onboard/command_test.go
+++ b/cmd/picoclaw/internal/onboard/command_test.go
@@ -13,7 +13,7 @@ func TestNewOnboardCommand(t *testing.T) {
require.NotNil(t, cmd)
assert.Equal(t, "onboard", cmd.Use)
- assert.Equal(t, "Initialize picoclaw configuration and workspace", cmd.Short)
+ assert.Equal(t, "Initialize picoclaw configuration, workspace, and channel accounts", cmd.Short)
assert.Len(t, cmd.Aliases, 1)
assert.True(t, cmd.HasAlias("o"))
@@ -28,5 +28,6 @@ func TestNewOnboardCommand(t *testing.T) {
encFlag := cmd.Flags().Lookup("enc")
require.NotNil(t, encFlag, "expected --enc flag to be registered")
assert.Equal(t, "false", encFlag.DefValue, "--enc should default to false")
- assert.False(t, cmd.HasSubCommands())
+ assert.True(t, cmd.HasSubCommands())
+ assert.NotNil(t, cmd.Commands())
}
diff --git a/cmd/picoclaw/internal/onboard/helpers_test.go b/cmd/picoclaw/internal/onboard/helpers_test.go
index f3e0c92e..23fc97c5 100644
--- a/cmd/picoclaw/internal/onboard/helpers_test.go
+++ b/cmd/picoclaw/internal/onboard/helpers_test.go
@@ -6,20 +6,32 @@ import (
"testing"
)
-func TestCopyEmbeddedToTargetUsesAgentsMarkdown(t *testing.T) {
+func TestCopyEmbeddedToTargetUsesStructuredAgentFiles(t *testing.T) {
targetDir := t.TempDir()
if err := copyEmbeddedToTarget(targetDir); err != nil {
t.Fatalf("copyEmbeddedToTarget() error = %v", err)
}
- agentsPath := filepath.Join(targetDir, "AGENTS.md")
- if _, err := os.Stat(agentsPath); err != nil {
- t.Fatalf("expected %s to exist: %v", agentsPath, err)
+ agentPath := filepath.Join(targetDir, "AGENT.md")
+ if _, err := os.Stat(agentPath); err != nil {
+ t.Fatalf("expected %s to exist: %v", agentPath, err)
}
- legacyPath := filepath.Join(targetDir, "AGENT.md")
- if _, err := os.Stat(legacyPath); !os.IsNotExist(err) {
- t.Fatalf("expected legacy file %s to be absent, got err=%v", legacyPath, err)
+ soulPath := filepath.Join(targetDir, "SOUL.md")
+ if _, err := os.Stat(soulPath); err != nil {
+ t.Fatalf("expected %s to exist: %v", soulPath, err)
+ }
+
+ userPath := filepath.Join(targetDir, "USER.md")
+ if _, err := os.Stat(userPath); err != nil {
+ t.Fatalf("expected %s to exist: %v", userPath, err)
+ }
+
+ for _, legacyName := range []string{"AGENTS.md", "IDENTITY.md"} {
+ legacyPath := filepath.Join(targetDir, legacyName)
+ if _, err := os.Stat(legacyPath); !os.IsNotExist(err) {
+ t.Fatalf("expected legacy file %s to be absent, got err=%v", legacyPath, err)
+ }
}
}
diff --git a/cmd/picoclaw/internal/onboard/weixin.go b/cmd/picoclaw/internal/onboard/weixin.go
new file mode 100644
index 00000000..721b4f0e
--- /dev/null
+++ b/cmd/picoclaw/internal/onboard/weixin.go
@@ -0,0 +1,124 @@
+package onboard
+
+import (
+ "context"
+ "fmt"
+ "time"
+
+ "github.com/spf13/cobra"
+
+ "github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+ "github.com/sipeed/picoclaw/pkg/channels/weixin"
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+func newWeixinCommand() *cobra.Command {
+ var baseURL string
+ var proxy string
+ var timeout int
+
+ cmd := &cobra.Command{
+ Use: "weixin",
+ Short: "Connect a WeChat personal account via QR code",
+ Long: `Start the interactive Weixin (WeChat personal) QR code login flow.
+
+A QR code is displayed in the terminal. Scan it with the WeChat mobile app
+to authorize your account. On success, the bot token is saved to the picoclaw
+config so you can start the gateway immediately.
+
+Example:
+ picoclaw onboard weixin`,
+ RunE: func(cmd *cobra.Command, _ []string) error {
+ return runWeixinOnboard(baseURL, proxy, time.Duration(timeout)*time.Second)
+ },
+ }
+
+ cmd.Flags().StringVar(&baseURL, "base-url", "https://ilinkai.weixin.qq.com/", "iLink API base URL")
+ cmd.Flags().StringVar(&proxy, "proxy", "", "HTTP proxy URL (e.g. http://localhost:7890)")
+ cmd.Flags().IntVar(&timeout, "timeout", 300, "Login timeout in seconds")
+
+ return cmd
+}
+
+func runWeixinOnboard(baseURL, proxy string, timeout time.Duration) error {
+ fmt.Println("Starting Weixin (WeChat personal) login...")
+ fmt.Println()
+
+ botToken, userID, accountID, returnedBaseURL, err := weixin.PerformLoginInteractive(
+ context.Background(),
+ weixin.AuthFlowOpts{
+ BaseURL: baseURL,
+ Timeout: timeout,
+ Proxy: proxy,
+ },
+ )
+ if err != nil {
+ return fmt.Errorf("login failed: %w", err)
+ }
+
+ fmt.Println()
+ fmt.Println("✅ Login successful!")
+ fmt.Printf(" Account ID : %s\n", accountID)
+ if userID != "" {
+ fmt.Printf(" User ID : %s\n", userID)
+ }
+ fmt.Println()
+
+ // Prefer the server-returned base URL (may be region-specific)
+ effectiveBaseURL := returnedBaseURL
+ if effectiveBaseURL == "" {
+ effectiveBaseURL = baseURL
+ }
+
+ if err := saveWeixinConfig(botToken, effectiveBaseURL, proxy); err != nil {
+ fmt.Printf("⚠️ Could not auto-save to config: %v\n", err)
+ printManualWeixinConfig(botToken, effectiveBaseURL)
+ return nil
+ }
+
+ fmt.Println("✓ Config updated. Start the gateway with:")
+ fmt.Println()
+ fmt.Println(" picoclaw gateway")
+ fmt.Println()
+ fmt.Println("To restrict which WeChat users can send messages, add their user IDs")
+ fmt.Println("to channels.weixin.allow_from in your config.")
+
+ return nil
+}
+
+// saveWeixinConfig patches channels.weixin in the config and saves it.
+func saveWeixinConfig(token, baseURL, proxy string) error {
+ cfgPath := internal.GetConfigPath()
+
+ cfg, err := config.LoadConfig(cfgPath)
+ if err != nil {
+ return fmt.Errorf("failed to load config: %w", err)
+ }
+
+ cfg.Channels.Weixin.Enabled = true
+ cfg.Channels.Weixin.Token = token
+ const defaultBase = "https://ilinkai.weixin.qq.com/"
+ if baseURL != "" && baseURL != defaultBase {
+ cfg.Channels.Weixin.BaseURL = baseURL
+ }
+ if proxy != "" {
+ cfg.Channels.Weixin.Proxy = proxy
+ }
+
+ return config.SaveConfig(cfgPath, cfg)
+}
+
+func printManualWeixinConfig(token, baseURL string) {
+ fmt.Println()
+ fmt.Println("Add the following to the channels section of your picoclaw config:")
+ fmt.Println()
+ fmt.Println(` "weixin": {`)
+ fmt.Println(` "enabled": true,`)
+ fmt.Printf(" \"token\": %q,\n", token)
+ const defaultBase = "https://ilinkai.weixin.qq.com/"
+ if baseURL != "" && baseURL != defaultBase {
+ fmt.Printf(" \"base_url\": %q,\n", baseURL)
+ }
+ fmt.Println(` "allow_from": []`)
+ fmt.Println(` }`)
+}
diff --git a/config/config.example.json b/config/config.example.json
index 81c9014e..28b29dfa 100644
--- a/config/config.example.json
+++ b/config/config.example.json
@@ -1,10 +1,12 @@
{
"agents": {
"defaults": {
+ "log_level": "fatal",
"workspace": "~/.picoclaw/workspace",
"restrict_to_workspace": true,
"model_name": "gpt-5.4",
"max_tokens": 8192,
+ "context_window": 131072,
"temperature": 0.7,
"max_tool_iterations": 20,
"summarize_message_threshold": 20,
@@ -548,6 +550,14 @@
"voice": {
"echo_transcription": false
},
+ "hooks": {
+ "enabled": true,
+ "defaults": {
+ "observer_timeout_ms": 500,
+ "interceptor_timeout_ms": 5000,
+ "approval_timeout_ms": 60000
+ }
+ },
"gateway": {
"host": "127.0.0.1",
"port": 18790,
diff --git a/docs/agent-refactor/context.md b/docs/agent-refactor/context.md
new file mode 100644
index 00000000..2269d925
--- /dev/null
+++ b/docs/agent-refactor/context.md
@@ -0,0 +1,164 @@
+# Context
+
+## What this document covers
+
+This document makes explicit the boundaries of context management in the agent loop:
+
+- what fills the context window and how space is divided
+- what is stored in session history vs. built at request time
+- when and how context compression happens
+- how token budgets are estimated
+
+These are existing concepts. This document clarifies their boundaries rather than introducing new ones.
+
+---
+
+## Context window regions
+
+The context window is the model's total input capacity. Four regions fill it:
+
+| Region | Assembled by | Stored in session? |
+|---|---|---|
+| System prompt | `BuildMessages()` — static + dynamic parts | No |
+| Summary | `SetSummary()` stores it; `BuildMessages()` injects it | Separate from history |
+| Session history | User / assistant / tool messages | Yes |
+| Tool definitions | Provider adapter injects at call time | No |
+
+`MaxTokens` (the output generation limit) must also be reserved from the total budget.
+
+The available space for history is therefore:
+
+```
+history_budget = ContextWindow - system_prompt - summary - tool_definitions - MaxTokens
+```
+
+---
+
+## ContextWindow vs MaxTokens
+
+These serve different purposes:
+
+- **MaxTokens** — maximum tokens the LLM may generate in one response. Sent as the `max_tokens` request parameter.
+- **ContextWindow** — the model's total input context capacity.
+
+These were previously set to the same value, which caused the summarization threshold to fire either far too early (at the default 32K) or not at all (when a user raised `max_tokens`).
+
+Current default when not explicitly configured: `ContextWindow = MaxTokens * 4`.
+
+---
+
+## Session history
+
+Session history stores only conversation messages:
+
+- `user` — user input
+- `assistant` — LLM response (may include `ToolCalls`)
+- `tool` — tool execution results
+
+Session history does **not** contain:
+
+- System prompts — assembled at request time by `BuildMessages`
+- Summary content — stored separately via `SetSummary`, injected by `BuildMessages`
+
+This distinction matters: any code that operates on session history — compression, boundary detection, token estimation — must not assume a system message is present.
+
+---
+
+## Turn
+
+A **Turn** is one complete cycle:
+
+> user message -> LLM iterations (possibly including tool calls) -> final assistant response
+
+This definition comes from the agent loop design (#1316). In session history, Turn boundaries are identified by `user`-role messages.
+
+Turn is the atomic unit for compression. Cutting inside a Turn can orphan tool-call sequences — an assistant message with `ToolCalls` separated from its corresponding `tool` results. Compressing at Turn boundaries avoids this by construction.
+
+`parseTurnBoundaries(history)` returns the starting index of each Turn.
+`findSafeBoundary(history, targetIndex)` snaps a target cut point to the nearest Turn boundary.
+
+---
+
+## Compression paths
+
+Three compression paths exist, in order of preference:
+
+### 1. Async summarization
+
+`maybeSummarize` runs after each Turn completes.
+
+Triggers when message count exceeds a threshold, or when estimated history tokens exceed a percentage of `ContextWindow`. If triggered, a background goroutine calls the LLM to produce a summary of the oldest messages. The summary is stored via `SetSummary`; `BuildMessages` injects it into the system prompt on the next call.
+
+Cut point uses `findSafeBoundary` so no Turn is split.
+
+### 2. Proactive budget check
+
+`isOverContextBudget` runs before each LLM call.
+
+Uses the full budget formula: `message_tokens + tool_def_tokens + MaxTokens > ContextWindow`. If over budget, triggers `forceCompression` and rebuilds messages before calling the LLM.
+
+This prevents wasted (and billed) LLM calls that would otherwise fail with a context-window error.
+
+### 3. Emergency compression (reactive)
+
+`forceCompression` runs when the LLM returns a context-window error despite the proactive check.
+
+Drops the oldest ~50% of Turns. If the history is a single Turn with no safe split point (e.g. one user message followed by a massive tool response), falls back to keeping only the most recent user message — breaking Turn atomicity as a last resort to avoid a context-exceeded loop.
+
+Stores a compression note in the session summary (not in history messages) so `BuildMessages` can include it in the next system prompt.
+
+This is the fallback for when the token estimate undershoots reality.
+
+---
+
+## Token estimation
+
+Estimation uses a heuristic of ~2.5 characters per token (`chars * 2 / 5`).
+
+`estimateMessageTokens` counts:
+
+- `Content` (rune count, for multibyte correctness)
+- `ReasoningContent` (extended thinking / chain-of-thought)
+- `ToolCalls` — ID, type, function name, arguments
+- `ToolCallID` (tool result metadata)
+- Per-message overhead (role label, JSON structure)
+- `Media` items — flat per-item token estimate, added directly to the final count (not through the character heuristic, since actual cost depends on resolution and provider-specific image tokenization)
+
+`estimateToolDefsTokens` counts tool definition overhead: name, description, JSON schema of parameters.
+
+These are deliberately heuristic. The proactive check handles the common case; the reactive path catches estimation errors.
+
+---
+
+## Interface boundaries
+
+Context budget functions (`parseTurnBoundaries`, `findSafeBoundary`, `estimateMessageTokens`, `isOverContextBudget`) are **pure functions**. They take `[]providers.Message` and integer parameters. They have no dependency on `AgentLoop` or any other runtime struct.
+
+`BuildMessages` is the sole assembler of the final message array sent to the LLM. Budget functions inform compression decisions but do not construct messages.
+
+`forceCompression` and `summarizeSession` mutate session state (history and summary). `BuildMessages` reads that state to construct context. The flow is:
+
+```
+budget check --> compression decision --> mutate session --> BuildMessages reads session --> LLM call
+```
+
+---
+
+## Known gaps
+
+These are recognized limitations in the current implementation, documented here for visibility:
+
+- **Summarization trigger does not use the full budget formula.** `maybeSummarize` compares estimated history tokens against a percentage of `ContextWindow`. It does not account for system prompt size, tool definition overhead, or `MaxTokens` reserve. The proactive check covers the critical path (preventing 400 errors), but the summarization trigger could be aligned with the same budget model for more accurate early compression.
+
+- **Token estimation is heuristic.** It does not account for provider-specific tokenization, exact system prompt size (assembled separately), or variable image token costs. The two-path design (proactive + reactive) is intended to tolerate this imprecision.
+
+- **Reactive retry does not preserve media.** When the reactive path rebuilds context after compression, it currently passes empty values for media references. This is a pre-existing issue in the main loop, not introduced by the budget system.
+
+---
+
+## What this document does not cover
+
+- How `AGENT.md` frontmatter configures context parameters — that is part of the Agent definition work
+- How the context builder assembles context in the new architecture — that is upcoming work
+- How compression events surface through the event system — that is part of the event model (#1316)
+- Subagent context isolation — that is a separate track
diff --git a/docs/channels/weixin/README.md b/docs/channels/weixin/README.md
new file mode 100644
index 00000000..22687fec
--- /dev/null
+++ b/docs/channels/weixin/README.md
@@ -0,0 +1,58 @@
+# 💬 Weixin (WeChat Personal) Channel
+
+PicoClaw supports connecting to your personal WeChat account using the official Tencent iLink API.
+
+## 🚀 Quick Onboarding
+
+The easiest way to set up the Weixin channel is using the interactive onboarding command:
+
+```bash
+picoclaw onboard weixin
+```
+
+This command will:
+1. Request a QR code from the iLink API and display it in your terminal.
+2. Wait for you to scan the QR code with your WeChat mobile app.
+3. Upon approval, automatically save the generated access token to your `~/.picoclaw/config.json`.
+
+After onboarding, you can start the gateway:
+
+```bash
+picoclaw gateway
+```
+
+---
+
+## ⚙️ Configuration
+
+You can also manually configure the filter rules in `config.json` under the `channels.weixin` section.
+
+```json
+{
+ "channels": {
+ "weixin": {
+ "enabled": true,
+ "token": "YOUR_WEIXIN_TOKEN",
+ "allow_from": [
+ "user_id_1",
+ "user_id_2"
+ ],
+ "proxy": ""
+ }
+ }
+}
+```
+
+### Configuration Fields
+
+| Field | Description |
+|---|---|
+| `enabled` | Set to `true` to enable the channel at startup. |
+| `token` | The authentication token obtained via QR login. |
+| `allow_from` | (Optional) List of WeChat User IDs permitted to interact with the bot. If empty, anyone who can send messages to the connected account can trigger the bot. |
+| `proxy` | (Optional) HTTP proxy address (e.g. `http://localhost:7890`) for environments where connection to `ilinkai.weixin.qq.com` is restricted. |
+
+## ⚠️ Important Notes
+
+- **One Account Only**: The iLink token binds to a single session. Starting a new interaction generally invalidates older tokens if another device authorizes.
+- **Message Rate Limits**: To avoid getting your account restricted by WeChat anti-spam systems, avoid loop triggers or high-frequency broadcasts.
diff --git a/docs/channels/weixin/README.zh.md b/docs/channels/weixin/README.zh.md
new file mode 100644
index 00000000..d5e6f0a4
--- /dev/null
+++ b/docs/channels/weixin/README.zh.md
@@ -0,0 +1,58 @@
+# 💬 微信个人号渠道 (Weixin)
+
+PicoClaw 支持使用腾讯官方 iLink API 连接您的个人微信账号。
+
+## 🚀 快速激活
+
+最简单的方法是使用交互式 onboarding 命令进行一键激活：
+
+```bash
+picoclaw onboard weixin
+```
+
+该命令将：
+1. 从 iLink API 获取二维码并在终端中打印。
+2. 等待您使用手机微信 App 扫码。
+3. 扫码确认后，自动将生成的 Access Token 保存至您的 `~/.picoclaw/config.json` 中。
+
+配置完成后，即可启动网关：
+
+```bash
+picoclaw gateway
+```
+
+---
+
+## ⚙️ 配置说明
+
+您也可以在 `config.json` 的 `channels.weixin` 段目下进行手动维护。
+
+```json
+{
+ "channels": {
+ "weixin": {
+ "enabled": true,
+ "token": "YOUR_WEIXIN_TOKEN",
+ "allow_from": [
+ "user_id_1",
+ "user_id_2"
+ ],
+ "proxy": ""
+ }
+ }
+}
+```
+
+### 字段解析
+
+| 字段 | 说明 |
+|---|---|
+| `enabled` | 设置为 `true` 以在启动时激活该频道。 |
+| `token` | 通过扫码获取的认证令牌。 |
+| `allow_from` | (可选) 允许与机器人交互的微信 User ID 列表。如果为空，任何能给此微信号发消息的人都可以触发机器人。 |
+| `proxy` | (可选) HTTP 代理地址（例如 `http://localhost:7890`），适合网络访问受限环境。 |
+
+## ⚠️ 注意事项
+
+- **单端绑定**: iLink 令牌通常与单个会话绑定。在其他地方重新扫码激活可能会导致旧令牌失效。
+- **频率控制**: 为避免触发微信的风控反垃圾机制，请避免设置死循环触发、高频广播等恶意行为。
diff --git a/docs/chat-apps.md b/docs/chat-apps.md
index 3ed37e81..07297952 100644
--- a/docs/chat-apps.md
+++ b/docs/chat-apps.md
@@ -13,6 +13,7 @@ Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk,
| **Telegram** | ⭐ Easy | Recommended, voice-to-text, long polling (no public IP needed) | [Docs](../channels/telegram/README.md) |
| **Discord** | ⭐ Easy | Socket Mode, group/DM support, rich bot ecosystem | [Docs](../channels/discord/README.md) |
| **WhatsApp** | ⭐ Easy | Native (QR scan) or Bridge URL | [Docs](#whatsapp) |
+| **Weixin** | ⭐ Easy | Native QR scan (Tencent iLink API) | [Docs](../channels/weixin/README.md) |
| **Slack** | ⭐ Easy | **Socket Mode** (no public IP needed), enterprise | [Docs](../channels/slack/README.md) |
| **Matrix** | ⭐⭐ Medium | Federated protocol, self-hosting supported | [Docs](../channels/matrix/README.md) |
| **QQ** | ⭐⭐ Medium | Official bot API, Chinese community | [Docs](../channels/qq/README.md) |
@@ -169,6 +170,39 @@ If `session_store_path` is empty, the session is stored in `
+
+
Weixin (WeChat Personal)
+ +PicoClaw supports connecting to your personal WeChat account using the official Tencent iLink API. + +**1. Login** +Run the interactive QR login flow: +```bash +picoclaw onboard weixin +``` +Scan the printed QR code with your WeChat mobile app. On success, the token is saved to your config. + +**2. Configure** +(Optional) Update `allow_from` with your WeChat User ID to restrict who can message the bot: +```json +{ + "channels": { + "weixin": { + "enabled": true, + "token": "YOUR_TOKEN", + "allow_from": ["YOUR_USER_ID"] + } + } +} +``` + +**3. Run** +```bash +picoclaw gateway +``` + +[initial poll] + AgentLoop-->>runLLMIteration: [] (empty, or messages) + + alt pendingMessages not empty + runLLMIteration->>runLLMIteration: inject into messages[]
save to session + end + + runLLMIteration->>LLM: Chat(messages, tools) + LLM-->>runLLMIteration: response with toolCalls[0..N] + + loop for each tool call (sequential) + ToolExecution->>ToolExecution: execute tool[i] + ToolExecution->>ToolExecution: process result,
append to messages[] + + ToolExecution->>AgentLoop: dequeueSteeringMessages() + AgentLoop-->>ToolExecution: steeringMessages + + alt steering found + opt remaining tools > 0 + Note over ToolExecution: Mark tool[i+1..N-1] as
"Skipped due to queued user message." + end + Note over ToolExecution: steeringAfterTools = steeringMessages + Note over ToolExecution: break out of tool loop + end + end + + alt steeringAfterTools not empty + ToolExecution-->>runLLMIteration: pendingMessages = steeringAfterTools + Note over runLLMIteration: next iteration will inject
these before calling LLM + end + + Note over runLLMIteration: ── loop back to iteration start ── +``` + +### Polling checkpoints + +| # | Location | When | Purpose | +|---|----------|------|---------| +| 1 | Top of `runLLMIteration`, before first LLM call | Once, at loop entry | Catch messages enqueued while the agent was still setting up context | +| 2 | After every tool completes (including the first and the last) | Immediately after each tool's result is processed | Interrupt the batch as early as possible — if steering is found and there are remaining tools, they are all skipped | + +### What happens to skipped tools + +When steering interrupts a tool batch after tool `[i]` completes, all tools from `[i+1]` to `[N-1]` are **not executed**. Instead, a tool result message is generated for each: + +```json +{ + "role": "tool", + "content": "Skipped due to queued user message.", + "tool_call_id": "
SkipInitialSteeringPoll: true"] + E --> F[Return response] +``` + +**Why `SkipInitialSteeringPoll: true`?** Because `Continue` already dequeued the messages itself. Without this flag, `runLLMIteration` would poll again at the start and find nothing (the queue is already empty), or worse, double-process if new messages arrived in the meantime. + +## Configuration + +```json +{ + "agents": { + "defaults": { + "steering_mode": "one-at-a-time" + } + } +} +``` + +| Field | Type | Default | Env var | +|-------|------|---------|---------| +| `steering_mode` | `string` | `"one-at-a-time"` | `PICOCLAW_AGENTS_DEFAULTS_STEERING_MODE` | + + +## Design decisions and trade-offs + +| Decision | Rationale | +|----------|-----------| +| Sequential tool execution | Required for per-tool steering polls. Parallel execution cannot be interrupted mid-batch. | +| Polling-based (not channel/signal) | Keeps the implementation simple. No need for `select` or signal channels. The polling cost is negligible (mutex lock + slice length check). | +| `one-at-a-time` as default | Gives the model a chance to react to each steering message individually. More predictable behavior than dumping all messages at once. | +| Skipped tools get explicit error results | The LLM protocol requires a tool result for every tool call in the assistant message. Omitting them would cause API errors. The skip message also informs the model about what was not done. | +| `Continue()` uses `SkipInitialSteeringPoll` | Prevents race conditions and double-dequeuing when resuming an idle agent. | +| Queue stored on `AgentLoop`, not `AgentInstance` | Steering is a loop-level concern (it affects the iteration flow), not a per-agent concern. All agents share the same steering queue since `processMessage` is sequential. | +| Bus drain goroutine in `Run()` | Channels (Telegram, Discord, etc.) publish to the bus via `PublishInbound`. Without the drain, messages would queue in the bus channel buffer and only be consumed after `processMessage` returns — defeating the purpose of steering. The drain goroutine bridges the gap by consuming new bus messages and calling `Steer()` while the agent is busy. | +| Audio transcription before steering | The drain goroutine calls `al.transcribeAudioInMessage(ctx, msg)` before steering, so voice messages are converted to text before the agent sees them. If transcription fails, the error is silently discarded and the original message is steered as-is. | +| `MaxQueueSize = 10` | Prevents unbounded memory growth if a user sends many messages while the agent is busy. Excess messages are dropped with a warning. | diff --git a/docs/hooks/README.md b/docs/hooks/README.md new file mode 100644 index 00000000..ec3bbc46 --- /dev/null +++ b/docs/hooks/README.md @@ -0,0 +1,679 @@ +# Hook System Guide + +This document describes the hook system that is implemented in the current repository, not the older design draft. + +The current implementation supports two mounting modes: + +1. In-process hooks +2. Out-of-process process hooks (`JSON-RPC over stdio`) + +The repository no longer ships standalone example source files. The Go and Python examples below are embedded directly in this document. If you want to use them, copy them into your own local files first. + +## Supported Hook Types + +| Type | Interface | Stage | Can modify data | +| --- | --- | --- | --- | +| Observer | `EventObserver` | EventBus broadcast | No | +| LLM interceptor | `LLMInterceptor` | `before_llm` / `after_llm` | Yes | +| Tool interceptor | `ToolInterceptor` | `before_tool` / `after_tool` | Yes | +| Tool approver | `ToolApprover` | `approve_tool` | No, returns allow/deny | + +The currently exposed synchronous hook points are: + +- `before_llm` +- `after_llm` +- `before_tool` +- `after_tool` +- `approve_tool` + +Everything else is exposed as read-only events. + +## Execution Order + +`HookManager` sorts hooks like this: + +1. In-process hooks first +2. Process hooks second +3. Lower `priority` first within the same source +4. Name order as the final tie-breaker + +## Timeouts + +Global defaults live under `hooks.defaults`: + +- `observer_timeout_ms` +- `interceptor_timeout_ms` +- `approval_timeout_ms` + +Note: the current implementation does not support per-process-hook `timeout_ms`. Timeouts are global defaults. + +## Quick Start + +If your first goal is simply to prove that the hook flow works and observe real requests, the easiest path is the Python process-hook example below: + +1. Enable `hooks.enabled` +2. Save the Python example from this document to a local file, for example `/tmp/review_gate.py` +3. Set `PICOCLAW_HOOK_LOG_FILE` +4. Restart the gateway +5. Watch the log file with `tail -f` + +Example: + +```json +{ + "hooks": { + "enabled": true, + "processes": { + "py_review_gate": { + "enabled": true, + "priority": 100, + "transport": "stdio", + "command": [ + "python3", + "/tmp/review_gate.py" + ], + "observe": [ + "tool_exec_start", + "tool_exec_end", + "tool_exec_skipped" + ], + "intercept": [ + "before_tool", + "approve_tool" + ], + "env": { + "PICOCLAW_HOOK_LOG_FILE": "/tmp/picoclaw-hook-review-gate.log" + } + } + } + } +} +``` + +Watch it with: + +```bash +tail -f /tmp/picoclaw-hook-review-gate.log +``` + +If you are developing PicoClaw itself rather than only validating the protocol, continue with the Go in-process example as well. + +## What The Two Examples Are For + +- Go in-process example + Best for validating the host-side hook chain and understanding `MountHook()` plus the synchronous stages +- Python process example + Best for understanding the `JSON-RPC over stdio` protocol and verifying the message flow between PicoClaw and an external process + +Both examples are intentionally safe: they only log, never rewrite, and never deny. + +## Go In-Process Example + +The following is a minimal logging hook for in-process use. It implements: + +1. `EventObserver` +2. `LLMInterceptor` +3. `ToolInterceptor` +4. `ToolApprover` + +It only records activity. It does not rewrite requests or reject tools. + +You can save it as your own Go file, for example `pkg/myhooks/example_logger.go`: + +```go +package myhooks + +import ( + "context" + "encoding/json" + "os" + "path/filepath" + "strings" + "sync" + "time" + + "github.com/sipeed/picoclaw/pkg/agent" + "github.com/sipeed/picoclaw/pkg/logger" +) + +type ExampleLoggerHookOptions struct { + LogFile string `json:"log_file,omitempty"` + LogEvents bool `json:"log_events,omitempty"` +} + +type ExampleLoggerHook struct { + logFile string + logEvents bool + mu sync.Mutex +} + +func NewExampleLoggerHook(opts ExampleLoggerHookOptions) *ExampleLoggerHook { + return &ExampleLoggerHook{ + logFile: strings.TrimSpace(opts.LogFile), + logEvents: opts.LogEvents, + } +} + +func (h *ExampleLoggerHook) OnEvent(ctx context.Context, evt agent.Event) error { + _ = ctx + if h == nil || !h.logEvents { + return nil + } + h.record("event", evt.Meta, map[string]any{ + "event": evt.Kind.String(), + "payload": evt.Payload, + }, nil) + return nil +} + +func (h *ExampleLoggerHook) BeforeLLM( + ctx context.Context, + req *agent.LLMHookRequest, +) (*agent.LLMHookRequest, agent.HookDecision, error) { + _ = ctx + h.record("before_llm", req.Meta, req, agent.HookDecision{Action: agent.HookActionContinue}) + return req, agent.HookDecision{Action: agent.HookActionContinue}, nil +} + +func (h *ExampleLoggerHook) AfterLLM( + ctx context.Context, + resp *agent.LLMHookResponse, +) (*agent.LLMHookResponse, agent.HookDecision, error) { + _ = ctx + h.record("after_llm", resp.Meta, resp, agent.HookDecision{Action: agent.HookActionContinue}) + return resp, agent.HookDecision{Action: agent.HookActionContinue}, nil +} + +func (h *ExampleLoggerHook) BeforeTool( + ctx context.Context, + call *agent.ToolCallHookRequest, +) (*agent.ToolCallHookRequest, agent.HookDecision, error) { + _ = ctx + h.record("before_tool", call.Meta, call, agent.HookDecision{Action: agent.HookActionContinue}) + return call, agent.HookDecision{Action: agent.HookActionContinue}, nil +} + +func (h *ExampleLoggerHook) AfterTool( + ctx context.Context, + result *agent.ToolResultHookResponse, +) (*agent.ToolResultHookResponse, agent.HookDecision, error) { + _ = ctx + h.record("after_tool", result.Meta, result, agent.HookDecision{Action: agent.HookActionContinue}) + return result, agent.HookDecision{Action: agent.HookActionContinue}, nil +} + +func (h *ExampleLoggerHook) ApproveTool( + ctx context.Context, + req *agent.ToolApprovalRequest, +) (agent.ApprovalDecision, error) { + _ = ctx + decision := agent.ApprovalDecision{Approved: true} + h.record("approve_tool", req.Meta, req, decision) + return decision, nil +} + +func (h *ExampleLoggerHook) record(stage string, meta agent.EventMeta, payload any, decision any) { + logger.InfoCF("hooks", "Example hook observed", map[string]any{ + "stage": stage, + }) + if h == nil || h.logFile == "" { + return + } + + entry := map[string]any{ + "ts": time.Now().UTC(), + "stage": stage, + "meta": meta, + "payload": payload, + "decision": decision, + } + + body, err := json.Marshal(entry) + if err != nil { + logger.WarnCF("hooks", "Example hook log encode failed", map[string]any{ + "stage": stage, + "error": err.Error(), + }) + return + } + + h.mu.Lock() + defer h.mu.Unlock() + + if dir := filepath.Dir(h.logFile); dir != "" && dir != "." { + if err := os.MkdirAll(dir, 0o755); err != nil { + logger.WarnCF("hooks", "Example hook log mkdir failed", map[string]any{ + "stage": stage, + "path": h.logFile, + "error": err.Error(), + }) + return + } + } + + file, err := os.OpenFile(h.logFile, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644) + if err != nil { + logger.WarnCF("hooks", "Example hook log open failed", map[string]any{ + "stage": stage, + "path": h.logFile, + "error": err.Error(), + }) + return + } + defer func() { _ = file.Close() }() + + if _, err := file.Write(append(body, '\n')); err != nil { + logger.WarnCF("hooks", "Example hook log write failed", map[string]any{ + "stage": stage, + "path": h.logFile, + "error": err.Error(), + }) + } +} +``` + +### Mounting It In Code + +If code mounting is enough, call this after `AgentLoop` is initialized: + +```go +hook := myhooks.NewExampleLoggerHook(myhooks.ExampleLoggerHookOptions{ + LogFile: "/tmp/picoclaw-hook-example-logger.log", + LogEvents: true, +}) + +if err := al.MountHook(agent.NamedHook("example-logger", hook)); err != nil { + panic(err) +} +``` + +### If You Also Want Config Mounting + +The hook system supports builtin hooks, but that requires you to compile the factory into your binary. In practice, that means you need registration code like this alongside the hook definition above: + +```go +package myhooks + +import ( + "context" + "encoding/json" + "fmt" + + "github.com/sipeed/picoclaw/pkg/agent" + "github.com/sipeed/picoclaw/pkg/config" +) + +func init() { + if err := agent.RegisterBuiltinHook("example_logger", func( + ctx context.Context, + spec config.BuiltinHookConfig, + ) (any, error) { + _ = ctx + + var opts ExampleLoggerHookOptions + if len(spec.Config) > 0 { + if err := json.Unmarshal(spec.Config, &opts); err != nil { + return nil, fmt.Errorf("decode example_logger config: %w", err) + } + } + return NewExampleLoggerHook(opts), nil + }); err != nil { + panic(err) + } +} +``` + +Only after you register that builtin will the following config work: + +```json +{ + "hooks": { + "enabled": true, + "builtins": { + "example_logger": { + "enabled": true, + "priority": 10, + "config": { + "log_file": "/tmp/picoclaw-hook-example-logger.log", + "log_events": true + } + } + } + } +} +``` + +### How To Observe It + +- If `log_file` is set, each hook call is appended as JSON Lines +- If `log_file` is not set, the hook still writes summaries to the gateway log +- Requests that only hit the LLM path usually show `before_llm` and `after_llm` +- Requests that trigger tools usually also show `before_tool`, `approve_tool`, and `after_tool` +- If `log_events=true`, you will also see `event` + +Typical log lines: + +```json +{"ts":"2026-03-21T14:10:00Z","stage":"before_tool","meta":{"session_key":"session-1"},"payload":{"tool":"echo_text","arguments":{"text":"hello"}},"decision":{"action":"continue"}} +{"ts":"2026-03-21T14:10:00Z","stage":"approve_tool","meta":{"session_key":"session-1"},"payload":{"tool":"echo_text","arguments":{"text":"hello"}},"decision":{"approved":true}} +``` + +If you only see `before_llm` and `after_llm`, that usually means the request did not trigger any tool call, not that the hook failed to mount. + +## Python Process-Hook Example + +The following script is a minimal process-hook example. It uses only the Python standard library and supports: + +1. `hook.hello` +2. `hook.event` +3. `hook.before_tool` +4. `hook.approve_tool` + +It only records activity. It does not rewrite or deny anything. + +Save it to any local path, for example `/tmp/review_gate.py`: + +```python +#!/usr/bin/env python3 +from __future__ import annotations + +import json +import os +import signal +import sys +from datetime import datetime, timezone +from typing import Any + +LOG_EVENTS = os.getenv("PICOCLAW_HOOK_LOG_EVENTS", "1").lower() not in {"0", "false", "no"} +LOG_FILE = os.getenv("PICOCLAW_HOOK_LOG_FILE", "").strip() + + +def append_log(entry: dict[str, Any]) -> None: + if not LOG_FILE: + return + + payload = { + "ts": datetime.now(timezone.utc).isoformat(), + **entry, + } + try: + log_dir = os.path.dirname(LOG_FILE) + if log_dir: + os.makedirs(log_dir, exist_ok=True) + with open(LOG_FILE, "a", encoding="utf-8") as handle: + handle.write(json.dumps(payload, ensure_ascii=True) + "\n") + except OSError as exc: + log_stderr(f"failed to write hook log file {LOG_FILE}: {exc}") + + +def send_response(message_id: int, result: Any | None = None, error: str | None = None) -> None: + payload: dict[str, Any] = { + "jsonrpc": "2.0", + "id": message_id, + } + if error is not None: + payload["error"] = {"code": -32000, "message": error} + else: + payload["result"] = result if result is not None else {} + + append_log({ + "direction": "out", + "id": message_id, + "response": payload.get("result"), + "error": payload.get("error"), + }) + + try: + sys.stdout.write(json.dumps(payload, ensure_ascii=True) + "\n") + sys.stdout.flush() + except BrokenPipeError: + raise SystemExit(0) from None + + +def log_stderr(message: str) -> None: + try: + sys.stderr.write(message + "\n") + sys.stderr.flush() + except BrokenPipeError: + raise SystemExit(0) from None + + +def handle_shutdown_signal(signum: int, _frame: Any) -> None: + raise KeyboardInterrupt(f"received signal {signum}") + + +def handle_before_tool(params: dict[str, Any]) -> dict[str, Any]: + _ = params + return {"action": "continue"} + + +def handle_approve_tool(params: dict[str, Any]) -> dict[str, Any]: + _ = params + return {"approved": True} + + +def handle_request(method: str, params: dict[str, Any]) -> dict[str, Any]: + if method == "hook.hello": + return {"ok": True, "name": "python-review-gate"} + if method == "hook.before_tool": + return handle_before_tool(params) + if method == "hook.approve_tool": + return handle_approve_tool(params) + if method == "hook.before_llm": + return {"action": "continue"} + if method == "hook.after_llm": + return {"action": "continue"} + if method == "hook.after_tool": + return {"action": "continue"} + raise KeyError(f"method not found: {method}") + + +def main() -> int: + try: + for raw_line in sys.stdin: + line = raw_line.strip() + if not line: + continue + + try: + message = json.loads(line) + except json.JSONDecodeError as exc: + log_stderr(f"failed to decode request: {exc}") + append_log({ + "direction": "in", + "decode_error": str(exc), + "raw": line, + }) + continue + + method = message.get("method") + message_id = message.get("id", 0) + params = message.get("params") or {} + if not isinstance(params, dict): + params = {} + + append_log({ + "direction": "in", + "id": message_id, + "method": method, + "params": params, + "notification": not bool(message_id), + }) + + if not message_id: + if method == "hook.event" and LOG_EVENTS: + log_stderr(f"observed event: {params.get('Kind')}") + continue + + try: + result = handle_request(str(method or ""), params) + except KeyError as exc: + send_response(int(message_id), error=str(exc)) + continue + except Exception as exc: + send_response(int(message_id), error=f"unexpected error: {exc}") + continue + + send_response(int(message_id), result=result) + except KeyboardInterrupt: + return 0 + + return 0 + + +if __name__ == "__main__": + signal.signal(signal.SIGINT, handle_shutdown_signal) + signal.signal(signal.SIGTERM, handle_shutdown_signal) + raise SystemExit(main()) +``` + +### Configuration + +```json +{ + "hooks": { + "enabled": true, + "processes": { + "py_review_gate": { + "enabled": true, + "priority": 100, + "transport": "stdio", + "command": [ + "python3", + "/abs/path/to/review_gate.py" + ], + "observe": [ + "tool_exec_start", + "tool_exec_end", + "tool_exec_skipped" + ], + "intercept": [ + "before_tool", + "approve_tool" + ], + "env": { + "PICOCLAW_HOOK_LOG_FILE": "/tmp/picoclaw-hook-review-gate.log" + } + } + } + } +} +``` + +### Environment Variables + +- `PICOCLAW_HOOK_LOG_EVENTS` + Whether to write `hook.event` summaries to `stderr`, enabled by default +- `PICOCLAW_HOOK_LOG_FILE` + Path to an external log file. When set, the script appends inbound hook requests, notifications, and outbound responses as JSON Lines + +Note: `PICOCLAW_HOOK_LOG_FILE` has no default. If you do not set it, the script does not write any file logs. + +### How To Confirm It Received Hooks + +Watch two places: + +- Gateway logs + Useful for confirming that the host successfully started the process and for seeing event summaries written to `stderr` +- `PICOCLAW_HOOK_LOG_FILE` + Useful for seeing the exact requests the script received and the exact responses it returned + +Typical interpretation: + +- Only `hook.hello` + The process started and completed the handshake, but no business hook request has arrived yet +- `hook.event` + The `observe` configuration is working +- `hook.before_tool` + The `intercept: ["before_tool", ...]` configuration is working +- `hook.approve_tool` + The approval hook path is working + +Because this example never rewrites or denies, the expected responses look like: + +```json +{"direction":"out","id":7,"response":{"action":"continue"},"error":null} +{"direction":"out","id":8,"response":{"approved":true},"error":null} +``` + +A complete sample: + +```json +{"ts":"2026-03-21T14:12:00+00:00","direction":"in","id":1,"method":"hook.hello","params":{"name":"py_review_gate","version":1,"modes":["observe","tool","approve"]},"notification":false} +{"ts":"2026-03-21T14:12:00+00:00","direction":"out","id":1,"response":{"ok":true,"name":"python-review-gate"},"error":null} +{"ts":"2026-03-21T14:12:05+00:00","direction":"in","id":0,"method":"hook.event","params":{"Kind":"tool_exec_start"},"notification":true} +{"ts":"2026-03-21T14:12:05+00:00","direction":"in","id":7,"method":"hook.before_tool","params":{"tool":"echo_text","arguments":{"text":"hello"}},"notification":false} +{"ts":"2026-03-21T14:12:05+00:00","direction":"out","id":7,"response":{"action":"continue"},"error":null} +``` + +Additional notes: + +- Timestamps are UTC +- `notification=true` means it was a notification such as `hook.event`, which does not expect a response +- `id` increases within a single hook process; if the process restarts, the counter starts over + +## Process-Hook Protocol + +Current process hooks use `JSON-RPC over stdio`: + +- PicoClaw starts the external process +- Requests and responses are exchanged as one JSON message per line +- `hook.event` is a notification and does not need a response +- `hook.before_llm`, `hook.after_llm`, `hook.before_tool`, `hook.after_tool`, and `hook.approve_tool` are request/response calls + +The host does not currently accept new RPCs initiated by the process hook. In practice, that means an external hook can only respond to PicoClaw calls; it cannot call back into the host to send channel messages. + +## Configuration Fields + +### `hooks.builtins.
+
+
Weixin (微信个人号)
+ +PicoClaw 支持使用腾讯官方 iLink API 连接您的个人微信账号。 + +**1. 登录** +运行交互式扫码登录流程： +```bash +picoclaw onboard weixin +``` +在终端扫描打印出的二维码。登录成功后，Token 将自动保存到您的配置文件中。 + +**2. 配置** +（可选）更新 `allow_from` 填写微信 User ID，以限制哪些用户可以给机器人发消息： +```json +{ + "channels": { + "weixin": { + "enabled": true, + "token": "你的_TOKEN", + "allow_from": ["你的_USER_ID"] + } + } +} +``` + +**3. 运行** +```bash +picoclaw gateway +``` + +Matrix
diff --git a/pkg/agent/context.go b/pkg/agent/context.go index 8db8f0b5..022230d4 100644 --- a/pkg/agent/context.go +++ b/pkg/agent/context.go @@ -222,13 +222,10 @@ func (cb *ContextBuilder) InvalidateCache() { // invalidation (bootstrap files + memory). Skill roots are handled separately // because they require both directory-level and recursive file-level checks. func (cb *ContextBuilder) sourcePaths() []string { - return []string{ - filepath.Join(cb.workspace, "AGENTS.md"), - filepath.Join(cb.workspace, "SOUL.md"), - filepath.Join(cb.workspace, "USER.md"), - filepath.Join(cb.workspace, "IDENTITY.md"), - filepath.Join(cb.workspace, "memory", "MEMORY.md"), - } + agentDefinition := cb.LoadAgentDefinition() + paths := agentDefinition.trackedPaths(cb.workspace) + paths = append(paths, filepath.Join(cb.workspace, "memory", "MEMORY.md")) + return uniquePaths(paths) } // skillRoots returns all skill root directories that can affect @@ -432,18 +429,32 @@ func skillFilesChangedSince(skillRoots []string, filesAtCache map[string]time.Ti } func (cb *ContextBuilder) LoadBootstrapFiles() string { - bootstrapFiles := []string{ - "AGENTS.md", - "SOUL.md", - "USER.md", - "IDENTITY.md", + var sb strings.Builder + + agentDefinition := cb.LoadAgentDefinition() + if agentDefinition.Agent != nil { + label := string(agentDefinition.Source) + if label == "" { + label = relativeWorkspacePath(cb.workspace, agentDefinition.Agent.Path) + } + fmt.Fprintf(&sb, "## %s\n\n%s\n\n", label, agentDefinition.Agent.Body) + } + if agentDefinition.Soul != nil { + fmt.Fprintf( + &sb, + "## %s\n\n%s\n\n", + relativeWorkspacePath(cb.workspace, agentDefinition.Soul.Path), + agentDefinition.Soul.Content, + ) + } + if agentDefinition.User != nil { + fmt.Fprintf(&sb, "## %s\n\n%s\n\n", "USER.md", agentDefinition.User.Content) } - var sb strings.Builder - for _, filename := range bootstrapFiles { - filePath := filepath.Join(cb.workspace, filename) + if agentDefinition.Source != AgentDefinitionSourceAgent { + filePath := filepath.Join(cb.workspace, "IDENTITY.md") if data, err := os.ReadFile(filePath); err == nil { - fmt.Fprintf(&sb, "## %s\n\n%s\n\n", filename, data) + fmt.Fprintf(&sb, "## %s\n\n%s\n\n", "IDENTITY.md", data) } } diff --git a/pkg/agent/context_budget.go b/pkg/agent/context_budget.go new file mode 100644 index 00000000..c87695c7 --- /dev/null +++ b/pkg/agent/context_budget.go @@ -0,0 +1,176 @@ +// PicoClaw - Ultra-lightweight personal AI agent +// License: MIT +// +// Copyright (c) 2026 PicoClaw contributors + +package agent + +import ( + "encoding/json" + "unicode/utf8" + + "github.com/sipeed/picoclaw/pkg/providers" +) + +// parseTurnBoundaries returns the starting index of each Turn in the history. +// A Turn is a complete "user input → LLM iterations → final response" cycle +// (as defined in #1316). Each Turn begins at a user message and extends +// through all subsequent assistant/tool messages until the next user message. +// +// Cutting at a Turn boundary guarantees that no tool-call sequence +// (assistant+ToolCalls → tool results) is split across the cut. +func parseTurnBoundaries(history []providers.Message) []int { + var starts []int + for i, msg := range history { + if msg.Role == "user" { + starts = append(starts, i) + } + } + return starts +} + +// isSafeBoundary reports whether index is a valid Turn boundary — i.e., +// a position where the kept portion (history[index:]) begins at a user +// message, so no tool-call sequence is torn apart. +func isSafeBoundary(history []providers.Message, index int) bool { + if index <= 0 || index >= len(history) { + return true + } + return history[index].Role == "user" +} + +// findSafeBoundary locates the nearest Turn boundary to targetIndex. +// It prefers the boundary at or before targetIndex (preserving more recent +// context). Falls back to the nearest boundary after targetIndex, and +// returns targetIndex unchanged only when no Turn boundary exists at all. +func findSafeBoundary(history []providers.Message, targetIndex int) int { + if len(history) == 0 { + return 0 + } + if targetIndex <= 0 { + return 0 + } + if targetIndex >= len(history) { + return len(history) + } + + turns := parseTurnBoundaries(history) + if len(turns) == 0 { + return targetIndex + } + + // Find the last Turn boundary at or before targetIndex. + // Prefer backward: keeps more recent messages. + backward := -1 + for _, t := range turns { + if t <= targetIndex { + backward = t + } + } + if backward > 0 { + return backward + } + + // No valid Turn boundary before target (or only at index 0 which + // would keep everything). Use the first Turn after targetIndex. + for _, t := range turns { + if t > targetIndex { + return t + } + } + + // No Turn boundary after targetIndex either. The only boundary is at + // index 0, meaning the entire history is a single Turn. Return 0 to + // signal that safe compression is not possible — callers check for + // mid <= 0 and skip compression in that case. + return 0 +} + +// estimateMessageTokens estimates the token count for a single message, +// including Content, ReasoningContent, ToolCalls arguments, ToolCallID +// metadata, and Media items. Uses a heuristic of 2.5 characters per token. +func estimateMessageTokens(msg providers.Message) int { + chars := utf8.RuneCountInString(msg.Content) + + // ReasoningContent (extended thinking / chain-of-thought) can be + // substantial and is stored in session history via AddFullMessage. + if msg.ReasoningContent != "" { + chars += utf8.RuneCountInString(msg.ReasoningContent) + } + + for _, tc := range msg.ToolCalls { + chars += len(tc.ID) + len(tc.Type) + if tc.Function != nil { + // Count function name + arguments (the wire format for most providers). + // tc.Name mirrors tc.Function.Name — count only once to avoid double-counting. + chars += len(tc.Function.Name) + len(tc.Function.Arguments) + } else { + // Fallback: some provider formats use top-level Name without Function. + chars += len(tc.Name) + } + } + + if msg.ToolCallID != "" { + chars += len(msg.ToolCallID) + } + + // Per-message overhead for role label, JSON structure, separators. + const messageOverhead = 12 + chars += messageOverhead + + tokens := chars * 2 / 5 + + // Media items (images, files) are serialized by provider adapters into + // multipart or image_url payloads. Add a fixed per-item token estimate + // directly (not through the chars heuristic) since actual cost depends + // on resolution and provider-specific image tokenization. + const mediaTokensPerItem = 256 + tokens += len(msg.Media) * mediaTokensPerItem + + return tokens +} + +// estimateToolDefsTokens estimates the total token cost of tool definitions +// as they appear in the LLM request. Each tool's name, description, and +// JSON schema parameters contribute to the context window budget. +func estimateToolDefsTokens(defs []providers.ToolDefinition) int { + if len(defs) == 0 { + return 0 + } + + totalChars := 0 + for _, d := range defs { + totalChars += len(d.Function.Name) + len(d.Function.Description) + + if d.Function.Parameters != nil { + if paramJSON, err := json.Marshal(d.Function.Parameters); err == nil { + totalChars += len(paramJSON) + } + } + + // Per-tool overhead: type field, JSON structure, separators. + totalChars += 20 + } + + return totalChars * 2 / 5 +} + +// isOverContextBudget checks whether the assembled messages plus tool definitions +// and output reserve would exceed the model's context window. This enables +// proactive compression before calling the LLM, rather than reacting to 400 errors. +func isOverContextBudget( + contextWindow int, + messages []providers.Message, + toolDefs []providers.ToolDefinition, + maxTokens int, +) bool { + msgTokens := 0 + for _, m := range messages { + msgTokens += estimateMessageTokens(m) + } + + toolTokens := estimateToolDefsTokens(toolDefs) + total := msgTokens + toolTokens + maxTokens + + return total > contextWindow +} diff --git a/pkg/agent/context_budget_test.go b/pkg/agent/context_budget_test.go new file mode 100644 index 00000000..870f0fbe --- /dev/null +++ b/pkg/agent/context_budget_test.go @@ -0,0 +1,826 @@ +package agent + +import ( + "fmt" + "strings" + "testing" + + "github.com/sipeed/picoclaw/pkg/providers" +) + +// msgUser creates a user message. +func msgUser(content string) providers.Message { + return providers.Message{Role: "user", Content: content} +} + +// msgAssistant creates a plain assistant message (no tool calls). +func msgAssistant(content string) providers.Message { + return providers.Message{Role: "assistant", Content: content} +} + +// msgAssistantTC creates an assistant message with tool calls. +func msgAssistantTC(toolIDs ...string) providers.Message { + tcs := make([]providers.ToolCall, len(toolIDs)) + for i, id := range toolIDs { + tcs[i] = providers.ToolCall{ + ID: id, + Type: "function", + Name: "tool_" + id, + Function: &providers.FunctionCall{ + Name: "tool_" + id, + Arguments: `{"key":"value"}`, + }, + } + } + return providers.Message{Role: "assistant", ToolCalls: tcs} +} + +// msgTool creates a tool result message. +func msgTool(callID, content string) providers.Message { + return providers.Message{Role: "tool", ToolCallID: callID, Content: content} +} + +func TestParseTurnBoundaries(t *testing.T) { + tests := []struct { + name string + history []providers.Message + want []int + }{ + { + name: "empty history", + history: nil, + want: nil, + }, + { + name: "simple exchange", + history: []providers.Message{ + msgUser("q1"), + msgAssistant("a1"), + msgUser("q2"), + msgAssistant("a2"), + }, + want: []int{0, 2}, + }, + { + name: "tool-call Turn", + history: []providers.Message{ + msgUser("search"), + msgAssistantTC("tc1"), + msgTool("tc1", "result"), + msgAssistant("found it"), + msgUser("thanks"), + msgAssistant("welcome"), + }, + want: []int{0, 4}, + }, + { + name: "chained tool calls in single Turn", + history: []providers.Message{ + msgUser("save and notify"), + msgAssistantTC("tc_save"), + msgTool("tc_save", "saved"), + msgAssistantTC("tc_notify"), + msgTool("tc_notify", "notified"), + msgAssistant("done"), + }, + want: []int{0}, + }, + { + name: "no user messages", + history: []providers.Message{ + msgAssistant("a1"), + msgAssistant("a2"), + }, + want: nil, + }, + { + name: "leading non-user messages", + history: []providers.Message{ + msgAssistantTC("tc1"), + msgTool("tc1", "r1"), + msgAssistant("greeting"), + msgUser("hello"), + msgAssistant("hi"), + }, + want: []int{3}, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := parseTurnBoundaries(tt.history) + if len(got) != len(tt.want) { + t.Errorf("parseTurnBoundaries() = %v, want %v", got, tt.want) + return + } + for i := range got { + if got[i] != tt.want[i] { + t.Errorf("parseTurnBoundaries()[%d] = %d, want %d", i, got[i], tt.want[i]) + } + } + }) + } +} + +func TestIsSafeBoundary(t *testing.T) { + tests := []struct { + name string + history []providers.Message + index int + want bool + }{ + { + name: "empty history, index 0", + history: nil, + index: 0, + want: true, + }, + { + name: "single user message, index 0", + history: []providers.Message{msgUser("hi")}, + index: 0, + want: true, + }, + { + name: "single user message, index 1 (end)", + history: []providers.Message{msgUser("hi")}, + index: 1, + want: true, + }, + { + name: "at user message", + history: []providers.Message{ + msgAssistant("hello"), + msgUser("how are you"), + msgAssistant("fine"), + }, + index: 1, + want: true, + }, + { + name: "at assistant without tool calls", + history: []providers.Message{ + msgUser("hello"), + msgAssistant("response"), + msgUser("follow up"), + }, + index: 1, + want: false, + }, + { + name: "at assistant with tool calls", + history: []providers.Message{ + msgUser("search something"), + msgAssistantTC("tc1"), + msgTool("tc1", "result"), + msgAssistant("here is what I found"), + }, + index: 1, + want: false, + }, + { + name: "at tool result", + history: []providers.Message{ + msgUser("do something"), + msgAssistantTC("tc1"), + msgTool("tc1", "done"), + msgAssistant("completed"), + }, + index: 2, + want: false, + }, + { + name: "negative index", + history: []providers.Message{ + msgUser("hello"), + }, + index: -1, + want: true, + }, + { + name: "index beyond length", + history: []providers.Message{ + msgUser("hello"), + }, + index: 5, + want: true, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := isSafeBoundary(tt.history, tt.index) + if got != tt.want { + t.Errorf("isSafeBoundary(history, %d) = %v, want %v", tt.index, got, tt.want) + } + }) + } +} + +func TestFindSafeBoundary(t *testing.T) { + tests := []struct { + name string + history []providers.Message + targetIndex int + want int + }{ + { + name: "empty history", + history: nil, + targetIndex: 0, + want: 0, + }, + { + name: "target at 0", + history: []providers.Message{msgUser("hi")}, + targetIndex: 0, + want: 0, + }, + { + name: "target beyond length", + history: []providers.Message{msgUser("hi")}, + targetIndex: 5, + want: 1, + }, + { + name: "target already at user message", + history: []providers.Message{ + msgUser("q1"), + msgAssistant("a1"), + msgUser("q2"), + msgAssistant("a2"), + }, + targetIndex: 2, + want: 2, + }, + { + name: "target at assistant, scan backward finds user", + history: []providers.Message{ + msgUser("q1"), + msgAssistant("a1"), + msgUser("q2"), + msgAssistant("a2"), + msgUser("q3"), + }, + targetIndex: 3, // assistant "a2" + want: 2, // backward to user "q2" + }, + { + name: "target inside tool sequence, scan backward finds user", + history: []providers.Message{ + msgUser("q1"), + msgAssistant("a1"), + msgUser("q2"), + msgAssistantTC("tc1", "tc2"), + msgTool("tc1", "r1"), + msgTool("tc2", "r2"), + msgAssistant("summary"), + msgUser("q3"), + }, + targetIndex: 4, // tool result "r1" + want: 2, // backward: 3=assistant+TC (not safe), 2=user → safe + }, + { + name: "target inside tool sequence, backward finds user before chain", + history: []providers.Message{ + msgUser("q1"), + msgAssistant("a1"), + msgUser("q2"), + msgAssistantTC("tc1", "tc2"), + msgTool("tc1", "r1"), + msgTool("tc2", "r2"), + msgAssistant("summary"), + msgUser("q3"), + }, + targetIndex: 5, // tool result "r2" + want: 2, // backward: 4=tool, 3=assistant+TC, 2=user → safe + }, + { + name: "no backward user, scan forward finds one", + history: []providers.Message{ + msgAssistantTC("tc1"), + msgTool("tc1", "r1"), + msgAssistant("a1"), + msgUser("q1"), + }, + targetIndex: 1, // tool result + want: 3, // forward to user "q1" + }, + { + name: "multi-step tool chain preserves atomicity", + history: []providers.Message{ + msgUser("q1"), + msgAssistant("a1"), + msgUser("q2"), + msgAssistantTC("tc1"), + msgTool("tc1", "r1"), + msgAssistantTC("tc2"), + msgTool("tc2", "r2"), + msgAssistant("final"), + msgUser("q3"), + msgAssistant("a3"), + }, + targetIndex: 5, // second assistant+TC + want: 2, // backward: 4=tool, 3=assistant+TC, 2=user → safe + }, + { + name: "all non-user messages returns target unchanged", + history: []providers.Message{ + msgAssistant("a1"), + msgAssistant("a2"), + msgAssistant("a3"), + }, + targetIndex: 1, + want: 1, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := findSafeBoundary(tt.history, tt.targetIndex) + if got != tt.want { + t.Errorf("findSafeBoundary(history, %d) = %d, want %d", + tt.targetIndex, got, tt.want) + } + }) + } +} + +func TestFindSafeBoundary_SingleTurnReturnsZero(t *testing.T) { + // A single Turn with no subsequent user message. The only Turn boundary + // is at index 0; cutting anywhere else would split the Turn's tool + // sequence. findSafeBoundary must return 0 so callers skip compression. + history := []providers.Message{ + msgUser("do everything"), // 0 ← only Turn boundary + msgAssistantTC("tc1"), // 1 + msgTool("tc1", "result"), // 2 + msgAssistant("all done"), // 3 + } + + got := findSafeBoundary(history, 2) + if got != 0 { + t.Errorf("findSafeBoundary(single_turn, 2) = %d, want 0 (cannot split single Turn)", got) + } +} + +func TestFindSafeBoundary_BackwardScanSkipsToolSequence(t *testing.T) { + // A long tool-call chain: user → assistant+TC → tool → tool → ... → assistant → user + // Target is inside the chain; boundary should skip the entire chain backward. + history := []providers.Message{ + msgUser("start"), // 0 + msgAssistant("before chain"), // 1 + msgUser("trigger"), // 2 ← expected safe boundary + msgAssistantTC("t1", "t2", "t3"), // 3 + msgTool("t1", "r1"), // 4 + msgTool("t2", "r2"), // 5 + msgTool("t3", "r3"), // 6 + msgAssistantTC("t4"), // 7 + msgTool("t4", "r4"), // 8 + msgAssistant("chain done"), // 9 + msgUser("next"), // 10 + } + + // Target at index 6 (middle of tool results) + got := findSafeBoundary(history, 6) + if got != 2 { + t.Errorf("findSafeBoundary(history, 6) = %d, want 2 (user before chain)", got) + } +} + +func TestEstimateMessageTokens(t *testing.T) { + tests := []struct { + name string + msg providers.Message + want int // minimum expected tokens (exact value depends on overhead) + }{ + { + name: "plain user message", + msg: msgUser("Hello, world!"), + want: 1, // at least some tokens + }, + { + name: "empty message still has overhead", + msg: providers.Message{Role: "user"}, + want: 1, // message overhead alone + }, + { + name: "assistant with tool calls", + msg: msgAssistantTC("tc_123"), + want: 1, + }, + { + name: "tool result with ID", + msg: msgTool("call_abc", "Here is the search result with lots of content"), + want: 1, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := estimateMessageTokens(tt.msg) + if got < tt.want { + t.Errorf("estimateMessageTokens() = %d, want >= %d", got, tt.want) + } + }) + } +} + +func TestEstimateMessageTokens_ToolCallsContribute(t *testing.T) { + plain := msgAssistant("thinking") + withTC := providers.Message{ + Role: "assistant", + Content: "thinking", + ToolCalls: []providers.ToolCall{ + { + ID: "call_1", + Type: "function", + Name: "web_search", + Function: &providers.FunctionCall{ + Name: "web_search", + Arguments: `{"query":"picoclaw agent framework","max_results":5}`, + }, + }, + }, + } + + plainTokens := estimateMessageTokens(plain) + withTCTokens := estimateMessageTokens(withTC) + + if withTCTokens <= plainTokens { + t.Errorf("message with ToolCalls (%d tokens) should exceed plain message (%d tokens)", + withTCTokens, plainTokens) + } +} + +func TestEstimateMessageTokens_MultibyteContent(t *testing.T) { + // Multi-byte characters (e.g. emoji, accented letters) are single runes + // but may map to different token counts. The heuristic should still produce + // reasonable estimates via RuneCountInString. + msg := msgUser("caf\u00e9 na\u00efve r\u00e9sum\u00e9 \u00fcber stra\u00dfe") + tokens := estimateMessageTokens(msg) + if tokens <= 0 { + t.Errorf("multibyte message should produce positive token count, got %d", tokens) + } +} + +func TestEstimateMessageTokens_LargeArguments(t *testing.T) { + // Simulate a tool call with large JSON arguments. + largeArgs := fmt.Sprintf(`{"content":"%s"}`, strings.Repeat("x", 5000)) + msg := providers.Message{ + Role: "assistant", + ToolCalls: []providers.ToolCall{ + { + ID: "call_large", + Type: "function", + Name: "write_file", + Function: &providers.FunctionCall{ + Name: "write_file", + Arguments: largeArgs, + }, + }, + }, + } + + tokens := estimateMessageTokens(msg) + // 5000+ chars → at least 2000 tokens with the 2.5 char/token heuristic + if tokens < 2000 { + t.Errorf("large tool call arguments should produce significant token count, got %d", tokens) + } +} + +func TestEstimateMessageTokens_ReasoningContent(t *testing.T) { + plain := msgAssistant("result") + withReasoning := providers.Message{ + Role: "assistant", + Content: "result", + ReasoningContent: strings.Repeat("thinking step ", 200), + } + + plainTokens := estimateMessageTokens(plain) + reasoningTokens := estimateMessageTokens(withReasoning) + + if reasoningTokens <= plainTokens { + t.Errorf("message with ReasoningContent (%d tokens) should exceed plain message (%d tokens)", + reasoningTokens, plainTokens) + } +} + +func TestEstimateMessageTokens_MediaItems(t *testing.T) { + plain := msgUser("describe this") + withMedia := providers.Message{ + Role: "user", + Content: "describe this", + Media: []string{"media://img1.png", "media://img2.png"}, + } + + plainTokens := estimateMessageTokens(plain) + mediaTokens := estimateMessageTokens(withMedia) + + if mediaTokens <= plainTokens { + t.Errorf("message with Media (%d tokens) should exceed plain message (%d tokens)", + mediaTokens, plainTokens) + } + + // Each media item should add exactly 256 tokens (not run through chars*2/5). + expectedDelta := 256 * 2 + actualDelta := mediaTokens - plainTokens + if actualDelta != expectedDelta { + t.Errorf("2 media items should add %d tokens, got delta %d", expectedDelta, actualDelta) + } +} + +// --- estimateToolDefsTokens tests --- + +func TestEstimateToolDefsTokens(t *testing.T) { + tests := []struct { + name string + defs []providers.ToolDefinition + want int // minimum expected tokens + }{ + { + name: "empty tool list", + defs: nil, + want: 0, + }, + { + name: "single tool with params", + defs: []providers.ToolDefinition{ + { + Type: "function", + Function: providers.ToolFunctionDefinition{ + Name: "web_search", + Description: "Search the web for information", + Parameters: map[string]any{ + "type": "object", + "properties": map[string]any{ + "query": map[string]any{"type": "string"}, + }, + "required": []any{"query"}, + }, + }, + }, + }, + want: 1, + }, + { + name: "tool without params", + defs: []providers.ToolDefinition{ + { + Type: "function", + Function: providers.ToolFunctionDefinition{ + Name: "list_dir", + Description: "List directory contents", + }, + }, + }, + want: 1, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := estimateToolDefsTokens(tt.defs) + if got < tt.want { + t.Errorf("estimateToolDefsTokens() = %d, want >= %d", got, tt.want) + } + }) + } +} + +func TestEstimateToolDefsTokens_ScalesWithCount(t *testing.T) { + makeTool := func(name string) providers.ToolDefinition { + return providers.ToolDefinition{ + Type: "function", + Function: providers.ToolFunctionDefinition{ + Name: name, + Description: "A test tool that does something useful", + Parameters: map[string]any{ + "type": "object", + "properties": map[string]any{ + "input": map[string]any{"type": "string", "description": "Input value"}, + }, + }, + }, + } + } + + one := estimateToolDefsTokens([]providers.ToolDefinition{makeTool("tool_a")}) + three := estimateToolDefsTokens([]providers.ToolDefinition{ + makeTool("tool_a"), makeTool("tool_b"), makeTool("tool_c"), + }) + + if three <= one { + t.Errorf("3 tools (%d tokens) should exceed 1 tool (%d tokens)", three, one) + } +} + +// --- isOverContextBudget tests --- + +func TestIsOverContextBudget(t *testing.T) { + systemMsg := providers.Message{Role: "system", Content: strings.Repeat("x", 1000)} + userMsg := msgUser("hello") + smallHistory := []providers.Message{systemMsg, msgUser("q1"), msgAssistant("a1"), userMsg} + + tools := []providers.ToolDefinition{ + { + Type: "function", + Function: providers.ToolFunctionDefinition{ + Name: "test_tool", + Description: "A test tool", + Parameters: map[string]any{"type": "object"}, + }, + }, + } + + tests := []struct { + name string + contextWindow int + messages []providers.Message + toolDefs []providers.ToolDefinition + maxTokens int + want bool + }{ + { + name: "within budget", + contextWindow: 100000, + messages: smallHistory, + toolDefs: tools, + maxTokens: 4096, + want: false, + }, + { + name: "over budget with small window", + contextWindow: 100, // very small window + messages: smallHistory, + toolDefs: tools, + maxTokens: 4096, + want: true, + }, + { + name: "large max_tokens eats budget", + contextWindow: 2000, + messages: smallHistory, + toolDefs: tools, + maxTokens: 1800, // leaves almost no room + want: true, + }, + { + name: "empty messages within budget", + contextWindow: 10000, + messages: nil, + toolDefs: nil, + maxTokens: 4096, + want: false, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := isOverContextBudget(tt.contextWindow, tt.messages, tt.toolDefs, tt.maxTokens) + if got != tt.want { + t.Errorf("isOverContextBudget() = %v, want %v", got, tt.want) + } + }) + } +} + +// --- Tests reflecting actual session data shape --- +// Session history never contains system messages. The system prompt is +// built dynamically by BuildMessages. These tests use realistic history +// shapes: user/assistant/tool only, with tool chains and reasoning content. + +func TestFindSafeBoundary_SessionHistoryNoSystem(t *testing.T) { + // Real session history starts with a user message, not a system message. + history := []providers.Message{ + msgUser("hello"), // 0 + msgAssistant("hi there"), // 1 + msgUser("search for X"), // 2 + msgAssistantTC("tc1"), // 3 + msgTool("tc1", "found X"), // 4 + msgAssistant("here is X"), // 5 + msgUser("thanks"), // 6 + msgAssistant("you're welcome"), // 7 + } + + // Mid-point is 4 (tool result). Should snap backward to 2 (user). + got := findSafeBoundary(history, 4) + if got != 2 { + t.Errorf("findSafeBoundary(session_history, 4) = %d, want 2", got) + } +} + +func TestFindSafeBoundary_SessionWithChainedTools(t *testing.T) { + // Session with chained tool calls (save then notify). + history := []providers.Message{ + msgUser("save and notify"), // 0 + msgAssistantTC("tc_save"), // 1 + msgTool("tc_save", "saved"), // 2 + msgAssistantTC("tc_notify"), // 3 + msgTool("tc_notify", "notified"), // 4 + msgAssistant("done"), // 5 + msgUser("check status"), // 6 + msgAssistant("all good"), // 7 + } + + // Target at 3 (inside chain). Should find user at 0, but backward + // scan stops at i>0, so forward scan finds user at 6. + // Actually: backward from 3: 2=tool (no), 1=assistantTC (no). Forward: 4=tool, 5=asst, 6=user ✓ + got := findSafeBoundary(history, 3) + if got != 6 { + t.Errorf("findSafeBoundary(chained_tools, 3) = %d, want 6", got) + } +} + +func TestEstimateMessageTokens_WithReasoningAndMedia(t *testing.T) { + // Message with all fields populated — mirrors what AddFullMessage stores. + msg := providers.Message{ + Role: "assistant", + Content: "Here is the analysis.", + ReasoningContent: strings.Repeat("Let me think about this carefully. ", 50), + ToolCalls: []providers.ToolCall{ + { + ID: "call_1", + Type: "function", + Name: "analyze", + Function: &providers.FunctionCall{ + Name: "analyze", + Arguments: `{"data":"sample","depth":3}`, + }, + }, + }, + } + + tokens := estimateMessageTokens(msg) + + // ReasoningContent alone is ~1700 chars → ~680 tokens. + // Content + TC + overhead adds more. Should be well above 500. + if tokens < 500 { + t.Errorf("message with reasoning+toolcalls should have significant tokens, got %d", tokens) + } + + // Compare without reasoning to ensure it's counted. + msgNoReasoning := msg + msgNoReasoning.ReasoningContent = "" + tokensNoReasoning := estimateMessageTokens(msgNoReasoning) + + if tokens <= tokensNoReasoning { + t.Errorf("reasoning content should add tokens: with=%d, without=%d", tokens, tokensNoReasoning) + } +} + +func TestIsOverContextBudget_RealisticSession(t *testing.T) { + // Simulate what BuildMessages produces: system + session history + current user. + // System message is built by BuildMessages, not stored in session. + systemMsg := providers.Message{ + Role: "system", + Content: strings.Repeat("system prompt content ", 100), + } + sessionHistory := []providers.Message{ + msgUser("first question"), + msgAssistant("first answer"), + msgUser("use tool X"), + { + Role: "assistant", + Content: "I'll use tool X", + ToolCalls: []providers.ToolCall{ + { + ID: "tc1", Type: "function", Name: "tool_x", + Function: &providers.FunctionCall{ + Name: "tool_x", + Arguments: `{"query":"test","verbose":true}`, + }, + }, + }, + }, + {Role: "tool", Content: strings.Repeat("result data ", 200), ToolCallID: "tc1"}, + msgAssistant("Here are the results from tool X."), + } + currentUser := msgUser("follow up question") + + // Assemble as BuildMessages would. + messages := make([]providers.Message, 0, 1+len(sessionHistory)+1) + messages = append(messages, systemMsg) + messages = append(messages, sessionHistory...) + messages = append(messages, currentUser) + + tools := []providers.ToolDefinition{ + { + Type: "function", + Function: providers.ToolFunctionDefinition{ + Name: "tool_x", + Description: "A useful tool", + Parameters: map[string]any{"type": "object"}, + }, + }, + } + + // With a large context window, should be within budget. + if isOverContextBudget(131072, messages, tools, 32768) { + t.Error("realistic session should be within 131072 context window") + } + + // With a tiny context window, should exceed budget. + if !isOverContextBudget(500, messages, tools, 32768) { + t.Error("realistic session should exceed 500 context window") + } +} diff --git a/pkg/agent/context_cache_test.go b/pkg/agent/context_cache_test.go index c26976c3..81a1534b 100644 --- a/pkg/agent/context_cache_test.go +++ b/pkg/agent/context_cache_test.go @@ -37,7 +37,7 @@ func setupWorkspace(t *testing.T, files map[string]string) string { // Codex (only reads last system message as instructions). func TestSingleSystemMessage(t *testing.T) { tmpDir := setupWorkspace(t, map[string]string{ - "IDENTITY.md": "# Identity\nTest agent.", + "AGENT.md": "# Agent\nTest agent.", }) defer os.RemoveAll(tmpDir) @@ -202,10 +202,10 @@ func TestMtimeAutoInvalidation(t *testing.T) { }{ { name: "bootstrap file change", - file: "IDENTITY.md", - contentV1: "# Original Identity", - contentV2: "# Updated Identity", - checkField: "Updated Identity", + file: "AGENT.md", + contentV1: "# Original Agent", + contentV2: "# Updated Agent", + checkField: "Updated Agent", }, { name: "memory file change", @@ -280,7 +280,7 @@ func TestMtimeAutoInvalidation(t *testing.T) { // even when source files haven't changed (useful for tests and reload commands). func TestExplicitInvalidateCache(t *testing.T) { tmpDir := setupWorkspace(t, map[string]string{ - "IDENTITY.md": "# Test Identity", + "AGENT.md": "# Test Agent", }) defer os.RemoveAll(tmpDir) @@ -307,8 +307,8 @@ func TestExplicitInvalidateCache(t *testing.T) { // when no files change (regression test for issue #607). func TestCacheStability(t *testing.T) { tmpDir := setupWorkspace(t, map[string]string{ - "IDENTITY.md": "# Identity\nContent", - "SOUL.md": "# Soul\nContent", + "AGENT.md": "# Agent\nContent", + "SOUL.md": "# Soul\nContent", }) defer os.RemoveAll(tmpDir) @@ -607,7 +607,7 @@ description: delete-me-v1 // Run with: go test -race ./pkg/agent/ -run TestConcurrentBuildSystemPromptWithCache func TestConcurrentBuildSystemPromptWithCache(t *testing.T) { tmpDir := setupWorkspace(t, map[string]string{ - "IDENTITY.md": "# Identity\nConcurrency test agent.", + "AGENT.md": "# Agent\nConcurrency test agent.", "SOUL.md": "# Soul\nBe helpful.", "memory/MEMORY.md": "# Memory\nUser prefers Go.", "skills/demo/SKILL.md": "---\nname: demo\ndescription: \"demo skill\"\n---\n# Demo", @@ -714,7 +714,7 @@ func BenchmarkBuildMessagesWithCache(b *testing.B) { os.MkdirAll(filepath.Join(tmpDir, "memory"), 0o755) os.MkdirAll(filepath.Join(tmpDir, "skills"), 0o755) - for _, name := range []string{"IDENTITY.md", "SOUL.md", "USER.md"} { + for _, name := range []string{"AGENT.md", "SOUL.md"} { os.WriteFile(filepath.Join(tmpDir, name), []byte(strings.Repeat("Content.\n", 10)), 0o644) } diff --git a/pkg/agent/definition.go b/pkg/agent/definition.go new file mode 100644 index 00000000..cf73d607 --- /dev/null +++ b/pkg/agent/definition.go @@ -0,0 +1,255 @@ +package agent + +import ( + "os" + "path/filepath" + "slices" + "strings" + + "github.com/gomarkdown/markdown/parser" + "gopkg.in/yaml.v3" + + "github.com/sipeed/picoclaw/pkg/logger" +) + +// AgentDefinitionSource identifies which agent bootstrap file produced the definition. +type AgentDefinitionSource string + +const ( + // AgentDefinitionSourceAgent indicates the new AGENT.md format. + AgentDefinitionSourceAgent AgentDefinitionSource = "AGENT.md" + // AgentDefinitionSourceAgents indicates the legacy AGENTS.md format. + AgentDefinitionSourceAgents AgentDefinitionSource = "AGENTS.md" +) + +// AgentFrontmatter holds machine-readable AGENT.md configuration. +// +// Known fields are exposed directly for convenience. Fields keeps the full +// parsed frontmatter so future refactors can read additional keys without +// changing the loader contract again. +type AgentFrontmatter struct { + Name string `json:"name"` + Description string `json:"description"` + Tools []string `json:"tools,omitempty"` + Model string `json:"model,omitempty"` + MaxTurns *int `json:"maxTurns,omitempty"` + Skills []string `json:"skills,omitempty"` + MCPServers []string `json:"mcpServers,omitempty"` + Fields map[string]any `json:"fields,omitempty"` +} + +// AgentPromptDefinition represents the parsed AGENT.md or AGENTS.md prompt file. +type AgentPromptDefinition struct { + Path string `json:"path"` + Raw string `json:"raw"` + Body string `json:"body"` + RawFrontmatter string `json:"raw_frontmatter,omitempty"` + Frontmatter AgentFrontmatter `json:"frontmatter"` +} + +// SoulDefinition represents the resolved SOUL.md file linked to the agent. +type SoulDefinition struct { + Path string `json:"path"` + Content string `json:"content"` +} + +// UserDefinition represents the resolved USER.md file linked to the workspace. +type UserDefinition struct { + Path string `json:"path"` + Content string `json:"content"` +} + +// AgentContextDefinition captures the workspace agent definition in a runtime-friendly shape. +type AgentContextDefinition struct { + Source AgentDefinitionSource `json:"source,omitempty"` + Agent *AgentPromptDefinition `json:"agent,omitempty"` + Soul *SoulDefinition `json:"soul,omitempty"` + User *UserDefinition `json:"user,omitempty"` +} + +// LoadAgentDefinition parses the workspace agent bootstrap files. +// +// It prefers the new AGENT.md format and its paired SOUL.md file. When the +// structured files are absent, it falls back to the legacy AGENTS.md layout so +// the current runtime can transition incrementally. +func (cb *ContextBuilder) LoadAgentDefinition() AgentContextDefinition { + return loadAgentDefinition(cb.workspace) +} + +func loadAgentDefinition(workspace string) AgentContextDefinition { + definition := AgentContextDefinition{} + definition.User = loadUserDefinition(workspace) + agentPath := filepath.Join(workspace, string(AgentDefinitionSourceAgent)) + if content, err := os.ReadFile(agentPath); err == nil { + prompt := parseAgentPromptDefinition(agentPath, string(content)) + definition.Source = AgentDefinitionSourceAgent + definition.Agent = &prompt + soulPath := filepath.Join(workspace, "SOUL.md") + if content, err := os.ReadFile(soulPath); err == nil { + definition.Soul = &SoulDefinition{ + Path: soulPath, + Content: string(content), + } + } + return definition + } + + legacyPath := filepath.Join(workspace, string(AgentDefinitionSourceAgents)) + if content, err := os.ReadFile(legacyPath); err == nil { + definition.Source = AgentDefinitionSourceAgents + definition.Agent = &AgentPromptDefinition{ + Path: legacyPath, + Raw: string(content), + Body: string(content), + } + } + + defaultSoulPath := filepath.Join(workspace, "SOUL.md") + if definition.Source != "" || fileExists(defaultSoulPath) { + if content, err := os.ReadFile(defaultSoulPath); err == nil { + definition.Soul = &SoulDefinition{ + Path: defaultSoulPath, + Content: string(content), + } + } + } + + return definition +} + +func (definition AgentContextDefinition) trackedPaths(workspace string) []string { + paths := []string{ + filepath.Join(workspace, string(AgentDefinitionSourceAgent)), + filepath.Join(workspace, "SOUL.md"), + filepath.Join(workspace, "USER.md"), + } + if definition.Source != AgentDefinitionSourceAgent { + paths = append(paths, + filepath.Join(workspace, string(AgentDefinitionSourceAgents)), + filepath.Join(workspace, "IDENTITY.md"), + ) + } + return uniquePaths(paths) +} + +func loadUserDefinition(workspace string) *UserDefinition { + userPath := filepath.Join(workspace, "USER.md") + if content, err := os.ReadFile(userPath); err == nil { + return &UserDefinition{ + Path: userPath, + Content: string(content), + } + } + + return nil +} + +func parseAgentPromptDefinition(path, content string) AgentPromptDefinition { + frontmatter, body := splitAgentFrontmatter(content) + return AgentPromptDefinition{ + Path: path, + Raw: content, + Body: body, + RawFrontmatter: frontmatter, + Frontmatter: parseAgentFrontmatter(path, frontmatter), + } +} + +func parseAgentFrontmatter(path, frontmatter string) AgentFrontmatter { + frontmatter = strings.TrimSpace(frontmatter) + if frontmatter == "" { + return AgentFrontmatter{} + } + + rawFields := make(map[string]any) + if err := yaml.Unmarshal([]byte(frontmatter), &rawFields); err != nil { + logger.WarnCF("agent", "Failed to parse AGENT.md frontmatter", map[string]any{ + "path": path, + "error": err.Error(), + }) + return AgentFrontmatter{} + } + + var typed struct { + Name string `yaml:"name"` + Description string `yaml:"description"` + Tools []string `yaml:"tools"` + Model string `yaml:"model"` + MaxTurns *int `yaml:"maxTurns"` + Skills []string `yaml:"skills"` + MCPServers []string `yaml:"mcpServers"` + } + if err := yaml.Unmarshal([]byte(frontmatter), &typed); err != nil { + logger.WarnCF("agent", "Failed to decode AGENT.md frontmatter fields", map[string]any{ + "path": path, + "error": err.Error(), + }) + return AgentFrontmatter{} + } + + return AgentFrontmatter{ + Name: strings.TrimSpace(typed.Name), + Description: strings.TrimSpace(typed.Description), + Tools: append([]string(nil), typed.Tools...), + Model: strings.TrimSpace(typed.Model), + MaxTurns: typed.MaxTurns, + Skills: append([]string(nil), typed.Skills...), + MCPServers: append([]string(nil), typed.MCPServers...), + Fields: rawFields, + } +} + +func splitAgentFrontmatter(content string) (frontmatter, body string) { + normalized := string(parser.NormalizeNewlines([]byte(content))) + lines := strings.Split(normalized, "\n") + if len(lines) == 0 || lines[0] != "---" { + return "", content + } + + end := -1 + for i := 1; i < len(lines); i++ { + if lines[i] == "---" { + end = i + break + } + } + if end == -1 { + return "", content + } + + frontmatter = strings.Join(lines[1:end], "\n") + body = strings.Join(lines[end+1:], "\n") + body = strings.TrimLeft(body, "\n") + return frontmatter, body +} + +func relativeWorkspacePath(workspace, path string) string { + if strings.TrimSpace(path) == "" { + return "" + } + relativePath, err := filepath.Rel(workspace, path) + if err == nil && relativePath != "." && !strings.HasPrefix(relativePath, "..") { + return filepath.ToSlash(relativePath) + } + return filepath.Clean(path) +} + +func uniquePaths(paths []string) []string { + result := make([]string, 0, len(paths)) + for _, path := range paths { + if strings.TrimSpace(path) == "" { + continue + } + cleaned := filepath.Clean(path) + if slices.Contains(result, cleaned) { + continue + } + result = append(result, cleaned) + } + return result +} + +func fileExists(path string) bool { + _, err := os.Stat(path) + return err == nil +} diff --git a/pkg/agent/definition_test.go b/pkg/agent/definition_test.go new file mode 100644 index 00000000..5ee99696 --- /dev/null +++ b/pkg/agent/definition_test.go @@ -0,0 +1,302 @@ +package agent + +import ( + "os" + "path/filepath" + "strings" + "testing" + "time" +) + +func TestLoadAgentDefinitionParsesFrontmatterAndSoul(t *testing.T) { + tmpDir := setupWorkspace(t, map[string]string{ + "AGENT.md": `--- +name: pico +description: Structured agent +model: claude-3-7-sonnet +tools: + - shell + - search +maxTurns: 8 +skills: + - review + - search-docs +mcpServers: + - github +metadata: + mode: strict +--- +# Agent + +Act directly and use tools first. +`, + "SOUL.md": "# Soul\nStay precise.", + }) + defer cleanupWorkspace(t, tmpDir) + + cb := NewContextBuilder(tmpDir) + definition := cb.LoadAgentDefinition() + + if definition.Source != AgentDefinitionSourceAgent { + t.Fatalf("expected source %q, got %q", AgentDefinitionSourceAgent, definition.Source) + } + if definition.Agent == nil { + t.Fatal("expected AGENT.md definition to be loaded") + } + if definition.Agent.Body == "" || !strings.Contains(definition.Agent.Body, "Act directly") { + t.Fatalf("expected AGENT.md body to be preserved, got %q", definition.Agent.Body) + } + if definition.Agent.Frontmatter.Name != "pico" { + t.Fatalf("expected name to be parsed, got %q", definition.Agent.Frontmatter.Name) + } + if definition.Agent.Frontmatter.Model != "claude-3-7-sonnet" { + t.Fatalf("expected model to be parsed, got %q", definition.Agent.Frontmatter.Model) + } + if len(definition.Agent.Frontmatter.Tools) != 2 { + t.Fatalf("expected tools to be parsed, got %v", definition.Agent.Frontmatter.Tools) + } + if definition.Agent.Frontmatter.MaxTurns == nil || *definition.Agent.Frontmatter.MaxTurns != 8 { + t.Fatalf("expected maxTurns to be parsed, got %v", definition.Agent.Frontmatter.MaxTurns) + } + if len(definition.Agent.Frontmatter.Skills) != 2 { + t.Fatalf("expected skills to be parsed, got %v", definition.Agent.Frontmatter.Skills) + } + if len(definition.Agent.Frontmatter.MCPServers) != 1 || definition.Agent.Frontmatter.MCPServers[0] != "github" { + t.Fatalf("expected mcpServers to be parsed, got %v", definition.Agent.Frontmatter.MCPServers) + } + if definition.Agent.Frontmatter.Fields["metadata"] == nil { + t.Fatal("expected arbitrary frontmatter fields to remain available") + } + + if definition.Soul == nil { + t.Fatal("expected SOUL.md to be loaded") + } + if !strings.Contains(definition.Soul.Content, "Stay precise") { + t.Fatalf("expected soul content to be loaded, got %q", definition.Soul.Content) + } + if definition.Soul.Path != filepath.Join(tmpDir, "SOUL.md") { + t.Fatalf("expected default SOUL.md path, got %q", definition.Soul.Path) + } +} + +func TestLoadAgentDefinitionFallsBackToLegacyAgentsMarkdown(t *testing.T) { + tmpDir := setupWorkspace(t, map[string]string{ + "AGENTS.md": "# Legacy Agent\nKeep compatibility.", + "SOUL.md": "# Soul\nLegacy soul.", + }) + defer cleanupWorkspace(t, tmpDir) + + cb := NewContextBuilder(tmpDir) + definition := cb.LoadAgentDefinition() + + if definition.Source != AgentDefinitionSourceAgents { + t.Fatalf("expected source %q, got %q", AgentDefinitionSourceAgents, definition.Source) + } + if definition.Agent == nil { + t.Fatal("expected AGENTS.md to be loaded") + } + if definition.Agent.RawFrontmatter != "" { + t.Fatalf("legacy AGENTS.md should not have frontmatter, got %q", definition.Agent.RawFrontmatter) + } + if !strings.Contains(definition.Agent.Body, "Keep compatibility") { + t.Fatalf("expected legacy body to be preserved, got %q", definition.Agent.Body) + } + if definition.Soul == nil || !strings.Contains(definition.Soul.Content, "Legacy soul") { + t.Fatal("expected default SOUL.md to be loaded for legacy format") + } +} + +func TestLoadAgentDefinitionLoadsWorkspaceUserMarkdown(t *testing.T) { + tmpDir := setupWorkspace(t, map[string]string{ + "AGENT.md": "# Agent\nStructured agent.", + "USER.md": "# User\nWorkspace preferences.", + }) + defer cleanupWorkspace(t, tmpDir) + + cb := NewContextBuilder(tmpDir) + definition := cb.LoadAgentDefinition() + + if definition.User == nil { + t.Fatal("expected USER.md to be loaded") + } + if definition.User.Path != filepath.Join(tmpDir, "USER.md") { + t.Fatalf("expected workspace USER.md path, got %q", definition.User.Path) + } + if !strings.Contains(definition.User.Content, "Workspace preferences") { + t.Fatalf("expected workspace USER.md content, got %q", definition.User.Content) + } +} + +func TestLoadAgentDefinitionInvalidFrontmatterFallsBackToEmptyStructuredFields(t *testing.T) { + tmpDir := setupWorkspace(t, map[string]string{ + "AGENT.md": `--- +name: pico +tools: + - shell + broken +--- +# Agent + +Keep going. +`, + }) + defer cleanupWorkspace(t, tmpDir) + + cb := NewContextBuilder(tmpDir) + definition := cb.LoadAgentDefinition() + + if definition.Agent == nil { + t.Fatal("expected AGENT.md definition to be loaded") + } + if !strings.Contains(definition.Agent.Body, "Keep going.") { + t.Fatalf("expected AGENT.md body to be preserved, got %q", definition.Agent.Body) + } + if definition.Agent.Frontmatter.Name != "" || + definition.Agent.Frontmatter.Description != "" || + definition.Agent.Frontmatter.Model != "" || + definition.Agent.Frontmatter.MaxTurns != nil || + len(definition.Agent.Frontmatter.Tools) != 0 || + len(definition.Agent.Frontmatter.Skills) != 0 || + len(definition.Agent.Frontmatter.MCPServers) != 0 || + len(definition.Agent.Frontmatter.Fields) != 0 { + t.Fatalf("expected invalid frontmatter to decode as empty struct, got %+v", definition.Agent.Frontmatter) + } +} + +func TestLoadBootstrapFilesUsesAgentBodyNotFrontmatter(t *testing.T) { + tmpDir := setupWorkspace(t, map[string]string{ + "AGENT.md": `--- +name: pico +model: codex-mini +--- +# Agent + +Follow the body prompt. +`, + "SOUL.md": "# Soul\nSpeak plainly.", + "IDENTITY.md": "# Identity\nWorkspace identity.", + }) + defer cleanupWorkspace(t, tmpDir) + + cb := NewContextBuilder(tmpDir) + bootstrap := cb.LoadBootstrapFiles() + + if !strings.Contains(bootstrap, "Follow the body prompt") { + t.Fatalf("expected AGENT.md body in bootstrap, got %q", bootstrap) + } + if !strings.Contains(bootstrap, "Speak plainly") { + t.Fatalf("expected resolved soul content in bootstrap, got %q", bootstrap) + } + if strings.Contains(bootstrap, "name: pico") { + t.Fatalf("bootstrap should not expose raw frontmatter, got %q", bootstrap) + } + if strings.Contains(bootstrap, "model: codex-mini") { + t.Fatalf("bootstrap should not expose raw frontmatter, got %q", bootstrap) + } + if !strings.Contains(bootstrap, "SOUL.md") { + t.Fatalf("expected bootstrap to label SOUL.md, got %q", bootstrap) + } + if strings.Contains(bootstrap, "Workspace identity") { + t.Fatalf("structured bootstrap should ignore IDENTITY.md, got %q", bootstrap) + } +} + +func TestLoadBootstrapFilesIncludesWorkspaceUserMarkdown(t *testing.T) { + tmpDir := setupWorkspace(t, map[string]string{ + "AGENT.md": "# Agent\nFollow the new structure.", + "SOUL.md": "# Soul\nSpeak plainly.", + "USER.md": "# User\nShared profile.", + }) + defer cleanupWorkspace(t, tmpDir) + + cb := NewContextBuilder(tmpDir) + bootstrap := cb.LoadBootstrapFiles() + + if !strings.Contains(bootstrap, "Shared profile") { + t.Fatalf("expected workspace USER.md in bootstrap, got %q", bootstrap) + } + if !strings.Contains(bootstrap, "## USER.md") { + t.Fatalf("expected USER.md heading in bootstrap, got %q", bootstrap) + } +} + +func TestStructuredAgentIgnoresIdentityChanges(t *testing.T) { + tmpDir := setupWorkspace(t, map[string]string{ + "AGENT.md": "# Agent\nFollow the new structure.", + "SOUL.md": "# Soul\nVersion one.", + "IDENTITY.md": "# Identity\nLegacy identity.", + }) + defer cleanupWorkspace(t, tmpDir) + + cb := NewContextBuilder(tmpDir) + + promptV1 := cb.BuildSystemPromptWithCache() + if strings.Contains(promptV1, "Legacy identity") { + t.Fatalf("structured prompt should not include IDENTITY.md, got %q", promptV1) + } + + identityPath := filepath.Join(tmpDir, "IDENTITY.md") + if err := os.WriteFile(identityPath, []byte("# Identity\nVersion two."), 0o644); err != nil { + t.Fatal(err) + } + future := time.Now().Add(2 * time.Second) + if err := os.Chtimes(identityPath, future, future); err != nil { + t.Fatal(err) + } + + cb.systemPromptMutex.RLock() + changed := cb.sourceFilesChangedLocked() + cb.systemPromptMutex.RUnlock() + if changed { + t.Fatal("IDENTITY.md should not invalidate cache for structured agent definitions") + } + + promptV2 := cb.BuildSystemPromptWithCache() + if promptV1 != promptV2 { + t.Fatal("structured prompt should remain stable after IDENTITY.md changes") + } +} + +func TestStructuredAgentUserChangesInvalidateCache(t *testing.T) { + tmpDir := setupWorkspace(t, map[string]string{ + "AGENT.md": "# Agent\nFollow the new structure.", + "SOUL.md": "# Soul\nVersion one.", + "USER.md": "# User\nInitial workspace preferences.", + }) + defer cleanupWorkspace(t, tmpDir) + + cb := NewContextBuilder(tmpDir) + + promptV1 := cb.BuildSystemPromptWithCache() + if !strings.Contains(promptV1, "Initial workspace preferences") { + t.Fatalf("expected workspace USER.md in prompt, got %q", promptV1) + } + + userPath := filepath.Join(tmpDir, "USER.md") + if err := os.WriteFile(userPath, []byte("# User\nUpdated workspace preferences."), 0o644); err != nil { + t.Fatal(err) + } + future := time.Now().Add(2 * time.Second) + if err := os.Chtimes(userPath, future, future); err != nil { + t.Fatal(err) + } + + cb.systemPromptMutex.RLock() + changed := cb.sourceFilesChangedLocked() + cb.systemPromptMutex.RUnlock() + if !changed { + t.Fatal("workspace USER.md changes should invalidate cache") + } + + promptV2 := cb.BuildSystemPromptWithCache() + if !strings.Contains(promptV2, "Updated workspace preferences") { + t.Fatalf("expected updated workspace USER.md in prompt, got %q", promptV2) + } +} + +func cleanupWorkspace(t *testing.T, path string) { + t.Helper() + if err := os.RemoveAll(path); err != nil { + t.Fatalf("failed to clean up workspace %s: %v", path, err) + } +} diff --git a/pkg/agent/eventbus.go b/pkg/agent/eventbus.go new file mode 100644 index 00000000..546d8436 --- /dev/null +++ b/pkg/agent/eventbus.go @@ -0,0 +1,121 @@ +package agent + +import ( + "sync" + "sync/atomic" + "time" +) + +const defaultEventSubscriberBuffer = 16 + +// EventSubscription identifies a subscriber channel returned by EventBus.Subscribe. +type EventSubscription struct { + ID uint64 + C <-chan Event +} + +type eventSubscriber struct { + ch chan Event +} + +// EventBus is a lightweight multi-subscriber broadcaster for agent-loop events. +type EventBus struct { + mu sync.RWMutex + subs map[uint64]eventSubscriber + nextID uint64 + closed bool + dropped [eventKindCount]atomic.Int64 +} + +// NewEventBus creates a new in-process event broadcaster. +func NewEventBus() *EventBus { + return &EventBus{ + subs: make(map[uint64]eventSubscriber), + } +} + +// Subscribe registers a new subscriber with the requested channel buffer size. +// A non-positive buffer uses the default size. +func (b *EventBus) Subscribe(buffer int) EventSubscription { + if buffer <= 0 { + buffer = defaultEventSubscriberBuffer + } + + b.mu.Lock() + defer b.mu.Unlock() + + if b.closed { + ch := make(chan Event) + close(ch) + return EventSubscription{C: ch} + } + + b.nextID++ + id := b.nextID + ch := make(chan Event, buffer) + b.subs[id] = eventSubscriber{ch: ch} + return EventSubscription{ID: id, C: ch} +} + +// Unsubscribe removes a subscriber and closes its channel. +func (b *EventBus) Unsubscribe(id uint64) { + b.mu.Lock() + defer b.mu.Unlock() + + sub, ok := b.subs[id] + if !ok { + return + } + + delete(b.subs, id) + close(sub.ch) +} + +// Emit broadcasts an event to all current subscribers without blocking. +// When a subscriber channel is full, the event is dropped for that subscriber. +func (b *EventBus) Emit(evt Event) { + if evt.Time.IsZero() { + evt.Time = time.Now() + } + + b.mu.RLock() + defer b.mu.RUnlock() + + if b.closed { + return + } + + for _, sub := range b.subs { + select { + case sub.ch <- evt: + default: + if evt.Kind < eventKindCount { + b.dropped[evt.Kind].Add(1) + } + } + } +} + +// Dropped returns the number of dropped events for a given kind. +func (b *EventBus) Dropped(kind EventKind) int64 { + if kind >= eventKindCount { + return 0 + } + return b.dropped[kind].Load() +} + +// Close closes all subscriber channels and stops future broadcasts. +func (b *EventBus) Close() { + b.mu.Lock() + defer b.mu.Unlock() + + if b.closed { + return + } + + b.closed = true + for id, sub := range b.subs { + close(sub.ch) + delete(b.subs, id) + } +} diff --git a/pkg/agent/eventbus_test.go b/pkg/agent/eventbus_test.go new file mode 100644 index 00000000..9acc6ddd --- /dev/null +++ b/pkg/agent/eventbus_test.go @@ -0,0 +1,684 @@ +package agent + +import ( + "context" + "os" + "slices" + "testing" + "time" + + "github.com/sipeed/picoclaw/pkg/bus" + "github.com/sipeed/picoclaw/pkg/config" + "github.com/sipeed/picoclaw/pkg/providers" + "github.com/sipeed/picoclaw/pkg/tools" +) + +func TestEventBus_SubscribeEmitUnsubscribeClose(t *testing.T) { + eventBus := NewEventBus() + sub := eventBus.Subscribe(1) + + eventBus.Emit(Event{ + Kind: EventKindTurnStart, + Meta: EventMeta{TurnID: "turn-1"}, + }) + + select { + case evt := <-sub.C: + if evt.Kind != EventKindTurnStart { + t.Fatalf("expected %v, got %v", EventKindTurnStart, evt.Kind) + } + if evt.Meta.TurnID != "turn-1" { + t.Fatalf("expected turn id turn-1, got %q", evt.Meta.TurnID) + } + case <-time.After(time.Second): + t.Fatal("timed out waiting for event") + } + + eventBus.Unsubscribe(sub.ID) + if _, ok := <-sub.C; ok { + t.Fatal("expected subscriber channel to be closed after unsubscribe") + } + + eventBus.Close() + closedSub := eventBus.Subscribe(1) + if _, ok := <-closedSub.C; ok { + t.Fatal("expected closed bus to return a closed subscriber channel") + } +} + +func TestEventBus_DropsWhenSubscriberIsFull(t *testing.T) { + eventBus := NewEventBus() + sub := eventBus.Subscribe(1) + defer eventBus.Unsubscribe(sub.ID) + + start := time.Now() + for i := 0; i < 1000; i++ { + eventBus.Emit(Event{Kind: EventKindLLMRequest}) + } + + if elapsed := time.Since(start); elapsed > 100*time.Millisecond { + t.Fatalf("Emit took too long with a blocked subscriber: %s", elapsed) + } + + if got := eventBus.Dropped(EventKindLLMRequest); got != 999 { + t.Fatalf("expected 999 dropped events, got %d", got) + } +} + +type scriptedToolProvider struct { + calls int +} + +func (m *scriptedToolProvider) Chat( + ctx context.Context, + messages []providers.Message, + toolDefs []providers.ToolDefinition, + model string, + opts map[string]any, +) (*providers.LLMResponse, error) { + m.calls++ + if m.calls == 1 { + return &providers.LLMResponse{ + ToolCalls: []providers.ToolCall{ + { + ID: "call-1", + Name: "mock_custom", + Arguments: map[string]any{"task": "ping"}, + }, + }, + }, nil + } + + return &providers.LLMResponse{ + Content: "done", + }, nil +} + +func (m *scriptedToolProvider) GetDefaultModel() string { + return "scripted-tool-model" +} + +func TestAgentLoop_EmitsMinimalTurnEvents(t *testing.T) { + tmpDir, err := os.MkdirTemp("", "agent-eventbus-*") + if err != nil { + t.Fatalf("failed to create temp dir: %v", err) + } + defer os.RemoveAll(tmpDir) + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: tmpDir, + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + }, + }, + } + + msgBus := bus.NewMessageBus() + provider := &scriptedToolProvider{} + al := NewAgentLoop(cfg, msgBus, provider) + al.RegisterTool(&mockCustomTool{}) + defaultAgent := al.registry.GetDefaultAgent() + if defaultAgent == nil { + t.Fatal("expected default agent") + } + + sub := al.SubscribeEvents(16) + defer al.UnsubscribeEvents(sub.ID) + + response, err := al.runAgentLoop(context.Background(), defaultAgent, processOptions{ + SessionKey: "session-1", + Channel: "cli", + ChatID: "direct", + UserMessage: "run tool", + DefaultResponse: defaultResponse, + EnableSummary: false, + SendResponse: false, + }) + if err != nil { + t.Fatalf("runAgentLoop failed: %v", err) + } + if response != "done" { + t.Fatalf("expected final response 'done', got %q", response) + } + + events := collectEventStream(sub.C) + if len(events) != 8 { + t.Fatalf("expected 8 events, got %d", len(events)) + } + + kinds := make([]EventKind, 0, len(events)) + for _, evt := range events { + kinds = append(kinds, evt.Kind) + } + + expectedKinds := []EventKind{ + EventKindTurnStart, + EventKindLLMRequest, + EventKindLLMResponse, + EventKindToolExecStart, + EventKindToolExecEnd, + EventKindLLMRequest, + EventKindLLMResponse, + EventKindTurnEnd, + } + if !slices.Equal(kinds, expectedKinds) { + t.Fatalf("unexpected event sequence: got %v want %v", kinds, expectedKinds) + } + + turnID := events[0].Meta.TurnID + for i, evt := range events { + if evt.Meta.TurnID != turnID { + t.Fatalf("event %d has mismatched turn id %q, want %q", i, evt.Meta.TurnID, turnID) + } + if evt.Meta.SessionKey != "session-1" { + t.Fatalf("event %d has session key %q, want session-1", i, evt.Meta.SessionKey) + } + } + + startPayload, ok := events[0].Payload.(TurnStartPayload) + if !ok { + t.Fatalf("expected TurnStartPayload, got %T", events[0].Payload) + } + if startPayload.UserMessage != "run tool" { + t.Fatalf("expected user message 'run tool', got %q", startPayload.UserMessage) + } + + toolStartPayload, ok := events[3].Payload.(ToolExecStartPayload) + if !ok { + t.Fatalf("expected ToolExecStartPayload, got %T", events[3].Payload) + } + if toolStartPayload.Tool != "mock_custom" { + t.Fatalf("expected tool name mock_custom, got %q", toolStartPayload.Tool) + } + + toolEndPayload, ok := events[4].Payload.(ToolExecEndPayload) + if !ok { + t.Fatalf("expected ToolExecEndPayload, got %T", events[4].Payload) + } + if toolEndPayload.Tool != "mock_custom" { + t.Fatalf("expected tool end payload for mock_custom, got %q", toolEndPayload.Tool) + } + if toolEndPayload.IsError { + t.Fatal("expected mock_custom tool to succeed") + } + + turnEndPayload, ok := events[len(events)-1].Payload.(TurnEndPayload) + if !ok { + t.Fatalf("expected TurnEndPayload, got %T", events[len(events)-1].Payload) + } + if turnEndPayload.Status != TurnEndStatusCompleted { + t.Fatalf("expected completed turn, got %q", turnEndPayload.Status) + } + if turnEndPayload.Iterations != 2 { + t.Fatalf("expected 2 iterations, got %d", turnEndPayload.Iterations) + } +} + +func TestAgentLoop_EmitsSteeringAndSkippedToolEvents(t *testing.T) { + tmpDir, err := os.MkdirTemp("", "agent-eventbus-steering-*") + if err != nil { + t.Fatalf("failed to create temp dir: %v", err) + } + defer os.RemoveAll(tmpDir) + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: tmpDir, + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + }, + }, + } + + tool1ExecCh := make(chan struct{}) + tool1 := &slowTool{name: "tool_one", duration: 50 * time.Millisecond, execCh: tool1ExecCh} + tool2 := &slowTool{name: "tool_two", duration: 50 * time.Millisecond} + + provider := &toolCallProvider{ + toolCalls: []providers.ToolCall{ + { + ID: "call_1", + Type: "function", + Name: "tool_one", + Function: &providers.FunctionCall{ + Name: "tool_one", + Arguments: "{}", + }, + Arguments: map[string]any{}, + }, + { + ID: "call_2", + Type: "function", + Name: "tool_two", + Function: &providers.FunctionCall{ + Name: "tool_two", + Arguments: "{}", + }, + Arguments: map[string]any{}, + }, + }, + finalResp: "steered response", + } + + msgBus := bus.NewMessageBus() + al := NewAgentLoop(cfg, msgBus, provider) + al.RegisterTool(tool1) + al.RegisterTool(tool2) + + sub := al.SubscribeEvents(32) + defer al.UnsubscribeEvents(sub.ID) + + resultCh := make(chan string, 1) + go func() { + resp, _ := al.ProcessDirectWithChannel(context.Background(), "do something", "test-session", "test", "chat1") + resultCh <- resp + }() + + select { + case <-tool1ExecCh: + case <-time.After(2 * time.Second): + t.Fatal("timeout waiting for tool_one to start") + } + + if err := al.Steer(providers.Message{Role: "user", Content: "change course"}); err != nil { + t.Fatalf("Steer failed: %v", err) + } + + select { + case resp := <-resultCh: + if resp != "steered response" { + t.Fatalf("expected steered response, got %q", resp) + } + case <-time.After(5 * time.Second): + t.Fatal("timeout waiting for steered response") + } + + events := collectEventStream(sub.C) + steeringEvt, ok := findEvent(events, EventKindSteeringInjected) + if !ok { + t.Fatal("expected steering injected event") + } + steeringPayload, ok := steeringEvt.Payload.(SteeringInjectedPayload) + if !ok { + t.Fatalf("expected SteeringInjectedPayload, got %T", steeringEvt.Payload) + } + if steeringPayload.Count != 1 { + t.Fatalf("expected 1 steering message, got %d", steeringPayload.Count) + } + + skippedEvt, ok := findEvent(events, EventKindToolExecSkipped) + if !ok { + t.Fatal("expected skipped tool event") + } + skippedPayload, ok := skippedEvt.Payload.(ToolExecSkippedPayload) + if !ok { + t.Fatalf("expected ToolExecSkippedPayload, got %T", skippedEvt.Payload) + } + if skippedPayload.Tool != "tool_two" { + t.Fatalf("expected skipped tool_two, got %q", skippedPayload.Tool) + } + + interruptEvt, ok := findEvent(events, EventKindInterruptReceived) + if !ok { + t.Fatal("expected interrupt received event") + } + interruptPayload, ok := interruptEvt.Payload.(InterruptReceivedPayload) + if !ok { + t.Fatalf("expected InterruptReceivedPayload, got %T", interruptEvt.Payload) + } + if interruptPayload.Role != "user" { + t.Fatalf("expected interrupt role user, got %q", interruptPayload.Role) + } + if interruptPayload.Kind != InterruptKindSteering { + t.Fatalf("expected steering interrupt kind, got %q", interruptPayload.Kind) + } + if interruptPayload.ContentLen != len("change course") { + t.Fatalf("expected interrupt content len %d, got %d", len("change course"), interruptPayload.ContentLen) + } +} + +func TestAgentLoop_EmitsContextCompressEventOnRetry(t *testing.T) { + tmpDir, err := os.MkdirTemp("", "agent-eventbus-compress-*") + if err != nil { + t.Fatalf("failed to create temp dir: %v", err) + } + defer os.RemoveAll(tmpDir) + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: tmpDir, + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + }, + }, + } + + contextErr := stringError("InvalidParameter: Total tokens of image and text exceed max message tokens") + provider := &failFirstMockProvider{ + failures: 1, + failError: contextErr, + successResp: "Recovered from context error", + } + msgBus := bus.NewMessageBus() + al := NewAgentLoop(cfg, msgBus, provider) + defaultAgent := al.registry.GetDefaultAgent() + if defaultAgent == nil { + t.Fatal("expected default agent") + } + + defaultAgent.Sessions.SetHistory("session-1", []providers.Message{ + {Role: "user", Content: "Old message 1"}, + {Role: "assistant", Content: "Old response 1"}, + {Role: "user", Content: "Old message 2"}, + {Role: "assistant", Content: "Old response 2"}, + {Role: "user", Content: "Trigger message"}, + }) + + sub := al.SubscribeEvents(16) + defer al.UnsubscribeEvents(sub.ID) + + resp, err := al.runAgentLoop(context.Background(), defaultAgent, processOptions{ + SessionKey: "session-1", + Channel: "cli", + ChatID: "direct", + UserMessage: "Trigger message", + DefaultResponse: defaultResponse, + EnableSummary: false, + SendResponse: false, + }) + if err != nil { + t.Fatalf("runAgentLoop failed: %v", err) + } + if resp != "Recovered from context error" { + t.Fatalf("expected retry success, got %q", resp) + } + + events := collectEventStream(sub.C) + retryEvt, ok := findEvent(events, EventKindLLMRetry) + if !ok { + t.Fatal("expected llm retry event") + } + retryPayload, ok := retryEvt.Payload.(LLMRetryPayload) + if !ok { + t.Fatalf("expected LLMRetryPayload, got %T", retryEvt.Payload) + } + if retryPayload.Reason != "context_limit" { + t.Fatalf("expected context_limit retry reason, got %q", retryPayload.Reason) + } + if retryPayload.Attempt != 1 { + t.Fatalf("expected retry attempt 1, got %d", retryPayload.Attempt) + } + + compressEvt, ok := findEvent(events, EventKindContextCompress) + if !ok { + t.Fatal("expected context compress event") + } + payload, ok := compressEvt.Payload.(ContextCompressPayload) + if !ok { + t.Fatalf("expected ContextCompressPayload, got %T", compressEvt.Payload) + } + if payload.Reason != ContextCompressReasonRetry { + t.Fatalf("expected retry compress reason, got %q", payload.Reason) + } + if payload.DroppedMessages == 0 { + t.Fatal("expected dropped messages to be recorded") + } +} + +func TestAgentLoop_EmitsSessionSummarizeEvent(t *testing.T) { + tmpDir, err := os.MkdirTemp("", "agent-eventbus-summary-*") + if err != nil { + t.Fatalf("failed to create temp dir: %v", err) + } + defer os.RemoveAll(tmpDir) + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: tmpDir, + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + ContextWindow: 8000, + SummarizeMessageThreshold: 2, + SummarizeTokenPercent: 75, + }, + }, + } + + msgBus := bus.NewMessageBus() + al := NewAgentLoop(cfg, msgBus, &simpleMockProvider{response: "summary text"}) + defaultAgent := al.registry.GetDefaultAgent() + if defaultAgent == nil { + t.Fatal("expected default agent") + } + + defaultAgent.Sessions.SetHistory("session-1", []providers.Message{ + {Role: "user", Content: "Question one"}, + {Role: "assistant", Content: "Answer one"}, + {Role: "user", Content: "Question two"}, + {Role: "assistant", Content: "Answer two"}, + {Role: "user", Content: "Question three"}, + {Role: "assistant", Content: "Answer three"}, + }) + + sub := al.SubscribeEvents(16) + defer al.UnsubscribeEvents(sub.ID) + + turnScope := al.newTurnEventScope(defaultAgent.ID, "session-1") + al.summarizeSession(defaultAgent, "session-1", turnScope) + + events := collectEventStream(sub.C) + summaryEvt, ok := findEvent(events, EventKindSessionSummarize) + if !ok { + t.Fatal("expected session summarize event") + } + payload, ok := summaryEvt.Payload.(SessionSummarizePayload) + if !ok { + t.Fatalf("expected SessionSummarizePayload, got %T", summaryEvt.Payload) + } + if payload.SummaryLen == 0 { + t.Fatal("expected non-empty summary length") + } +} + +func TestAgentLoop_EmitsFollowUpQueuedEvent(t *testing.T) { + tmpDir, err := os.MkdirTemp("", "agent-eventbus-followup-*") + if err != nil { + t.Fatalf("failed to create temp dir: %v", err) + } + defer os.RemoveAll(tmpDir) + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: tmpDir, + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + }, + }, + } + + provider := &toolCallProvider{ + toolCalls: []providers.ToolCall{ + { + ID: "call_async_1", + Type: "function", + Name: "async_followup", + Function: &providers.FunctionCall{ + Name: "async_followup", + Arguments: "{}", + }, + Arguments: map[string]any{}, + }, + }, + finalResp: "async launched", + } + + msgBus := bus.NewMessageBus() + al := NewAgentLoop(cfg, msgBus, provider) + doneCh := make(chan struct{}) + al.RegisterTool(&asyncFollowUpTool{ + name: "async_followup", + followUpText: "background result", + completionSig: doneCh, + }) + defaultAgent := al.registry.GetDefaultAgent() + if defaultAgent == nil { + t.Fatal("expected default agent") + } + + sub := al.SubscribeEvents(32) + defer al.UnsubscribeEvents(sub.ID) + + resp, err := al.runAgentLoop(context.Background(), defaultAgent, processOptions{ + SessionKey: "session-1", + Channel: "cli", + ChatID: "direct", + UserMessage: "run async tool", + DefaultResponse: defaultResponse, + EnableSummary: false, + SendResponse: false, + }) + if err != nil { + t.Fatalf("runAgentLoop failed: %v", err) + } + if resp != "async launched" { + t.Fatalf("expected final response 'async launched', got %q", resp) + } + + select { + case <-doneCh: + case <-time.After(2 * time.Second): + t.Fatal("timeout waiting for async tool completion") + } + + followUpEvt := waitForEvent(t, sub.C, 2*time.Second, func(evt Event) bool { + return evt.Kind == EventKindFollowUpQueued + }) + payload, ok := followUpEvt.Payload.(FollowUpQueuedPayload) + if !ok { + t.Fatalf("expected FollowUpQueuedPayload, got %T", followUpEvt.Payload) + } + if payload.SourceTool != "async_followup" { + t.Fatalf("expected source tool async_followup, got %q", payload.SourceTool) + } + if payload.Channel != "cli" { + t.Fatalf("expected channel cli, got %q", payload.Channel) + } + if payload.ChatID != "direct" { + t.Fatalf("expected chat id direct, got %q", payload.ChatID) + } + if payload.ContentLen != len("background result") { + t.Fatalf("expected content len %d, got %d", len("background result"), payload.ContentLen) + } + if followUpEvt.Meta.SessionKey != "session-1" { + t.Fatalf("expected session key session-1, got %q", followUpEvt.Meta.SessionKey) + } + if followUpEvt.Meta.TurnID == "" { + t.Fatal("expected follow-up event to include turn id") + } +} + +func collectEventStream(ch <-chan Event) []Event { + var events []Event + for { + select { + case evt, ok := <-ch: + if !ok { + return events + } + events = append(events, evt) + default: + return events + } + } +} + +func waitForEvent(t *testing.T, ch <-chan Event, timeout time.Duration, match func(Event) bool) Event { + t.Helper() + + timer := time.NewTimer(timeout) + defer timer.Stop() + + for { + select { + case evt, ok := <-ch: + if !ok { + t.Fatal("event stream closed before expected event arrived") + } + if match(evt) { + return evt + } + case <-timer.C: + t.Fatal("timed out waiting for expected event") + } + } +} + +func findEvent(events []Event, kind EventKind) (Event, bool) { + for _, evt := range events { + if evt.Kind == kind { + return evt, true + } + } + return Event{}, false +} + +type stringError string + +func (e stringError) Error() string { + return string(e) +} + +type asyncFollowUpTool struct { + name string + followUpText string + completionSig chan struct{} +} + +func (t *asyncFollowUpTool) Name() string { + return t.name +} + +func (t *asyncFollowUpTool) Description() string { + return "async follow-up tool for testing" +} + +func (t *asyncFollowUpTool) Parameters() map[string]any { + return map[string]any{ + "type": "object", + "properties": map[string]any{}, + } +} + +func (t *asyncFollowUpTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult { + return tools.AsyncResult("async follow-up scheduled") +} + +func (t *asyncFollowUpTool) ExecuteAsync( + ctx context.Context, + args map[string]any, + cb tools.AsyncCallback, +) *tools.ToolResult { + go func() { + cb(ctx, &tools.ToolResult{ForLLM: t.followUpText}) + if t.completionSig != nil { + close(t.completionSig) + } + }() + return tools.AsyncResult("async follow-up scheduled") +} + +var ( + _ tools.Tool = (*mockCustomTool)(nil) + _ tools.AsyncExecutor = (*asyncFollowUpTool)(nil) +) diff --git a/pkg/agent/events.go b/pkg/agent/events.go new file mode 100644 index 00000000..f4562b36 --- /dev/null +++ b/pkg/agent/events.go @@ -0,0 +1,271 @@ +package agent + +import ( + "fmt" + "time" +) + +// EventKind identifies a structured agent-loop event. +type EventKind uint8 + +const ( + // EventKindTurnStart is emitted when a turn begins processing. + EventKindTurnStart EventKind = iota + // EventKindTurnEnd is emitted when a turn finishes, successfully or with an error. + EventKindTurnEnd + // EventKindLLMRequest is emitted before a provider chat request is made. + EventKindLLMRequest + // EventKindLLMDelta is emitted when a streaming provider yields a partial delta. + EventKindLLMDelta + // EventKindLLMResponse is emitted after a provider chat response is received. + EventKindLLMResponse + // EventKindLLMRetry is emitted when an LLM request is retried. + EventKindLLMRetry + // EventKindContextCompress is emitted when session history is forcibly compressed. + EventKindContextCompress + // EventKindSessionSummarize is emitted when asynchronous summarization completes. + EventKindSessionSummarize + // EventKindToolExecStart is emitted immediately before a tool executes. + EventKindToolExecStart + // EventKindToolExecEnd is emitted immediately after a tool finishes executing. + EventKindToolExecEnd + // EventKindToolExecSkipped is emitted when a queued tool call is skipped. + EventKindToolExecSkipped + // EventKindSteeringInjected is emitted when queued steering is injected into context. + EventKindSteeringInjected + // EventKindFollowUpQueued is emitted when an async tool queues a follow-up system message. + EventKindFollowUpQueued + // EventKindInterruptReceived is emitted when a soft interrupt message is accepted. + EventKindInterruptReceived + // EventKindSubTurnSpawn is emitted when a sub-turn is spawned. + EventKindSubTurnSpawn + // EventKindSubTurnEnd is emitted when a sub-turn finishes. + EventKindSubTurnEnd + // EventKindSubTurnResultDelivered is emitted when a sub-turn result is delivered. + EventKindSubTurnResultDelivered + // EventKindSubTurnOrphan is emitted when a sub-turn result cannot be delivered. + EventKindSubTurnOrphan + // EventKindError is emitted when a turn encounters an execution error. + EventKindError + + eventKindCount +) + +var eventKindNames = [...]string{ + "turn_start", + "turn_end", + "llm_request", + "llm_delta", + "llm_response", + "llm_retry", + "context_compress", + "session_summarize", + "tool_exec_start", + "tool_exec_end", + "tool_exec_skipped", + "steering_injected", + "follow_up_queued", + "interrupt_received", + "subturn_spawn", + "subturn_end", + "subturn_result_delivered", + "subturn_orphan", + "error", +} + +// String returns the stable string form of an EventKind. +func (k EventKind) String() string { + if k >= eventKindCount { + return fmt.Sprintf("event_kind(%d)", k) + } + return eventKindNames[k] +} + +// Event is the structured envelope broadcast by the agent EventBus. +type Event struct { + Kind EventKind + Time time.Time + Meta EventMeta + Payload any +} + +// EventMeta contains correlation fields shared by all agent-loop events. +type EventMeta struct { + AgentID string + TurnID string + ParentTurnID string + SessionKey string + Iteration int + TracePath string + Source string +} + +// TurnEndStatus describes the terminal state of a turn. +type TurnEndStatus string + +const ( + // TurnEndStatusCompleted indicates the turn finished normally. + TurnEndStatusCompleted TurnEndStatus = "completed" + // TurnEndStatusError indicates the turn ended because of an error. + TurnEndStatusError TurnEndStatus = "error" + // TurnEndStatusAborted indicates the turn was hard-aborted and rolled back. + TurnEndStatusAborted TurnEndStatus = "aborted" +) + +// TurnStartPayload describes the start of a turn. +type TurnStartPayload struct { + Channel string + ChatID string + UserMessage string + MediaCount int +} + +// TurnEndPayload describes the completion of a turn. +type TurnEndPayload struct { + Status TurnEndStatus + Iterations int + Duration time.Duration + FinalContentLen int +} + +// LLMRequestPayload describes an outbound LLM request. +type LLMRequestPayload struct { + Model string + MessagesCount int + ToolsCount int + MaxTokens int + Temperature float64 +} + +// LLMResponsePayload describes an inbound LLM response. +type LLMResponsePayload struct { + ContentLen int + ToolCalls int + HasReasoning bool +} + +// LLMDeltaPayload describes a streamed LLM delta. +type LLMDeltaPayload struct { + ContentDeltaLen int + ReasoningDeltaLen int +} + +// LLMRetryPayload describes a retry of an LLM request. +type LLMRetryPayload struct { + Attempt int + MaxRetries int + Reason string + Error string + Backoff time.Duration +} + +// ContextCompressReason identifies why emergency compression ran. +type ContextCompressReason string + +const ( + // ContextCompressReasonProactive indicates compression before the first LLM call. + ContextCompressReasonProactive ContextCompressReason = "proactive_budget" + // ContextCompressReasonRetry indicates compression during context-error retry handling. + ContextCompressReasonRetry ContextCompressReason = "llm_retry" +) + +// ContextCompressPayload describes a forced history compression. +type ContextCompressPayload struct { + Reason ContextCompressReason + DroppedMessages int + RemainingMessages int +} + +// SessionSummarizePayload describes a completed async session summarization. +type SessionSummarizePayload struct { + SummarizedMessages int + KeptMessages int + SummaryLen int + OmittedOversized bool +} + +// ToolExecStartPayload describes a tool execution request. +type ToolExecStartPayload struct { + Tool string + Arguments map[string]any +} + +// ToolExecEndPayload describes the outcome of a tool execution. +type ToolExecEndPayload struct { + Tool string + Duration time.Duration + ForLLMLen int + ForUserLen int + IsError bool + Async bool +} + +// ToolExecSkippedPayload describes a skipped tool call. +type ToolExecSkippedPayload struct { + Tool string + Reason string +} + +// SteeringInjectedPayload describes steering messages appended before the next LLM call. +type SteeringInjectedPayload struct { + Count int + TotalContentLen int +} + +// FollowUpQueuedPayload describes an async follow-up queued back into the inbound bus. +type FollowUpQueuedPayload struct { + SourceTool string + Channel string + ChatID string + ContentLen int +} + +type InterruptKind string + +const ( + InterruptKindSteering InterruptKind = "steering" + InterruptKindGraceful InterruptKind = "graceful" + InterruptKindHard InterruptKind = "hard_abort" +) + +// InterruptReceivedPayload describes accepted turn-control input. +type InterruptReceivedPayload struct { + Kind InterruptKind + Role string + ContentLen int + QueueDepth int + HintLen int +} + +// SubTurnSpawnPayload describes the creation of a child turn. +type SubTurnSpawnPayload struct { + AgentID string + Label string + ParentTurnID string +} + +// SubTurnEndPayload describes the completion of a child turn. +type SubTurnEndPayload struct { + AgentID string + Status string +} + +// SubTurnResultDeliveredPayload describes delivery of a sub-turn result. +type SubTurnResultDeliveredPayload struct { + TargetChannel string + TargetChatID string + ContentLen int +} + +// SubTurnOrphanPayload describes a sub-turn result that could not be delivered. +type SubTurnOrphanPayload struct { + ParentTurnID string + ChildTurnID string + Reason string +} + +// ErrorPayload describes an execution error inside the agent loop. +type ErrorPayload struct { + Stage string + Message string +} diff --git a/pkg/agent/hook_mount.go b/pkg/agent/hook_mount.go new file mode 100644 index 00000000..c92145f1 --- /dev/null +++ b/pkg/agent/hook_mount.go @@ -0,0 +1,317 @@ +package agent + +import ( + "context" + "fmt" + "sort" + "sync" + "time" + + "github.com/sipeed/picoclaw/pkg/config" +) + +type hookRuntime struct { + initOnce sync.Once + mu sync.Mutex + initErr error + mounted []string +} + +func (r *hookRuntime) setInitErr(err error) { + r.mu.Lock() + r.initErr = err + r.mu.Unlock() +} + +func (r *hookRuntime) getInitErr() error { + r.mu.Lock() + defer r.mu.Unlock() + return r.initErr +} + +func (r *hookRuntime) setMounted(names []string) { + r.mu.Lock() + r.mounted = append([]string(nil), names...) + r.mu.Unlock() +} + +func (r *hookRuntime) reset(al *AgentLoop) { + r.mu.Lock() + names := append([]string(nil), r.mounted...) + r.mounted = nil + r.initErr = nil + r.initOnce = sync.Once{} + r.mu.Unlock() + + for _, name := range names { + al.UnmountHook(name) + } +} + +// BuiltinHookFactory constructs an in-process hook from config. +type BuiltinHookFactory func(ctx context.Context, spec config.BuiltinHookConfig) (any, error) + +var ( + builtinHookRegistryMu sync.RWMutex + builtinHookRegistry = map[string]BuiltinHookFactory{} +) + +// RegisterBuiltinHook registers a named in-process hook factory for config-driven mounting. +func RegisterBuiltinHook(name string, factory BuiltinHookFactory) error { + if name == "" { + return fmt.Errorf("builtin hook name is required") + } + if factory == nil { + return fmt.Errorf("builtin hook %q factory is nil", name) + } + + builtinHookRegistryMu.Lock() + defer builtinHookRegistryMu.Unlock() + + if _, exists := builtinHookRegistry[name]; exists { + return fmt.Errorf("builtin hook %q is already registered", name) + } + builtinHookRegistry[name] = factory + return nil +} + +func unregisterBuiltinHook(name string) { + if name == "" { + return + } + builtinHookRegistryMu.Lock() + delete(builtinHookRegistry, name) + builtinHookRegistryMu.Unlock() +} + +func lookupBuiltinHook(name string) (BuiltinHookFactory, bool) { + builtinHookRegistryMu.RLock() + defer builtinHookRegistryMu.RUnlock() + + factory, ok := builtinHookRegistry[name] + return factory, ok +} + +func configureHookManagerFromConfig(hm *HookManager, cfg *config.Config) { + if hm == nil || cfg == nil { + return + } + hm.ConfigureTimeouts( + hookTimeoutFromMS(cfg.Hooks.Defaults.ObserverTimeoutMS), + hookTimeoutFromMS(cfg.Hooks.Defaults.InterceptorTimeoutMS), + hookTimeoutFromMS(cfg.Hooks.Defaults.ApprovalTimeoutMS), + ) +} + +func hookTimeoutFromMS(ms int) time.Duration { + if ms <= 0 { + return 0 + } + return time.Duration(ms) * time.Millisecond +} + +func (al *AgentLoop) ensureHooksInitialized(ctx context.Context) error { + if al == nil || al.cfg == nil || al.hooks == nil { + return nil + } + + al.hookRuntime.initOnce.Do(func() { + al.hookRuntime.setInitErr(al.loadConfiguredHooks(ctx)) + }) + + return al.hookRuntime.getInitErr() +} + +func (al *AgentLoop) loadConfiguredHooks(ctx context.Context) (err error) { + if al == nil || al.cfg == nil || !al.cfg.Hooks.Enabled { + return nil + } + + mounted := make([]string, 0) + defer func() { + if err != nil { + for _, name := range mounted { + al.UnmountHook(name) + } + return + } + al.hookRuntime.setMounted(mounted) + }() + + builtinNames := enabledBuiltinHookNames(al.cfg.Hooks.Builtins) + for _, name := range builtinNames { + spec := al.cfg.Hooks.Builtins[name] + factory, ok := lookupBuiltinHook(name) + if !ok { + return fmt.Errorf("builtin hook %q is not registered", name) + } + + hook, factoryErr := factory(ctx, spec) + if factoryErr != nil { + return fmt.Errorf("build builtin hook %q: %w", name, factoryErr) + } + if err := al.MountHook(HookRegistration{ + Name: name, + Priority: spec.Priority, + Source: HookSourceInProcess, + Hook: hook, + }); err != nil { + return fmt.Errorf("mount builtin hook %q: %w", name, err) + } + mounted = append(mounted, name) + } + + processNames := enabledProcessHookNames(al.cfg.Hooks.Processes) + for _, name := range processNames { + spec := al.cfg.Hooks.Processes[name] + opts, buildErr := processHookOptionsFromConfig(spec) + if buildErr != nil { + return fmt.Errorf("configure process hook %q: %w", name, buildErr) + } + + processHook, buildErr := NewProcessHook(ctx, name, opts) + if buildErr != nil { + return fmt.Errorf("start process hook %q: %w", name, buildErr) + } + if err := al.MountHook(HookRegistration{ + Name: name, + Priority: spec.Priority, + Source: HookSourceProcess, + Hook: processHook, + }); err != nil { + _ = processHook.Close() + return fmt.Errorf("mount process hook %q: %w", name, err) + } + mounted = append(mounted, name) + } + + return nil +} + +func enabledBuiltinHookNames(specs map[string]config.BuiltinHookConfig) []string { + if len(specs) == 0 { + return nil + } + + names := make([]string, 0, len(specs)) + for name, spec := range specs { + if spec.Enabled { + names = append(names, name) + } + } + sort.Strings(names) + return names +} + +func enabledProcessHookNames(specs map[string]config.ProcessHookConfig) []string { + if len(specs) == 0 { + return nil + } + + names := make([]string, 0, len(specs)) + for name, spec := range specs { + if spec.Enabled { + names = append(names, name) + } + } + sort.Strings(names) + return names +} + +func processHookOptionsFromConfig(spec config.ProcessHookConfig) (ProcessHookOptions, error) { + transport := spec.Transport + if transport == "" { + transport = "stdio" + } + if transport != "stdio" { + return ProcessHookOptions{}, fmt.Errorf("unsupported transport %q", transport) + } + if len(spec.Command) == 0 { + return ProcessHookOptions{}, fmt.Errorf("command is required") + } + + opts := ProcessHookOptions{ + Command: append([]string(nil), spec.Command...), + Dir: spec.Dir, + Env: processHookEnvFromMap(spec.Env), + } + + observeKinds, observeEnabled, err := processHookObserveKindsFromConfig(spec.Observe) + if err != nil { + return ProcessHookOptions{}, err + } + opts.Observe = observeEnabled + opts.ObserveKinds = observeKinds + + for _, intercept := range spec.Intercept { + switch intercept { + case "before_llm", "after_llm": + opts.InterceptLLM = true + case "before_tool", "after_tool": + opts.InterceptTool = true + case "approve_tool": + opts.ApproveTool = true + case "": + continue + default: + return ProcessHookOptions{}, fmt.Errorf("unsupported intercept %q", intercept) + } + } + + if !opts.Observe && !opts.InterceptLLM && !opts.InterceptTool && !opts.ApproveTool { + return ProcessHookOptions{}, fmt.Errorf("no hook modes enabled") + } + + return opts, nil +} + +func processHookEnvFromMap(envMap map[string]string) []string { + if len(envMap) == 0 { + return nil + } + + keys := make([]string, 0, len(envMap)) + for key := range envMap { + keys = append(keys, key) + } + sort.Strings(keys) + + env := make([]string, 0, len(keys)) + for _, key := range keys { + env = append(env, key+"="+envMap[key]) + } + return env +} + +func processHookObserveKindsFromConfig(observe []string) ([]string, bool, error) { + if len(observe) == 0 { + return nil, false, nil + } + + validKinds := validHookEventKinds() + normalized := make([]string, 0, len(observe)) + for _, kind := range observe { + switch kind { + case "", "*", "all": + return nil, true, nil + default: + if _, ok := validKinds[kind]; !ok { + return nil, false, fmt.Errorf("unsupported observe event %q", kind) + } + normalized = append(normalized, kind) + } + } + + if len(normalized) == 0 { + return nil, false, nil + } + return normalized, true, nil +} + +func validHookEventKinds() map[string]struct{} { + kinds := make(map[string]struct{}, int(eventKindCount)) + for kind := EventKind(0); kind < eventKindCount; kind++ { + kinds[kind.String()] = struct{}{} + } + return kinds +} diff --git a/pkg/agent/hook_mount_test.go b/pkg/agent/hook_mount_test.go new file mode 100644 index 00000000..a9d8f27c --- /dev/null +++ b/pkg/agent/hook_mount_test.go @@ -0,0 +1,179 @@ +package agent + +import ( + "context" + "encoding/json" + "path/filepath" + "testing" + + "github.com/sipeed/picoclaw/pkg/bus" + "github.com/sipeed/picoclaw/pkg/config" +) + +type builtinAutoHookConfig struct { + Model string `json:"model"` + Suffix string `json:"suffix"` +} + +type builtinAutoHook struct { + model string + suffix string +} + +func (h *builtinAutoHook) BeforeLLM( + ctx context.Context, + req *LLMHookRequest, +) (*LLMHookRequest, HookDecision, error) { + next := req.Clone() + next.Model = h.model + return next, HookDecision{Action: HookActionModify}, nil +} + +func (h *builtinAutoHook) AfterLLM( + ctx context.Context, + resp *LLMHookResponse, +) (*LLMHookResponse, HookDecision, error) { + next := resp.Clone() + if next.Response != nil { + next.Response.Content += h.suffix + } + return next, HookDecision{Action: HookActionModify}, nil +} + +func newConfiguredHookLoop(t *testing.T, provider *llmHookTestProvider, hooks config.HooksConfig) *AgentLoop { + t.Helper() + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: t.TempDir(), + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + }, + }, + Hooks: hooks, + } + + return NewAgentLoop(cfg, bus.NewMessageBus(), provider) +} + +func TestAgentLoop_ProcessDirectWithChannel_AutoMountsBuiltinHook(t *testing.T) { + const hookName = "test-auto-builtin-hook" + + if err := RegisterBuiltinHook(hookName, func( + ctx context.Context, + spec config.BuiltinHookConfig, + ) (any, error) { + var hookCfg builtinAutoHookConfig + if len(spec.Config) > 0 { + if err := json.Unmarshal(spec.Config, &hookCfg); err != nil { + return nil, err + } + } + return &builtinAutoHook{ + model: hookCfg.Model, + suffix: hookCfg.Suffix, + }, nil + }); err != nil { + t.Fatalf("RegisterBuiltinHook failed: %v", err) + } + t.Cleanup(func() { + unregisterBuiltinHook(hookName) + }) + + rawCfg, err := json.Marshal(builtinAutoHookConfig{ + Model: "builtin-model", + Suffix: "|builtin", + }) + if err != nil { + t.Fatalf("json.Marshal failed: %v", err) + } + + provider := &llmHookTestProvider{} + al := newConfiguredHookLoop(t, provider, config.HooksConfig{ + Enabled: true, + Builtins: map[string]config.BuiltinHookConfig{ + hookName: { + Enabled: true, + Config: rawCfg, + }, + }, + }) + defer al.Close() + + resp, err := al.ProcessDirectWithChannel(context.Background(), "hello", "session-1", "cli", "direct") + if err != nil { + t.Fatalf("ProcessDirectWithChannel failed: %v", err) + } + if resp != "provider content|builtin" { + t.Fatalf("expected builtin-hooked content, got %q", resp) + } + + provider.mu.Lock() + lastModel := provider.lastModel + provider.mu.Unlock() + if lastModel != "builtin-model" { + t.Fatalf("expected builtin model, got %q", lastModel) + } +} + +func TestAgentLoop_ProcessDirectWithChannel_AutoMountsProcessHook(t *testing.T) { + provider := &llmHookTestProvider{} + eventLog := filepath.Join(t.TempDir(), "events.log") + + al := newConfiguredHookLoop(t, provider, config.HooksConfig{ + Enabled: true, + Processes: map[string]config.ProcessHookConfig{ + "ipc-auto": { + Enabled: true, + Command: processHookHelperCommand(), + Env: map[string]string{ + "PICOCLAW_HOOK_HELPER": "1", + "PICOCLAW_HOOK_MODE": "rewrite", + "PICOCLAW_HOOK_EVENT_LOG": eventLog, + }, + Observe: []string{"turn_end"}, + Intercept: []string{"before_llm", "after_llm"}, + }, + }, + }) + defer al.Close() + + resp, err := al.ProcessDirectWithChannel(context.Background(), "hello", "session-1", "cli", "direct") + if err != nil { + t.Fatalf("ProcessDirectWithChannel failed: %v", err) + } + if resp != "provider content|ipc" { + t.Fatalf("expected process-hooked content, got %q", resp) + } + + provider.mu.Lock() + lastModel := provider.lastModel + provider.mu.Unlock() + if lastModel != "process-model" { + t.Fatalf("expected process model, got %q", lastModel) + } + + waitForFileContains(t, eventLog, "turn_end") +} + +func TestAgentLoop_ProcessDirectWithChannel_InvalidConfiguredHookFails(t *testing.T) { + provider := &llmHookTestProvider{} + al := newConfiguredHookLoop(t, provider, config.HooksConfig{ + Enabled: true, + Processes: map[string]config.ProcessHookConfig{ + "bad-hook": { + Enabled: true, + Command: processHookHelperCommand(), + Intercept: []string{"not_supported"}, + }, + }, + }) + defer al.Close() + + _, err := al.ProcessDirectWithChannel(context.Background(), "hello", "session-1", "cli", "direct") + if err == nil { + t.Fatal("expected invalid configured hook error") + } +} diff --git a/pkg/agent/hook_process.go b/pkg/agent/hook_process.go new file mode 100644 index 00000000..e5632913 --- /dev/null +++ b/pkg/agent/hook_process.go @@ -0,0 +1,511 @@ +package agent + +import ( + "bufio" + "context" + "encoding/json" + "fmt" + "io" + "os" + "os/exec" + "sync" + "sync/atomic" + "time" + + "github.com/sipeed/picoclaw/pkg/logger" +) + +const ( + processHookJSONRPCVersion = "2.0" + processHookReadBufferSize = 1024 * 1024 + processHookCloseTimeout = 2 * time.Second +) + +type ProcessHookOptions struct { + Command []string + Dir string + Env []string + Observe bool + ObserveKinds []string + InterceptLLM bool + InterceptTool bool + ApproveTool bool +} + +type ProcessHook struct { + name string + opts ProcessHookOptions + + cmd *exec.Cmd + stdin io.WriteCloser + observeKinds map[string]struct{} + + writeMu sync.Mutex + + pendingMu sync.Mutex + pending map[uint64]chan processHookRPCMessage + nextID atomic.Uint64 + + closed atomic.Bool + done chan struct{} + closeErr error + closeMu sync.Mutex + closeOnce sync.Once +} + +type processHookRPCMessage struct { + JSONRPC string `json:"jsonrpc,omitempty"` + ID uint64 `json:"id,omitempty"` + Method string `json:"method,omitempty"` + Params json.RawMessage `json:"params,omitempty"` + Result json.RawMessage `json:"result,omitempty"` + Error *processHookRPCError `json:"error,omitempty"` +} + +type processHookRPCError struct { + Code int `json:"code"` + Message string `json:"message"` +} + +type processHookHelloParams struct { + Name string `json:"name"` + Version int `json:"version"` + Modes []string `json:"modes,omitempty"` +} + +type processHookDecisionResponse struct { + Action HookAction `json:"action"` + Reason string `json:"reason,omitempty"` +} + +type processHookBeforeLLMResponse struct { + processHookDecisionResponse + Request *LLMHookRequest `json:"request,omitempty"` +} + +type processHookAfterLLMResponse struct { + processHookDecisionResponse + Response *LLMHookResponse `json:"response,omitempty"` +} + +type processHookBeforeToolResponse struct { + processHookDecisionResponse + Call *ToolCallHookRequest `json:"call,omitempty"` +} + +type processHookAfterToolResponse struct { + processHookDecisionResponse + Result *ToolResultHookResponse `json:"result,omitempty"` +} + +func NewProcessHook(ctx context.Context, name string, opts ProcessHookOptions) (*ProcessHook, error) { + if len(opts.Command) == 0 { + return nil, fmt.Errorf("process hook command is required") + } + + cmd := exec.Command(opts.Command[0], opts.Command[1:]...) + cmd.Dir = opts.Dir + if len(opts.Env) > 0 { + cmd.Env = append(os.Environ(), opts.Env...) + } + stdin, err := cmd.StdinPipe() + if err != nil { + return nil, fmt.Errorf("create process hook stdin: %w", err) + } + stdout, err := cmd.StdoutPipe() + if err != nil { + return nil, fmt.Errorf("create process hook stdout: %w", err) + } + stderr, err := cmd.StderrPipe() + if err != nil { + return nil, fmt.Errorf("create process hook stderr: %w", err) + } + if err := cmd.Start(); err != nil { + return nil, fmt.Errorf("start process hook: %w", err) + } + + ph := &ProcessHook{ + name: name, + opts: opts, + cmd: cmd, + stdin: stdin, + observeKinds: newProcessHookObserveKinds(opts.ObserveKinds), + pending: make(map[uint64]chan processHookRPCMessage), + done: make(chan struct{}), + } + + go ph.readLoop(stdout) + go ph.readStderr(stderr) + go ph.waitLoop() + + helloCtx := ctx + if helloCtx == nil { + var cancel context.CancelFunc + helloCtx, cancel = context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + } + if err := ph.hello(helloCtx); err != nil { + _ = ph.Close() + return nil, err + } + + return ph, nil +} + +func (ph *ProcessHook) Close() error { + if ph == nil { + return nil + } + + ph.closeOnce.Do(func() { + ph.closed.Store(true) + if ph.stdin != nil { + _ = ph.stdin.Close() + } + + select { + case <-ph.done: + case <-time.After(processHookCloseTimeout): + if ph.cmd != nil && ph.cmd.Process != nil { + _ = ph.cmd.Process.Kill() + } + <-ph.done + } + }) + + ph.closeMu.Lock() + defer ph.closeMu.Unlock() + return ph.closeErr +} + +func (ph *ProcessHook) OnEvent(ctx context.Context, evt Event) error { + if ph == nil || !ph.opts.Observe { + return nil + } + if len(ph.observeKinds) > 0 { + if _, ok := ph.observeKinds[evt.Kind.String()]; !ok { + return nil + } + } + return ph.notify(ctx, "hook.event", evt) +} + +func (ph *ProcessHook) BeforeLLM( + ctx context.Context, + req *LLMHookRequest, +) (*LLMHookRequest, HookDecision, error) { + if ph == nil || !ph.opts.InterceptLLM { + return req, HookDecision{Action: HookActionContinue}, nil + } + + var resp processHookBeforeLLMResponse + if err := ph.call(ctx, "hook.before_llm", req, &resp); err != nil { + return nil, HookDecision{}, err + } + if resp.Request == nil { + resp.Request = req + } + return resp.Request, HookDecision{Action: resp.Action, Reason: resp.Reason}, nil +} + +func (ph *ProcessHook) AfterLLM( + ctx context.Context, + resp *LLMHookResponse, +) (*LLMHookResponse, HookDecision, error) { + if ph == nil || !ph.opts.InterceptLLM { + return resp, HookDecision{Action: HookActionContinue}, nil + } + + var result processHookAfterLLMResponse + if err := ph.call(ctx, "hook.after_llm", resp, &result); err != nil { + return nil, HookDecision{}, err + } + if result.Response == nil { + result.Response = resp + } + return result.Response, HookDecision{Action: result.Action, Reason: result.Reason}, nil +} + +func (ph *ProcessHook) BeforeTool( + ctx context.Context, + call *ToolCallHookRequest, +) (*ToolCallHookRequest, HookDecision, error) { + if ph == nil || !ph.opts.InterceptTool { + return call, HookDecision{Action: HookActionContinue}, nil + } + + var resp processHookBeforeToolResponse + if err := ph.call(ctx, "hook.before_tool", call, &resp); err != nil { + return nil, HookDecision{}, err + } + if resp.Call == nil { + resp.Call = call + } + return resp.Call, HookDecision{Action: resp.Action, Reason: resp.Reason}, nil +} + +func (ph *ProcessHook) AfterTool( + ctx context.Context, + result *ToolResultHookResponse, +) (*ToolResultHookResponse, HookDecision, error) { + if ph == nil || !ph.opts.InterceptTool { + return result, HookDecision{Action: HookActionContinue}, nil + } + + var resp processHookAfterToolResponse + if err := ph.call(ctx, "hook.after_tool", result, &resp); err != nil { + return nil, HookDecision{}, err + } + if resp.Result == nil { + resp.Result = result + } + return resp.Result, HookDecision{Action: resp.Action, Reason: resp.Reason}, nil +} + +func (ph *ProcessHook) ApproveTool(ctx context.Context, req *ToolApprovalRequest) (ApprovalDecision, error) { + if ph == nil || !ph.opts.ApproveTool { + return ApprovalDecision{Approved: true}, nil + } + + var resp ApprovalDecision + if err := ph.call(ctx, "hook.approve_tool", req, &resp); err != nil { + return ApprovalDecision{}, err + } + return resp, nil +} + +func (ph *ProcessHook) hello(ctx context.Context) error { + modes := make([]string, 0, 4) + if ph.opts.Observe { + modes = append(modes, "observe") + } + if ph.opts.InterceptLLM { + modes = append(modes, "llm") + } + if ph.opts.InterceptTool { + modes = append(modes, "tool") + } + if ph.opts.ApproveTool { + modes = append(modes, "approve") + } + + var result map[string]any + return ph.call(ctx, "hook.hello", processHookHelloParams{ + Name: ph.name, + Version: 1, + Modes: modes, + }, &result) +} + +func (ph *ProcessHook) notify(ctx context.Context, method string, params any) error { + msg := processHookRPCMessage{ + JSONRPC: processHookJSONRPCVersion, + Method: method, + } + if params != nil { + body, err := json.Marshal(params) + if err != nil { + return err + } + msg.Params = body + } + return ph.send(ctx, msg) +} + +func (ph *ProcessHook) call(ctx context.Context, method string, params any, out any) error { + if ph.closed.Load() { + return fmt.Errorf("process hook %q is closed", ph.name) + } + + id := ph.nextID.Add(1) + respCh := make(chan processHookRPCMessage, 1) + ph.pendingMu.Lock() + ph.pending[id] = respCh + ph.pendingMu.Unlock() + + msg := processHookRPCMessage{ + JSONRPC: processHookJSONRPCVersion, + ID: id, + Method: method, + } + if params != nil { + body, err := json.Marshal(params) + if err != nil { + ph.removePending(id) + return err + } + msg.Params = body + } + + if err := ph.send(ctx, msg); err != nil { + ph.removePending(id) + return err + } + + select { + case resp, ok := <-respCh: + if !ok { + return fmt.Errorf("process hook %q closed while waiting for %s", ph.name, method) + } + if resp.Error != nil { + return fmt.Errorf("process hook %q %s failed: %s", ph.name, method, resp.Error.Message) + } + if out != nil && len(resp.Result) > 0 { + if err := json.Unmarshal(resp.Result, out); err != nil { + return fmt.Errorf("decode process hook %q %s result: %w", ph.name, method, err) + } + } + return nil + case <-ctx.Done(): + ph.removePending(id) + return ctx.Err() + } +} + +func (ph *ProcessHook) send(ctx context.Context, msg processHookRPCMessage) error { + body, err := json.Marshal(msg) + if err != nil { + return err + } + body = append(body, '\n') + + ph.writeMu.Lock() + defer ph.writeMu.Unlock() + + if ph.closed.Load() { + return fmt.Errorf("process hook %q is closed", ph.name) + } + + done := make(chan error, 1) + go func() { + _, writeErr := ph.stdin.Write(body) + done <- writeErr + }() + + select { + case err := <-done: + if err != nil { + return fmt.Errorf("write process hook %q message: %w", ph.name, err) + } + return nil + case <-ctx.Done(): + return ctx.Err() + } +} + +func (ph *ProcessHook) readLoop(stdout io.Reader) { + scanner := bufio.NewScanner(stdout) + scanner.Buffer(make([]byte, 0, 64*1024), processHookReadBufferSize) + + for scanner.Scan() { + var msg processHookRPCMessage + if err := json.Unmarshal(scanner.Bytes(), &msg); err != nil { + logger.WarnCF("hooks", "Failed to decode process hook message", map[string]any{ + "hook": ph.name, + "error": err.Error(), + }) + continue + } + if msg.ID == 0 { + continue + } + ph.pendingMu.Lock() + respCh, ok := ph.pending[msg.ID] + if ok { + delete(ph.pending, msg.ID) + } + ph.pendingMu.Unlock() + if ok { + respCh <- msg + close(respCh) + } + } +} + +func (ph *ProcessHook) readStderr(stderr io.Reader) { + scanner := bufio.NewScanner(stderr) + scanner.Buffer(make([]byte, 0, 16*1024), processHookReadBufferSize) + for scanner.Scan() { + logger.WarnCF("hooks", "Process hook stderr", map[string]any{ + "hook": ph.name, + "stderr": scanner.Text(), + }) + } +} + +func (ph *ProcessHook) waitLoop() { + err := ph.cmd.Wait() + ph.closeMu.Lock() + ph.closeErr = err + ph.closeMu.Unlock() + ph.failPending(err) + close(ph.done) +} + +func (ph *ProcessHook) failPending(err error) { + ph.pendingMu.Lock() + defer ph.pendingMu.Unlock() + + msg := processHookRPCMessage{ + Error: &processHookRPCError{ + Code: -32000, + Message: "process exited", + }, + } + if err != nil { + msg.Error.Message = err.Error() + } + + for id, ch := range ph.pending { + delete(ph.pending, id) + ch <- msg + close(ch) + } +} + +func (ph *ProcessHook) removePending(id uint64) { + ph.pendingMu.Lock() + defer ph.pendingMu.Unlock() + + if ch, ok := ph.pending[id]; ok { + delete(ph.pending, id) + close(ch) + } +} + +func (al *AgentLoop) MountProcessHook(ctx context.Context, name string, opts ProcessHookOptions) error { + if al == nil { + return fmt.Errorf("agent loop is nil") + } + processHook, err := NewProcessHook(ctx, name, opts) + if err != nil { + return err + } + if err := al.MountHook(HookRegistration{ + Name: name, + Source: HookSourceProcess, + Hook: processHook, + }); err != nil { + _ = processHook.Close() + return err + } + return nil +} + +func newProcessHookObserveKinds(kinds []string) map[string]struct{} { + if len(kinds) == 0 { + return nil + } + + normalized := make(map[string]struct{}, len(kinds)) + for _, kind := range kinds { + if kind == "" { + continue + } + normalized[kind] = struct{}{} + } + if len(normalized) == 0 { + return nil + } + return normalized +} diff --git a/pkg/agent/hook_process_test.go b/pkg/agent/hook_process_test.go new file mode 100644 index 00000000..50f89811 --- /dev/null +++ b/pkg/agent/hook_process_test.go @@ -0,0 +1,339 @@ +package agent + +import ( + "bufio" + "context" + "encoding/json" + "fmt" + "os" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/sipeed/picoclaw/pkg/providers" +) + +func TestProcessHook_HelperProcess(t *testing.T) { + if os.Getenv("PICOCLAW_HOOK_HELPER") != "1" { + return + } + if err := runProcessHookHelper(); err != nil { + fmt.Fprintln(os.Stderr, err.Error()) + os.Exit(1) + } + os.Exit(0) +} + +func TestAgentLoop_MountProcessHook_LLMAndObserver(t *testing.T) { + provider := &llmHookTestProvider{} + al, agent, cleanup := newHookTestLoop(t, provider) + defer cleanup() + + eventLog := filepath.Join(t.TempDir(), "events.log") + if err := al.MountProcessHook(context.Background(), "ipc-llm", ProcessHookOptions{ + Command: processHookHelperCommand(), + Env: processHookHelperEnv("rewrite", eventLog), + Observe: true, + InterceptLLM: true, + }); err != nil { + t.Fatalf("MountProcessHook failed: %v", err) + } + + resp, err := al.runAgentLoop(context.Background(), agent, processOptions{ + SessionKey: "session-1", + Channel: "cli", + ChatID: "direct", + UserMessage: "hello", + DefaultResponse: defaultResponse, + EnableSummary: false, + SendResponse: false, + }) + if err != nil { + t.Fatalf("runAgentLoop failed: %v", err) + } + if resp != "provider content|ipc" { + t.Fatalf("expected process-hooked llm content, got %q", resp) + } + + provider.mu.Lock() + lastModel := provider.lastModel + provider.mu.Unlock() + if lastModel != "process-model" { + t.Fatalf("expected process model, got %q", lastModel) + } + + waitForFileContains(t, eventLog, "turn_end") +} + +func TestAgentLoop_MountProcessHook_ToolRewrite(t *testing.T) { + provider := &toolHookProvider{} + al, agent, cleanup := newHookTestLoop(t, provider) + defer cleanup() + + al.RegisterTool(&echoTextTool{}) + if err := al.MountProcessHook(context.Background(), "ipc-tool", ProcessHookOptions{ + Command: processHookHelperCommand(), + Env: processHookHelperEnv("rewrite", ""), + InterceptTool: true, + }); err != nil { + t.Fatalf("MountProcessHook failed: %v", err) + } + + resp, err := al.runAgentLoop(context.Background(), agent, processOptions{ + SessionKey: "session-1", + Channel: "cli", + ChatID: "direct", + UserMessage: "run tool", + DefaultResponse: defaultResponse, + EnableSummary: false, + SendResponse: false, + }) + if err != nil { + t.Fatalf("runAgentLoop failed: %v", err) + } + if resp != "ipc:ipc" { + t.Fatalf("expected rewritten process-hook tool result, got %q", resp) + } +} + +type blockedToolProvider struct { + calls int +} + +func (p *blockedToolProvider) Chat( + ctx context.Context, + messages []providers.Message, + tools []providers.ToolDefinition, + model string, + opts map[string]any, +) (*providers.LLMResponse, error) { + p.calls++ + if p.calls == 1 { + return &providers.LLMResponse{ + ToolCalls: []providers.ToolCall{ + { + ID: "call-1", + Name: "blocked_tool", + Arguments: map[string]any{}, + }, + }, + }, nil + } + + return &providers.LLMResponse{ + Content: messages[len(messages)-1].Content, + }, nil +} + +func (p *blockedToolProvider) GetDefaultModel() string { + return "blocked-tool-provider" +} + +func TestAgentLoop_MountProcessHook_ApprovalDeny(t *testing.T) { + provider := &blockedToolProvider{} + al, agent, cleanup := newHookTestLoop(t, provider) + defer cleanup() + + if err := al.MountProcessHook(context.Background(), "ipc-approval", ProcessHookOptions{ + Command: processHookHelperCommand(), + Env: processHookHelperEnv("deny", ""), + ApproveTool: true, + }); err != nil { + t.Fatalf("MountProcessHook failed: %v", err) + } + + sub := al.SubscribeEvents(16) + defer al.UnsubscribeEvents(sub.ID) + + resp, err := al.runAgentLoop(context.Background(), agent, processOptions{ + SessionKey: "session-1", + Channel: "cli", + ChatID: "direct", + UserMessage: "run blocked tool", + DefaultResponse: defaultResponse, + EnableSummary: false, + SendResponse: false, + }) + if err != nil { + t.Fatalf("runAgentLoop failed: %v", err) + } + + expected := "Tool execution denied by approval hook: blocked by ipc hook" + if resp != expected { + t.Fatalf("expected %q, got %q", expected, resp) + } + + events := collectEventStream(sub.C) + skippedEvt, ok := findEvent(events, EventKindToolExecSkipped) + if !ok { + t.Fatal("expected tool skipped event") + } + payload, ok := skippedEvt.Payload.(ToolExecSkippedPayload) + if !ok { + t.Fatalf("expected ToolExecSkippedPayload, got %T", skippedEvt.Payload) + } + if payload.Reason != expected { + t.Fatalf("expected reason %q, got %q", expected, payload.Reason) + } +} + +func processHookHelperCommand() []string { + return []string{os.Args[0], "-test.run=TestProcessHook_HelperProcess", "--"} +} + +func processHookHelperEnv(mode, eventLog string) []string { + env := []string{ + "PICOCLAW_HOOK_HELPER=1", + "PICOCLAW_HOOK_MODE=" + mode, + } + if eventLog != "" { + env = append(env, "PICOCLAW_HOOK_EVENT_LOG="+eventLog) + } + return env +} + +func waitForFileContains(t *testing.T, path, substring string) { + t.Helper() + + deadline := time.Now().Add(3 * time.Second) + for time.Now().Before(deadline) { + data, err := os.ReadFile(path) + if err == nil && strings.Contains(string(data), substring) { + return + } + time.Sleep(20 * time.Millisecond) + } + + data, _ := os.ReadFile(path) + t.Fatalf("timed out waiting for %q in %s; current content: %q", substring, path, string(data)) +} + +func runProcessHookHelper() error { + mode := os.Getenv("PICOCLAW_HOOK_MODE") + eventLog := os.Getenv("PICOCLAW_HOOK_EVENT_LOG") + + scanner := bufio.NewScanner(os.Stdin) + scanner.Buffer(make([]byte, 0, 64*1024), processHookReadBufferSize) + encoder := json.NewEncoder(os.Stdout) + + for scanner.Scan() { + var msg processHookRPCMessage + if err := json.Unmarshal(scanner.Bytes(), &msg); err != nil { + return err + } + + if msg.ID == 0 { + if msg.Method == "hook.event" && eventLog != "" { + var evt map[string]any + if err := json.Unmarshal(msg.Params, &evt); err == nil { + if rawKind, ok := evt["Kind"].(float64); ok { + kind := EventKind(rawKind) + _ = os.WriteFile(eventLog, []byte(kind.String()+"\n"), 0o644) + } + } + } + continue + } + + result, rpcErr := handleProcessHookRequest(mode, msg) + resp := processHookRPCMessage{ + JSONRPC: processHookJSONRPCVersion, + ID: msg.ID, + } + if rpcErr != nil { + resp.Error = rpcErr + } else if result != nil { + body, err := json.Marshal(result) + if err != nil { + return err + } + resp.Result = body + } else { + resp.Result = []byte("{}") + } + + if err := encoder.Encode(resp); err != nil { + return err + } + } + + return scanner.Err() +} + +func handleProcessHookRequest(mode string, msg processHookRPCMessage) (any, *processHookRPCError) { + switch msg.Method { + case "hook.hello": + return map[string]any{"ok": true}, nil + case "hook.before_llm": + if mode != "rewrite" { + return map[string]any{"action": HookActionContinue}, nil + } + var req map[string]any + _ = json.Unmarshal(msg.Params, &req) + req["model"] = "process-model" + return map[string]any{ + "action": HookActionModify, + "request": req, + }, nil + case "hook.after_llm": + if mode != "rewrite" { + return map[string]any{"action": HookActionContinue}, nil + } + var resp map[string]any + _ = json.Unmarshal(msg.Params, &resp) + if rawResponse, ok := resp["response"].(map[string]any); ok { + if content, ok := rawResponse["content"].(string); ok { + rawResponse["content"] = content + "|ipc" + } + } + return map[string]any{ + "action": HookActionModify, + "response": resp, + }, nil + case "hook.before_tool": + if mode != "rewrite" { + return map[string]any{"action": HookActionContinue}, nil + } + var call map[string]any + _ = json.Unmarshal(msg.Params, &call) + rawArgs, ok := call["arguments"].(map[string]any) + if !ok || rawArgs == nil { + rawArgs = map[string]any{} + } + rawArgs["text"] = "ipc" + call["arguments"] = rawArgs + return map[string]any{ + "action": HookActionModify, + "call": call, + }, nil + case "hook.after_tool": + if mode != "rewrite" { + return map[string]any{"action": HookActionContinue}, nil + } + var result map[string]any + _ = json.Unmarshal(msg.Params, &result) + if rawResult, ok := result["result"].(map[string]any); ok { + if forLLM, ok := rawResult["for_llm"].(string); ok { + rawResult["for_llm"] = "ipc:" + forLLM + } + } + return map[string]any{ + "action": HookActionModify, + "result": result, + }, nil + case "hook.approve_tool": + if mode == "deny" { + return ApprovalDecision{ + Approved: false, + Reason: "blocked by ipc hook", + }, nil + } + return ApprovalDecision{Approved: true}, nil + default: + return nil, &processHookRPCError{ + Code: -32601, + Message: "method not found", + } + } +} diff --git a/pkg/agent/hooks.go b/pkg/agent/hooks.go new file mode 100644 index 00000000..c1ef58ff --- /dev/null +++ b/pkg/agent/hooks.go @@ -0,0 +1,809 @@ +package agent + +import ( + "context" + "fmt" + "io" + "sort" + "sync" + "time" + + "github.com/sipeed/picoclaw/pkg/logger" + "github.com/sipeed/picoclaw/pkg/providers" + "github.com/sipeed/picoclaw/pkg/tools" +) + +const ( + defaultHookObserverTimeout = 500 * time.Millisecond + defaultHookInterceptorTimeout = 5 * time.Second + defaultHookApprovalTimeout = 60 * time.Second + hookObserverBufferSize = 64 +) + +type HookAction string + +const ( + HookActionContinue HookAction = "continue" + HookActionModify HookAction = "modify" + HookActionDenyTool HookAction = "deny_tool" + HookActionAbortTurn HookAction = "abort_turn" + HookActionHardAbort HookAction = "hard_abort" +) + +type HookDecision struct { + Action HookAction `json:"action"` + Reason string `json:"reason,omitempty"` +} + +func (d HookDecision) normalizedAction() HookAction { + if d.Action == "" { + return HookActionContinue + } + return d.Action +} + +type ApprovalDecision struct { + Approved bool `json:"approved"` + Reason string `json:"reason,omitempty"` +} + +type HookSource uint8 + +const ( + HookSourceInProcess HookSource = iota + HookSourceProcess +) + +type HookRegistration struct { + Name string + Priority int + Source HookSource + Hook any +} + +func NamedHook(name string, hook any) HookRegistration { + return HookRegistration{ + Name: name, + Source: HookSourceInProcess, + Hook: hook, + } +} + +type EventObserver interface { + OnEvent(ctx context.Context, evt Event) error +} + +type LLMInterceptor interface { + BeforeLLM(ctx context.Context, req *LLMHookRequest) (*LLMHookRequest, HookDecision, error) + AfterLLM(ctx context.Context, resp *LLMHookResponse) (*LLMHookResponse, HookDecision, error) +} + +type ToolInterceptor interface { + BeforeTool(ctx context.Context, call *ToolCallHookRequest) (*ToolCallHookRequest, HookDecision, error) + AfterTool(ctx context.Context, result *ToolResultHookResponse) (*ToolResultHookResponse, HookDecision, error) +} + +type ToolApprover interface { + ApproveTool(ctx context.Context, req *ToolApprovalRequest) (ApprovalDecision, error) +} + +type LLMHookRequest struct { + Meta EventMeta `json:"meta"` + Model string `json:"model"` + Messages []providers.Message `json:"messages,omitempty"` + Tools []providers.ToolDefinition `json:"tools,omitempty"` + Options map[string]any `json:"options,omitempty"` + Channel string `json:"channel,omitempty"` + ChatID string `json:"chat_id,omitempty"` + GracefulTerminal bool `json:"graceful_terminal,omitempty"` +} + +func (r *LLMHookRequest) Clone() *LLMHookRequest { + if r == nil { + return nil + } + cloned := *r + cloned.Messages = cloneProviderMessages(r.Messages) + cloned.Tools = cloneToolDefinitions(r.Tools) + cloned.Options = cloneStringAnyMap(r.Options) + return &cloned +} + +type LLMHookResponse struct { + Meta EventMeta `json:"meta"` + Model string `json:"model"` + Response *providers.LLMResponse `json:"response,omitempty"` + Channel string `json:"channel,omitempty"` + ChatID string `json:"chat_id,omitempty"` +} + +func (r *LLMHookResponse) Clone() *LLMHookResponse { + if r == nil { + return nil + } + cloned := *r + cloned.Response = cloneLLMResponse(r.Response) + return &cloned +} + +type ToolCallHookRequest struct { + Meta EventMeta `json:"meta"` + Tool string `json:"tool"` + Arguments map[string]any `json:"arguments,omitempty"` + Channel string `json:"channel,omitempty"` + ChatID string `json:"chat_id,omitempty"` +} + +func (r *ToolCallHookRequest) Clone() *ToolCallHookRequest { + if r == nil { + return nil + } + cloned := *r + cloned.Arguments = cloneStringAnyMap(r.Arguments) + return &cloned +} + +type ToolApprovalRequest struct { + Meta EventMeta `json:"meta"` + Tool string `json:"tool"` + Arguments map[string]any `json:"arguments,omitempty"` + Channel string `json:"channel,omitempty"` + ChatID string `json:"chat_id,omitempty"` +} + +func (r *ToolApprovalRequest) Clone() *ToolApprovalRequest { + if r == nil { + return nil + } + cloned := *r + cloned.Arguments = cloneStringAnyMap(r.Arguments) + return &cloned +} + +type ToolResultHookResponse struct { + Meta EventMeta `json:"meta"` + Tool string `json:"tool"` + Arguments map[string]any `json:"arguments,omitempty"` + Result *tools.ToolResult `json:"result,omitempty"` + Duration time.Duration `json:"duration"` + Channel string `json:"channel,omitempty"` + ChatID string `json:"chat_id,omitempty"` +} + +func (r *ToolResultHookResponse) Clone() *ToolResultHookResponse { + if r == nil { + return nil + } + cloned := *r + cloned.Arguments = cloneStringAnyMap(r.Arguments) + cloned.Result = cloneToolResult(r.Result) + return &cloned +} + +type HookManager struct { + eventBus *EventBus + observerTimeout time.Duration + interceptorTimeout time.Duration + approvalTimeout time.Duration + + mu sync.RWMutex + hooks map[string]HookRegistration + ordered []HookRegistration + + sub EventSubscription + done chan struct{} + closeOnce sync.Once +} + +func NewHookManager(eventBus *EventBus) *HookManager { + hm := &HookManager{ + eventBus: eventBus, + observerTimeout: defaultHookObserverTimeout, + interceptorTimeout: defaultHookInterceptorTimeout, + approvalTimeout: defaultHookApprovalTimeout, + hooks: make(map[string]HookRegistration), + done: make(chan struct{}), + } + + if eventBus == nil { + close(hm.done) + return hm + } + + hm.sub = eventBus.Subscribe(hookObserverBufferSize) + go hm.dispatchEvents() + return hm +} + +func (hm *HookManager) Close() { + if hm == nil { + return + } + + hm.closeOnce.Do(func() { + if hm.eventBus != nil { + hm.eventBus.Unsubscribe(hm.sub.ID) + } + <-hm.done + hm.closeAllHooks() + }) +} + +func (hm *HookManager) ConfigureTimeouts(observer, interceptor, approval time.Duration) { + if hm == nil { + return + } + if observer > 0 { + hm.observerTimeout = observer + } + if interceptor > 0 { + hm.interceptorTimeout = interceptor + } + if approval > 0 { + hm.approvalTimeout = approval + } +} + +func (hm *HookManager) Mount(reg HookRegistration) error { + if hm == nil { + return fmt.Errorf("hook manager is nil") + } + if reg.Name == "" { + return fmt.Errorf("hook name is required") + } + if reg.Hook == nil { + return fmt.Errorf("hook %q is nil", reg.Name) + } + + hm.mu.Lock() + defer hm.mu.Unlock() + + if existing, ok := hm.hooks[reg.Name]; ok { + closeHookIfPossible(existing.Hook) + } + hm.hooks[reg.Name] = reg + hm.rebuildOrdered() + return nil +} + +func (hm *HookManager) Unmount(name string) { + if hm == nil || name == "" { + return + } + + hm.mu.Lock() + defer hm.mu.Unlock() + + if existing, ok := hm.hooks[name]; ok { + closeHookIfPossible(existing.Hook) + } + delete(hm.hooks, name) + hm.rebuildOrdered() +} + +func (hm *HookManager) dispatchEvents() { + defer close(hm.done) + + for evt := range hm.sub.C { + for _, reg := range hm.snapshotHooks() { + observer, ok := reg.Hook.(EventObserver) + if !ok { + continue + } + hm.runObserver(reg.Name, observer, evt) + } + } +} + +func (hm *HookManager) BeforeLLM(ctx context.Context, req *LLMHookRequest) (*LLMHookRequest, HookDecision) { + if hm == nil || req == nil { + return req, HookDecision{Action: HookActionContinue} + } + + current := req.Clone() + for _, reg := range hm.snapshotHooks() { + interceptor, ok := reg.Hook.(LLMInterceptor) + if !ok { + continue + } + + next, decision, ok := hm.callBeforeLLM(ctx, reg.Name, interceptor, current.Clone()) + if !ok { + continue + } + + switch decision.normalizedAction() { + case HookActionContinue, HookActionModify: + if next != nil { + current = next + } + case HookActionAbortTurn, HookActionHardAbort: + return current, decision + default: + hm.logUnsupportedAction(reg.Name, "before_llm", decision.Action) + } + } + return current, HookDecision{Action: HookActionContinue} +} + +func (hm *HookManager) AfterLLM(ctx context.Context, resp *LLMHookResponse) (*LLMHookResponse, HookDecision) { + if hm == nil || resp == nil { + return resp, HookDecision{Action: HookActionContinue} + } + + current := resp.Clone() + for _, reg := range hm.snapshotHooks() { + interceptor, ok := reg.Hook.(LLMInterceptor) + if !ok { + continue + } + + next, decision, ok := hm.callAfterLLM(ctx, reg.Name, interceptor, current.Clone()) + if !ok { + continue + } + + switch decision.normalizedAction() { + case HookActionContinue, HookActionModify: + if next != nil { + current = next + } + case HookActionAbortTurn, HookActionHardAbort: + return current, decision + default: + hm.logUnsupportedAction(reg.Name, "after_llm", decision.Action) + } + } + return current, HookDecision{Action: HookActionContinue} +} + +func (hm *HookManager) BeforeTool( + ctx context.Context, + call *ToolCallHookRequest, +) (*ToolCallHookRequest, HookDecision) { + if hm == nil || call == nil { + return call, HookDecision{Action: HookActionContinue} + } + + current := call.Clone() + for _, reg := range hm.snapshotHooks() { + interceptor, ok := reg.Hook.(ToolInterceptor) + if !ok { + continue + } + + next, decision, ok := hm.callBeforeTool(ctx, reg.Name, interceptor, current.Clone()) + if !ok { + continue + } + + switch decision.normalizedAction() { + case HookActionContinue, HookActionModify: + if next != nil { + current = next + } + case HookActionDenyTool, HookActionAbortTurn, HookActionHardAbort: + return current, decision + default: + hm.logUnsupportedAction(reg.Name, "before_tool", decision.Action) + } + } + return current, HookDecision{Action: HookActionContinue} +} + +func (hm *HookManager) AfterTool( + ctx context.Context, + result *ToolResultHookResponse, +) (*ToolResultHookResponse, HookDecision) { + if hm == nil || result == nil { + return result, HookDecision{Action: HookActionContinue} + } + + current := result.Clone() + for _, reg := range hm.snapshotHooks() { + interceptor, ok := reg.Hook.(ToolInterceptor) + if !ok { + continue + } + + next, decision, ok := hm.callAfterTool(ctx, reg.Name, interceptor, current.Clone()) + if !ok { + continue + } + + switch decision.normalizedAction() { + case HookActionContinue, HookActionModify: + if next != nil { + current = next + } + case HookActionAbortTurn, HookActionHardAbort: + return current, decision + default: + hm.logUnsupportedAction(reg.Name, "after_tool", decision.Action) + } + } + return current, HookDecision{Action: HookActionContinue} +} + +func (hm *HookManager) ApproveTool(ctx context.Context, req *ToolApprovalRequest) ApprovalDecision { + if hm == nil || req == nil { + return ApprovalDecision{Approved: true} + } + + for _, reg := range hm.snapshotHooks() { + approver, ok := reg.Hook.(ToolApprover) + if !ok { + continue + } + + decision, ok := hm.callApproveTool(ctx, reg.Name, approver, req.Clone()) + if !ok { + return ApprovalDecision{ + Approved: false, + Reason: fmt.Sprintf("tool approval hook %q failed", reg.Name), + } + } + if !decision.Approved { + return decision + } + } + + return ApprovalDecision{Approved: true} +} + +func (hm *HookManager) rebuildOrdered() { + hm.ordered = hm.ordered[:0] + for _, reg := range hm.hooks { + hm.ordered = append(hm.ordered, reg) + } + sort.SliceStable(hm.ordered, func(i, j int) bool { + if hm.ordered[i].Source != hm.ordered[j].Source { + return hm.ordered[i].Source < hm.ordered[j].Source + } + if hm.ordered[i].Priority == hm.ordered[j].Priority { + return hm.ordered[i].Name < hm.ordered[j].Name + } + return hm.ordered[i].Priority < hm.ordered[j].Priority + }) +} + +func (hm *HookManager) snapshotHooks() []HookRegistration { + hm.mu.RLock() + defer hm.mu.RUnlock() + + snapshot := make([]HookRegistration, len(hm.ordered)) + copy(snapshot, hm.ordered) + return snapshot +} + +func (hm *HookManager) closeAllHooks() { + hm.mu.Lock() + defer hm.mu.Unlock() + + for name, reg := range hm.hooks { + closeHookIfPossible(reg.Hook) + delete(hm.hooks, name) + } + hm.ordered = nil +} + +func (hm *HookManager) runObserver(name string, observer EventObserver, evt Event) { + ctx, cancel := context.WithTimeout(context.Background(), hm.observerTimeout) + defer cancel() + + done := make(chan error, 1) + go func() { + done <- observer.OnEvent(ctx, evt) + }() + + select { + case err := <-done: + if err != nil { + logger.WarnCF("hooks", "Event observer failed", map[string]any{ + "hook": name, + "event": evt.Kind.String(), + "error": err.Error(), + }) + } + case <-ctx.Done(): + logger.WarnCF("hooks", "Event observer timed out", map[string]any{ + "hook": name, + "event": evt.Kind.String(), + "timeout_ms": hm.observerTimeout.Milliseconds(), + }) + } +} + +func (hm *HookManager) callBeforeLLM( + parent context.Context, + name string, + interceptor LLMInterceptor, + req *LLMHookRequest, +) (*LLMHookRequest, HookDecision, bool) { + return runInterceptorHook( + parent, + hm.interceptorTimeout, + name, + "before_llm", + func(ctx context.Context) (*LLMHookRequest, HookDecision, error) { + return interceptor.BeforeLLM(ctx, req) + }, + ) +} + +func (hm *HookManager) callAfterLLM( + parent context.Context, + name string, + interceptor LLMInterceptor, + resp *LLMHookResponse, +) (*LLMHookResponse, HookDecision, bool) { + return runInterceptorHook( + parent, + hm.interceptorTimeout, + name, + "after_llm", + func(ctx context.Context) (*LLMHookResponse, HookDecision, error) { + return interceptor.AfterLLM(ctx, resp) + }, + ) +} + +func (hm *HookManager) callBeforeTool( + parent context.Context, + name string, + interceptor ToolInterceptor, + call *ToolCallHookRequest, +) (*ToolCallHookRequest, HookDecision, bool) { + return runInterceptorHook( + parent, + hm.interceptorTimeout, + name, + "before_tool", + func(ctx context.Context) (*ToolCallHookRequest, HookDecision, error) { + return interceptor.BeforeTool(ctx, call) + }, + ) +} + +func (hm *HookManager) callAfterTool( + parent context.Context, + name string, + interceptor ToolInterceptor, + resultView *ToolResultHookResponse, +) (*ToolResultHookResponse, HookDecision, bool) { + return runInterceptorHook( + parent, + hm.interceptorTimeout, + name, + "after_tool", + func(ctx context.Context) (*ToolResultHookResponse, HookDecision, error) { + return interceptor.AfterTool(ctx, resultView) + }, + ) +} + +func (hm *HookManager) callApproveTool( + parent context.Context, + name string, + approver ToolApprover, + req *ToolApprovalRequest, +) (ApprovalDecision, bool) { + return runApprovalHook( + parent, + hm.approvalTimeout, + name, + "approve_tool", + func(ctx context.Context) (ApprovalDecision, error) { + return approver.ApproveTool(ctx, req) + }, + ) +} + +func runInterceptorHook[T any]( + parent context.Context, + timeout time.Duration, + name string, + stage string, + fn func(ctx context.Context) (T, HookDecision, error), +) (T, HookDecision, bool) { + var zero T + + ctx, cancel := context.WithTimeout(parent, timeout) + defer cancel() + + type result struct { + value T + decision HookDecision + err error + } + done := make(chan result, 1) + go func() { + value, decision, err := fn(ctx) + done <- result{value: value, decision: decision, err: err} + }() + + select { + case res := <-done: + if res.err != nil { + logger.WarnCF("hooks", "Interceptor hook failed", map[string]any{ + "hook": name, + "stage": stage, + "error": res.err.Error(), + }) + return zero, HookDecision{}, false + } + return res.value, res.decision, true + case <-ctx.Done(): + logger.WarnCF("hooks", "Interceptor hook timed out", map[string]any{ + "hook": name, + "stage": stage, + "timeout_ms": timeout.Milliseconds(), + }) + return zero, HookDecision{}, false + } +} + +func runApprovalHook( + parent context.Context, + timeout time.Duration, + name string, + stage string, + fn func(ctx context.Context) (ApprovalDecision, error), +) (ApprovalDecision, bool) { + ctx, cancel := context.WithTimeout(parent, timeout) + defer cancel() + + type result struct { + decision ApprovalDecision + err error + } + done := make(chan result, 1) + go func() { + decision, err := fn(ctx) + done <- result{decision: decision, err: err} + }() + + select { + case res := <-done: + if res.err != nil { + logger.WarnCF("hooks", "Approval hook failed", map[string]any{ + "hook": name, + "stage": stage, + "error": res.err.Error(), + }) + return ApprovalDecision{}, false + } + return res.decision, true + case <-ctx.Done(): + logger.WarnCF("hooks", "Approval hook timed out", map[string]any{ + "hook": name, + "stage": stage, + "timeout_ms": timeout.Milliseconds(), + }) + return ApprovalDecision{ + Approved: false, + Reason: fmt.Sprintf("tool approval hook %q timed out", name), + }, true + } +} + +func (hm *HookManager) logUnsupportedAction(name, stage string, action HookAction) { + logger.WarnCF("hooks", "Hook returned unsupported action for stage", map[string]any{ + "hook": name, + "stage": stage, + "action": action, + }) +} + +func cloneProviderMessages(messages []providers.Message) []providers.Message { + if len(messages) == 0 { + return nil + } + + cloned := make([]providers.Message, len(messages)) + for i, msg := range messages { + cloned[i] = msg + if len(msg.Media) > 0 { + cloned[i].Media = append([]string(nil), msg.Media...) + } + if len(msg.SystemParts) > 0 { + cloned[i].SystemParts = append([]providers.ContentBlock(nil), msg.SystemParts...) + } + if len(msg.ToolCalls) > 0 { + cloned[i].ToolCalls = cloneProviderToolCalls(msg.ToolCalls) + } + } + return cloned +} + +func cloneProviderToolCalls(calls []providers.ToolCall) []providers.ToolCall { + if len(calls) == 0 { + return nil + } + + cloned := make([]providers.ToolCall, len(calls)) + for i, call := range calls { + cloned[i] = call + if call.Function != nil { + fn := *call.Function + cloned[i].Function = &fn + } + if call.Arguments != nil { + cloned[i].Arguments = cloneStringAnyMap(call.Arguments) + } + if call.ExtraContent != nil { + extra := *call.ExtraContent + if call.ExtraContent.Google != nil { + google := *call.ExtraContent.Google + extra.Google = &google + } + cloned[i].ExtraContent = &extra + } + } + return cloned +} + +func cloneToolDefinitions(defs []providers.ToolDefinition) []providers.ToolDefinition { + if len(defs) == 0 { + return nil + } + + cloned := make([]providers.ToolDefinition, len(defs)) + for i, def := range defs { + cloned[i] = def + cloned[i].Function.Parameters = cloneStringAnyMap(def.Function.Parameters) + } + return cloned +} + +func cloneLLMResponse(resp *providers.LLMResponse) *providers.LLMResponse { + if resp == nil { + return nil + } + cloned := *resp + cloned.ToolCalls = cloneProviderToolCalls(resp.ToolCalls) + if len(resp.ReasoningDetails) > 0 { + cloned.ReasoningDetails = append(cloned.ReasoningDetails[:0:0], resp.ReasoningDetails...) + } + if resp.Usage != nil { + usage := *resp.Usage + cloned.Usage = &usage + } + return &cloned +} + +func cloneStringAnyMap(src map[string]any) map[string]any { + if len(src) == 0 { + return nil + } + + cloned := make(map[string]any, len(src)) + for k, v := range src { + cloned[k] = v + } + return cloned +} + +func cloneToolResult(result *tools.ToolResult) *tools.ToolResult { + if result == nil { + return nil + } + + cloned := *result + if len(result.Media) > 0 { + cloned.Media = append([]string(nil), result.Media...) + } + return &cloned +} + +func closeHookIfPossible(hook any) { + closer, ok := hook.(io.Closer) + if !ok { + return + } + if err := closer.Close(); err != nil { + logger.WarnCF("hooks", "Failed to close hook", map[string]any{ + "error": err.Error(), + }) + } +} diff --git a/pkg/agent/hooks_test.go b/pkg/agent/hooks_test.go new file mode 100644 index 00000000..e6471e9c --- /dev/null +++ b/pkg/agent/hooks_test.go @@ -0,0 +1,345 @@ +package agent + +import ( + "context" + "os" + "sync" + "testing" + "time" + + "github.com/sipeed/picoclaw/pkg/bus" + "github.com/sipeed/picoclaw/pkg/config" + "github.com/sipeed/picoclaw/pkg/providers" + "github.com/sipeed/picoclaw/pkg/tools" +) + +func newHookTestLoop( + t *testing.T, + provider providers.LLMProvider, +) (*AgentLoop, *AgentInstance, func()) { + t.Helper() + + tmpDir, err := os.MkdirTemp("", "agent-hooks-*") + if err != nil { + t.Fatalf("failed to create temp dir: %v", err) + } + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: tmpDir, + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + }, + }, + } + + al := NewAgentLoop(cfg, bus.NewMessageBus(), provider) + agent := al.registry.GetDefaultAgent() + if agent == nil { + t.Fatal("expected default agent") + } + + return al, agent, func() { + al.Close() + _ = os.RemoveAll(tmpDir) + } +} + +func TestHookManager_SortsInProcessBeforeProcess(t *testing.T) { + hm := NewHookManager(nil) + defer hm.Close() + + if err := hm.Mount(HookRegistration{ + Name: "process", + Priority: -10, + Source: HookSourceProcess, + Hook: struct{}{}, + }); err != nil { + t.Fatalf("mount process hook: %v", err) + } + if err := hm.Mount(HookRegistration{ + Name: "in-process", + Priority: 100, + Source: HookSourceInProcess, + Hook: struct{}{}, + }); err != nil { + t.Fatalf("mount in-process hook: %v", err) + } + + ordered := hm.snapshotHooks() + if len(ordered) != 2 { + t.Fatalf("expected 2 hooks, got %d", len(ordered)) + } + if ordered[0].Name != "in-process" { + t.Fatalf("expected in-process hook first, got %q", ordered[0].Name) + } + if ordered[1].Name != "process" { + t.Fatalf("expected process hook second, got %q", ordered[1].Name) + } +} + +type llmHookTestProvider struct { + mu sync.Mutex + lastModel string +} + +func (p *llmHookTestProvider) Chat( + ctx context.Context, + messages []providers.Message, + tools []providers.ToolDefinition, + model string, + opts map[string]any, +) (*providers.LLMResponse, error) { + p.mu.Lock() + p.lastModel = model + p.mu.Unlock() + + return &providers.LLMResponse{ + Content: "provider content", + }, nil +} + +func (p *llmHookTestProvider) GetDefaultModel() string { + return "llm-hook-provider" +} + +type llmObserverHook struct { + eventCh chan Event +} + +func (h *llmObserverHook) OnEvent(ctx context.Context, evt Event) error { + if evt.Kind == EventKindTurnEnd { + select { + case h.eventCh <- evt: + default: + } + } + return nil +} + +func (h *llmObserverHook) BeforeLLM( + ctx context.Context, + req *LLMHookRequest, +) (*LLMHookRequest, HookDecision, error) { + next := req.Clone() + next.Model = "hook-model" + return next, HookDecision{Action: HookActionModify}, nil +} + +func (h *llmObserverHook) AfterLLM( + ctx context.Context, + resp *LLMHookResponse, +) (*LLMHookResponse, HookDecision, error) { + next := resp.Clone() + next.Response.Content = "hooked content" + return next, HookDecision{Action: HookActionModify}, nil +} + +func TestAgentLoop_Hooks_ObserverAndLLMInterceptor(t *testing.T) { + provider := &llmHookTestProvider{} + al, agent, cleanup := newHookTestLoop(t, provider) + defer cleanup() + + hook := &llmObserverHook{eventCh: make(chan Event, 1)} + if err := al.MountHook(NamedHook("llm-observer", hook)); err != nil { + t.Fatalf("MountHook failed: %v", err) + } + + resp, err := al.runAgentLoop(context.Background(), agent, processOptions{ + SessionKey: "session-1", + Channel: "cli", + ChatID: "direct", + UserMessage: "hello", + DefaultResponse: defaultResponse, + EnableSummary: false, + SendResponse: false, + }) + if err != nil { + t.Fatalf("runAgentLoop failed: %v", err) + } + if resp != "hooked content" { + t.Fatalf("expected hooked content, got %q", resp) + } + + provider.mu.Lock() + lastModel := provider.lastModel + provider.mu.Unlock() + if lastModel != "hook-model" { + t.Fatalf("expected model hook-model, got %q", lastModel) + } + + select { + case evt := <-hook.eventCh: + if evt.Kind != EventKindTurnEnd { + t.Fatalf("expected turn end event, got %v", evt.Kind) + } + case <-time.After(2 * time.Second): + t.Fatal("timed out waiting for hook observer event") + } +} + +type toolHookProvider struct { + mu sync.Mutex + calls int +} + +func (p *toolHookProvider) Chat( + ctx context.Context, + messages []providers.Message, + tools []providers.ToolDefinition, + model string, + opts map[string]any, +) (*providers.LLMResponse, error) { + p.mu.Lock() + defer p.mu.Unlock() + + p.calls++ + if p.calls == 1 { + return &providers.LLMResponse{ + ToolCalls: []providers.ToolCall{ + { + ID: "call-1", + Name: "echo_text", + Arguments: map[string]any{"text": "original"}, + }, + }, + }, nil + } + + last := messages[len(messages)-1] + return &providers.LLMResponse{ + Content: last.Content, + }, nil +} + +func (p *toolHookProvider) GetDefaultModel() string { + return "tool-hook-provider" +} + +type echoTextTool struct{} + +func (t *echoTextTool) Name() string { + return "echo_text" +} + +func (t *echoTextTool) Description() string { + return "echo a text argument" +} + +func (t *echoTextTool) Parameters() map[string]any { + return map[string]any{ + "type": "object", + "properties": map[string]any{ + "text": map[string]any{ + "type": "string", + }, + }, + } +} + +func (t *echoTextTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult { + text, _ := args["text"].(string) + return tools.SilentResult(text) +} + +type toolRewriteHook struct{} + +func (h *toolRewriteHook) BeforeTool( + ctx context.Context, + call *ToolCallHookRequest, +) (*ToolCallHookRequest, HookDecision, error) { + next := call.Clone() + next.Arguments["text"] = "modified" + return next, HookDecision{Action: HookActionModify}, nil +} + +func (h *toolRewriteHook) AfterTool( + ctx context.Context, + result *ToolResultHookResponse, +) (*ToolResultHookResponse, HookDecision, error) { + next := result.Clone() + next.Result.ForLLM = "after:" + next.Result.ForLLM + return next, HookDecision{Action: HookActionModify}, nil +} + +func TestAgentLoop_Hooks_ToolInterceptorCanRewrite(t *testing.T) { + provider := &toolHookProvider{} + al, agent, cleanup := newHookTestLoop(t, provider) + defer cleanup() + + al.RegisterTool(&echoTextTool{}) + if err := al.MountHook(NamedHook("tool-rewrite", &toolRewriteHook{})); err != nil { + t.Fatalf("MountHook failed: %v", err) + } + + resp, err := al.runAgentLoop(context.Background(), agent, processOptions{ + SessionKey: "session-1", + Channel: "cli", + ChatID: "direct", + UserMessage: "run tool", + DefaultResponse: defaultResponse, + EnableSummary: false, + SendResponse: false, + }) + if err != nil { + t.Fatalf("runAgentLoop failed: %v", err) + } + if resp != "after:modified" { + t.Fatalf("expected rewritten tool result, got %q", resp) + } +} + +type denyApprovalHook struct{} + +func (h *denyApprovalHook) ApproveTool(ctx context.Context, req *ToolApprovalRequest) (ApprovalDecision, error) { + return ApprovalDecision{ + Approved: false, + Reason: "blocked", + }, nil +} + +func TestAgentLoop_Hooks_ToolApproverCanDeny(t *testing.T) { + provider := &toolHookProvider{} + al, agent, cleanup := newHookTestLoop(t, provider) + defer cleanup() + + al.RegisterTool(&echoTextTool{}) + if err := al.MountHook(NamedHook("deny-approval", &denyApprovalHook{})); err != nil { + t.Fatalf("MountHook failed: %v", err) + } + + sub := al.SubscribeEvents(16) + defer al.UnsubscribeEvents(sub.ID) + + resp, err := al.runAgentLoop(context.Background(), agent, processOptions{ + SessionKey: "session-1", + Channel: "cli", + ChatID: "direct", + UserMessage: "run tool", + DefaultResponse: defaultResponse, + EnableSummary: false, + SendResponse: false, + }) + if err != nil { + t.Fatalf("runAgentLoop failed: %v", err) + } + expected := "Tool execution denied by approval hook: blocked" + if resp != expected { + t.Fatalf("expected %q, got %q", expected, resp) + } + + events := collectEventStream(sub.C) + skippedEvt, ok := findEvent(events, EventKindToolExecSkipped) + if !ok { + t.Fatal("expected tool skipped event") + } + payload, ok := skippedEvt.Payload.(ToolExecSkippedPayload) + if !ok { + t.Fatalf("expected ToolExecSkippedPayload, got %T", skippedEvt.Payload) + } + if payload.Reason != expected { + t.Fatalf("expected skipped reason %q, got %q", expected, payload.Reason) + } +} diff --git a/pkg/agent/instance.go b/pkg/agent/instance.go index 355e78a3..34d40118 100644 --- a/pkg/agent/instance.go +++ b/pkg/agent/instance.go @@ -130,6 +130,17 @@ func NewAgentInstance( maxTokens = 8192 } + contextWindow := defaults.ContextWindow + if contextWindow == 0 { + // Default heuristic: 4x the output token limit. + // Most models have context windows well above their output limits + // (e.g., GPT-4o 128k ctx / 16k out, Claude 200k ctx / 8k out). + // 4x is a conservative lower bound that avoids premature + // summarization while remaining safe — the reactive + // forceCompression handles any overshoot. + contextWindow = maxTokens * 4 + } + temperature := 0.7 if defaults.Temperature != nil { temperature = *defaults.Temperature @@ -182,7 +193,7 @@ func NewAgentInstance( MaxTokens: maxTokens, Temperature: temperature, ThinkingLevel: thinkingLevel, - ContextWindow: maxTokens, + ContextWindow: contextWindow, SummarizeMessageThreshold: summarizeMessageThreshold, SummarizeTokenPercent: summarizeTokenPercent, Provider: provider, diff --git a/pkg/agent/loop.go b/pkg/agent/loop.go index 2b6672f9..2a8cb883 100644 --- a/pkg/agent/loop.go +++ b/pkg/agent/loop.go @@ -17,7 +17,6 @@ import ( "sync" "sync/atomic" "time" - "unicode/utf8" "github.com/sipeed/picoclaw/pkg/bus" "github.com/sipeed/picoclaw/pkg/channels" @@ -36,10 +35,17 @@ import ( ) type AgentLoop struct { - bus *bus.MessageBus - cfg *config.Config - registry *AgentRegistry - state *state.Manager + // Core dependencies + bus *bus.MessageBus + cfg *config.Config + registry *AgentRegistry + state *state.Manager + + // Event system (from Incoming) + eventBus *EventBus + hooks *HookManager + + // Runtime state running atomic.Bool summarizing sync.Map fallback *providers.FallbackChain @@ -48,25 +54,43 @@ type AgentLoop struct { transcriber voice.Transcriber cmdRegistry *commands.Registry mcp mcpRuntime + hookRuntime hookRuntime + steering *steeringQueue mu sync.RWMutex - reloadFunc func() error - // Track active requests for safe provider cleanup + + // Concurrent turn management (from HEAD) + activeTurnStates sync.Map // key: sessionKey (string), value: *turnState + subTurnCounter atomic.Int64 // Counter for generating unique SubTurn IDs + + // Turn tracking (from Incoming) + turnSeq atomic.Uint64 activeRequests sync.WaitGroup + + reloadFunc func() error } // processOptions configures how a message is processed type processOptions struct { - SessionKey string // Session identifier for history/context - Channel string // Target channel for tool execution - ChatID string // Target chat ID for tool execution - SenderID string // Current sender ID for dynamic context - SenderDisplayName string // Current sender display name for dynamic context - UserMessage string // User message content (may include prefix) - Media []string // media:// refs from inbound message - DefaultResponse string // Response when LLM returns empty - EnableSummary bool // Whether to trigger summarization - SendResponse bool // Whether to send response via bus - NoHistory bool // If true, don't load session history (for heartbeat) + SessionKey string // Session identifier for history/context + Channel string // Target channel for tool execution + ChatID string // Target chat ID for tool execution + SenderID string // Current sender ID for dynamic context + SenderDisplayName string // Current sender display name for dynamic context + UserMessage string // User message content (may include prefix) + SystemPromptOverride string // Override the default system prompt (Used by SubTurns) + Media []string // media:// refs from inbound message + InitialSteeringMessages []providers.Message // Steering messages from refactor/agent + DefaultResponse string // Response when LLM returns empty + EnableSummary bool // Whether to trigger summarization + SendResponse bool // Whether to send response via bus + NoHistory bool // If true, don't load session history (for heartbeat) + SkipInitialSteeringPoll bool // If true, skip the steering poll at loop start (used by Continue) +} + +type continuationTarget struct { + SessionKey string + Channel string + ChatID string } const ( @@ -87,9 +111,6 @@ func NewAgentLoop( ) *AgentLoop { registry := NewAgentRegistry(cfg, provider) - // Register shared tools to all agents - registerSharedTools(cfg, msgBus, registry, provider) - // Set up shared fallback chain cooldown := providers.NewCooldownTracker() fallbackChain := providers.NewFallbackChain(cooldown) @@ -101,21 +122,30 @@ func NewAgentLoop( stateManager = state.NewManager(defaultAgent.Workspace) } + eventBus := NewEventBus() al := &AgentLoop{ bus: msgBus, cfg: cfg, registry: registry, state: stateManager, + eventBus: eventBus, summarizing: sync.Map{}, fallback: fallbackChain, cmdRegistry: commands.NewRegistry(commands.BuiltinDefinitions()), + steering: newSteeringQueue(parseSteeringMode(cfg.Agents.Defaults.SteeringMode)), } + al.hooks = NewHookManager(eventBus) + configureHookManagerFromConfig(al.hooks, cfg) + + // Register shared tools to all agents (now that al is created) + registerSharedTools(al, cfg, msgBus, registry, provider) return al } // registerSharedTools registers tools that are shared across all agents (web, message, spawn). func registerSharedTools( + al *AgentLoop, cfg *config.Config, msgBus *bus.MessageBus, registry *AgentRegistry, @@ -241,6 +271,67 @@ func registerSharedTools( if (spawnEnabled || spawnStatusEnabled) && cfg.Tools.IsToolEnabled("subagent") { subagentManager := tools.NewSubagentManager(provider, agent.Model, agent.Workspace) subagentManager.SetLLMOptions(agent.MaxTokens, agent.Temperature) + + // Set the spawner that links into AgentLoop's turnState + subagentManager.SetSpawner(func( + ctx context.Context, + task, label, targetAgentID string, + tls *tools.ToolRegistry, + maxTokens int, + temperature float64, + hasMaxTokens, hasTemperature bool, + ) (*tools.ToolResult, error) { + // 1. Recover parent Turn State from Context + parentTS := turnStateFromContext(ctx) + if parentTS == nil { + // Fallback: If no turnState exists in context, create an isolated ad-hoc root turn state + // so that the tool can still function outside of an agent loop (e.g. tests, raw invocations). + parentTS = &turnState{ + ctx: ctx, + turnID: "adhoc-root", + depth: 0, + session: nil, // Ephemeral session not needed for adhoc spawn + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, 5), + } + } + + // 2. Build Tools slice from registry + var tlSlice []tools.Tool + for _, name := range tls.List() { + if t, ok := tls.Get(name); ok { + tlSlice = append(tlSlice, t) + } + } + + // 3. System Prompt + systemPrompt := "You are a subagent. Complete the given task independently and report the result.\n" + + "You have access to tools - use them as needed to complete your task.\n" + + "After completing the task, provide a clear summary of what was done.\n\n" + + "Task: " + task + + // 4. Resolve Model + modelToUse := agent.Model + if targetAgentID != "" { + if targetAgent, ok := al.GetRegistry().GetAgent(targetAgentID); ok { + modelToUse = targetAgent.Model + } + } + + // 5. Build SubTurnConfig + cfg := SubTurnConfig{ + Model: modelToUse, + Tools: tlSlice, + SystemPrompt: systemPrompt, + } + if hasMaxTokens { + cfg.MaxTokens = maxTokens + } + + // 6. Spawn SubTurn + return spawnSubTurn(ctx, al, parentTS, cfg) + }) + // Clone the parent's tool registry so subagents can use all // tools registered so far (file, web, etc.) but NOT spawn/ // spawn_status which are added below — preventing recursive @@ -248,11 +339,18 @@ func registerSharedTools( subagentManager.SetTools(agent.Tools.Clone()) if spawnEnabled { spawnTool := tools.NewSpawnTool(subagentManager) + spawnTool.SetSpawner(NewSubTurnSpawner(al)) currentAgentID := agentID spawnTool.SetAllowlistChecker(func(targetAgentID string) bool { return registry.CanSpawnSubagent(currentAgentID, targetAgentID) }) + agent.Tools.Register(spawnTool) + + // Also register the synchronous subagent tool + subagentTool := tools.NewSubagentTool(subagentManager) + subagentTool.SetSpawner(NewSubTurnSpawner(al)) + agent.Tools.Register(subagentTool) } if spawnStatusEnabled { agent.Tools.Register(tools.NewSpawnStatusTool(subagentManager)) @@ -266,6 +364,9 @@ func registerSharedTools( func (al *AgentLoop) Run(ctx context.Context) error { al.running.Store(true) + if err := al.ensureHooksInitialized(ctx); err != nil { + return err + } if err := al.ensureMCPInitialized(ctx); err != nil { return err } @@ -278,6 +379,17 @@ func (al *AgentLoop) Run(ctx context.Context) error { if !ok { return nil } + + // Start a goroutine that drains the bus while processMessage is + // running. Only messages that resolve to the active turn scope are + // redirected into steering; other inbound messages are requeued. + drainCancel := func() {} + if activeScope, activeAgentID, ok := al.resolveSteeringTarget(msg); ok { + drainCtx, cancel := context.WithCancel(ctx) + drainCancel = cancel + go al.drainBusToSteering(drainCtx, activeScope, activeAgentID) + } + // Process message func() { defer func() { @@ -298,43 +410,95 @@ func (al *AgentLoop) Run(ctx context.Context) error { // } // }() + drainCanceled := false + cancelDrain := func() { + if drainCanceled { + return + } + drainCancel() + drainCanceled = true + } + defer cancelDrain() + response, err := al.processMessage(ctx, msg) if err != nil { response = fmt.Sprintf("Error processing message: %v", err) } + finalResponse := response - if response != "" { - // Check if the message tool already sent a response during this round. - // If so, skip publishing to avoid duplicate messages to the user. - // Use default agent's tools to check (message tool is shared). - alreadySent := false - defaultAgent := al.GetRegistry().GetDefaultAgent() - if defaultAgent != nil { - if tool, ok := defaultAgent.Tools.Get("message"); ok { - if mt, ok := tool.(*tools.MessageTool); ok { - alreadySent = mt.HasSentInRound() - } - } - } - if !alreadySent { - al.bus.PublishOutbound(ctx, bus.OutboundMessage{ - Channel: msg.Channel, - ChatID: msg.ChatID, - Content: response, + target, targetErr := al.buildContinuationTarget(msg) + if targetErr != nil { + logger.WarnCF("agent", "Failed to build steering continuation target", + map[string]any{ + "channel": msg.Channel, + "error": targetErr.Error(), }) - logger.InfoCF("agent", "Published outbound response", - map[string]any{ - "channel": msg.Channel, - "chat_id": msg.ChatID, - "content_len": len(response), - }) - } else { - logger.DebugCF( - "agent", - "Skipped outbound (message tool already sent)", - map[string]any{"channel": msg.Channel}, - ) + return + } + if target == nil { + cancelDrain() + if finalResponse != "" { + al.publishResponseIfNeeded(ctx, msg.Channel, msg.ChatID, finalResponse) } + return + } + + for al.pendingSteeringCountForScope(target.SessionKey) > 0 { + logger.InfoCF("agent", "Continuing queued steering after turn end", + map[string]any{ + "channel": target.Channel, + "chat_id": target.ChatID, + "session_key": target.SessionKey, + "queue_depth": al.pendingSteeringCountForScope(target.SessionKey), + }) + + continued, continueErr := al.Continue(ctx, target.SessionKey, target.Channel, target.ChatID) + if continueErr != nil { + logger.WarnCF("agent", "Failed to continue queued steering", + map[string]any{ + "channel": target.Channel, + "chat_id": target.ChatID, + "error": continueErr.Error(), + }) + return + } + if continued == "" { + return + } + + finalResponse = continued + } + + cancelDrain() + + for al.pendingSteeringCountForScope(target.SessionKey) > 0 { + logger.InfoCF("agent", "Draining steering queued during turn shutdown", + map[string]any{ + "channel": target.Channel, + "chat_id": target.ChatID, + "session_key": target.SessionKey, + "queue_depth": al.pendingSteeringCountForScope(target.SessionKey), + }) + + continued, continueErr := al.Continue(ctx, target.SessionKey, target.Channel, target.ChatID) + if continueErr != nil { + logger.WarnCF("agent", "Failed to continue queued steering after shutdown drain", + map[string]any{ + "channel": target.Channel, + "chat_id": target.ChatID, + "error": continueErr.Error(), + }) + return + } + if continued == "" { + break + } + + finalResponse = continued + } + + if finalResponse != "" { + al.publishResponseIfNeeded(ctx, target.Channel, target.ChatID, finalResponse) } }() default: @@ -345,10 +509,135 @@ func (al *AgentLoop) Run(ctx context.Context) error { return nil } +// drainBusToSteering consumes inbound messages and redirects messages from the +// active scope into the steering queue. Messages from other scopes are requeued +// so they can be processed normally after the active turn. It drains all +// immediately available messages, blocking for the first one until ctx is done. +func (al *AgentLoop) drainBusToSteering(ctx context.Context, activeScope, activeAgentID string) { + blocking := true + for { + var msg bus.InboundMessage + + if blocking { + // Block waiting for the first available message or ctx cancellation. + select { + case <-ctx.Done(): + return + case m, ok := <-al.bus.InboundChan(): + if !ok { + return + } + msg = m + } + } else { + // Non-blocking: drain any remaining queued messages, return when empty. + select { + case m, ok := <-al.bus.InboundChan(): + if !ok { + return + } + msg = m + default: + return + } + } + blocking = false + + msgScope, _, scopeOK := al.resolveSteeringTarget(msg) + if !scopeOK || msgScope != activeScope { + if err := al.requeueInboundMessage(msg); err != nil { + logger.WarnCF("agent", "Failed to requeue non-steering inbound message", map[string]any{ + "error": err.Error(), + "channel": msg.Channel, + "sender_id": msg.SenderID, + }) + } + continue + } + + // Transcribe audio if needed before steering, so the agent sees text. + msg, _ = al.transcribeAudioInMessage(ctx, msg) + + logger.InfoCF("agent", "Redirecting inbound message to steering queue", + map[string]any{ + "channel": msg.Channel, + "sender_id": msg.SenderID, + "content_len": len(msg.Content), + "scope": activeScope, + }) + + if err := al.enqueueSteeringMessage(activeScope, activeAgentID, providers.Message{ + Role: "user", + Content: msg.Content, + Media: append([]string(nil), msg.Media...), + }); err != nil { + logger.WarnCF("agent", "Failed to steer message, will be lost", + map[string]any{ + "error": err.Error(), + "channel": msg.Channel, + }) + } + } +} + func (al *AgentLoop) Stop() { al.running.Store(false) } +func (al *AgentLoop) publishResponseIfNeeded(ctx context.Context, channel, chatID, response string) { + if response == "" { + return + } + + alreadySent := false + defaultAgent := al.GetRegistry().GetDefaultAgent() + if defaultAgent != nil { + if tool, ok := defaultAgent.Tools.Get("message"); ok { + if mt, ok := tool.(*tools.MessageTool); ok { + alreadySent = mt.HasSentInRound() + } + } + } + + if alreadySent { + logger.DebugCF( + "agent", + "Skipped outbound (message tool already sent)", + map[string]any{"channel": channel}, + ) + return + } + + al.bus.PublishOutbound(ctx, bus.OutboundMessage{ + Channel: channel, + ChatID: chatID, + Content: response, + }) + logger.InfoCF("agent", "Published outbound response", + map[string]any{ + "channel": channel, + "chat_id": chatID, + "content_len": len(response), + }) +} + +func (al *AgentLoop) buildContinuationTarget(msg bus.InboundMessage) (*continuationTarget, error) { + if msg.Channel == "system" { + return nil, nil + } + + route, _, err := al.resolveMessageRoute(msg) + if err != nil { + return nil, err + } + + return &continuationTarget{ + SessionKey: resolveScopeKey(route, msg.SessionKey), + Channel: msg.Channel, + ChatID: msg.ChatID, + }, nil +} + // Close releases resources held by agent session stores. Call after Stop. func (al *AgentLoop) Close() { mcpManager := al.mcp.takeManager() @@ -363,6 +652,232 @@ func (al *AgentLoop) Close() { } al.GetRegistry().Close() + if al.hooks != nil { + al.hooks.Close() + } + if al.eventBus != nil { + al.eventBus.Close() + } +} + +// MountHook registers an in-process hook on the agent loop. +func (al *AgentLoop) MountHook(reg HookRegistration) error { + if al == nil || al.hooks == nil { + return fmt.Errorf("hook manager is not initialized") + } + return al.hooks.Mount(reg) +} + +// UnmountHook removes a previously registered in-process hook. +func (al *AgentLoop) UnmountHook(name string) { + if al == nil || al.hooks == nil { + return + } + al.hooks.Unmount(name) +} + +// SubscribeEvents registers a subscriber for agent-loop events. +func (al *AgentLoop) SubscribeEvents(buffer int) EventSubscription { + if al == nil || al.eventBus == nil { + ch := make(chan Event) + close(ch) + return EventSubscription{C: ch} + } + return al.eventBus.Subscribe(buffer) +} + +// UnsubscribeEvents removes a previously registered event subscriber. +func (al *AgentLoop) UnsubscribeEvents(id uint64) { + if al == nil || al.eventBus == nil { + return + } + al.eventBus.Unsubscribe(id) +} + +// EventDrops returns the number of dropped events for the given kind. +func (al *AgentLoop) EventDrops(kind EventKind) int64 { + if al == nil || al.eventBus == nil { + return 0 + } + return al.eventBus.Dropped(kind) +} + +type turnEventScope struct { + agentID string + sessionKey string + turnID string +} + +func (al *AgentLoop) newTurnEventScope(agentID, sessionKey string) turnEventScope { + seq := al.turnSeq.Add(1) + return turnEventScope{ + agentID: agentID, + sessionKey: sessionKey, + turnID: fmt.Sprintf("%s-turn-%d", agentID, seq), + } +} + +func (ts turnEventScope) meta(iteration int, source, tracePath string) EventMeta { + return EventMeta{ + AgentID: ts.agentID, + TurnID: ts.turnID, + SessionKey: ts.sessionKey, + Iteration: iteration, + Source: source, + TracePath: tracePath, + } +} + +func (al *AgentLoop) emitEvent(kind EventKind, meta EventMeta, payload any) { + evt := Event{ + Kind: kind, + Meta: meta, + Payload: payload, + } + + if al == nil || al.eventBus == nil { + return + } + + al.logEvent(evt) + + al.eventBus.Emit(evt) +} + +func cloneEventArguments(args map[string]any) map[string]any { + if len(args) == 0 { + return nil + } + + cloned := make(map[string]any, len(args)) + for k, v := range args { + cloned[k] = v + } + return cloned +} + +func (al *AgentLoop) hookAbortError(ts *turnState, stage string, decision HookDecision) error { + reason := decision.Reason + if reason == "" { + reason = "hook requested turn abort" + } + + err := fmt.Errorf("hook aborted turn during %s: %s", stage, reason) + al.emitEvent( + EventKindError, + ts.eventMeta("hooks", "turn.error"), + ErrorPayload{ + Stage: "hook." + stage, + Message: err.Error(), + }, + ) + return err +} + +func hookDeniedToolContent(prefix, reason string) string { + if reason == "" { + return prefix + } + return prefix + ": " + reason +} + +func (al *AgentLoop) logEvent(evt Event) { + fields := map[string]any{ + "event_kind": evt.Kind.String(), + "agent_id": evt.Meta.AgentID, + "turn_id": evt.Meta.TurnID, + "session_key": evt.Meta.SessionKey, + "iteration": evt.Meta.Iteration, + } + + if evt.Meta.TracePath != "" { + fields["trace"] = evt.Meta.TracePath + } + if evt.Meta.Source != "" { + fields["source"] = evt.Meta.Source + } + + switch payload := evt.Payload.(type) { + case TurnStartPayload: + fields["channel"] = payload.Channel + fields["chat_id"] = payload.ChatID + fields["user_len"] = len(payload.UserMessage) + fields["media_count"] = payload.MediaCount + case TurnEndPayload: + fields["status"] = payload.Status + fields["iterations_total"] = payload.Iterations + fields["duration_ms"] = payload.Duration.Milliseconds() + fields["final_len"] = payload.FinalContentLen + case LLMRequestPayload: + fields["model"] = payload.Model + fields["messages"] = payload.MessagesCount + fields["tools"] = payload.ToolsCount + fields["max_tokens"] = payload.MaxTokens + case LLMDeltaPayload: + fields["content_delta_len"] = payload.ContentDeltaLen + fields["reasoning_delta_len"] = payload.ReasoningDeltaLen + case LLMResponsePayload: + fields["content_len"] = payload.ContentLen + fields["tool_calls"] = payload.ToolCalls + fields["has_reasoning"] = payload.HasReasoning + case LLMRetryPayload: + fields["attempt"] = payload.Attempt + fields["max_retries"] = payload.MaxRetries + fields["reason"] = payload.Reason + fields["error"] = payload.Error + fields["backoff_ms"] = payload.Backoff.Milliseconds() + case ContextCompressPayload: + fields["reason"] = payload.Reason + fields["dropped_messages"] = payload.DroppedMessages + fields["remaining_messages"] = payload.RemainingMessages + case SessionSummarizePayload: + fields["summarized_messages"] = payload.SummarizedMessages + fields["kept_messages"] = payload.KeptMessages + fields["summary_len"] = payload.SummaryLen + fields["omitted_oversized"] = payload.OmittedOversized + case ToolExecStartPayload: + fields["tool"] = payload.Tool + fields["args_count"] = len(payload.Arguments) + case ToolExecEndPayload: + fields["tool"] = payload.Tool + fields["duration_ms"] = payload.Duration.Milliseconds() + fields["for_llm_len"] = payload.ForLLMLen + fields["for_user_len"] = payload.ForUserLen + fields["is_error"] = payload.IsError + fields["async"] = payload.Async + case ToolExecSkippedPayload: + fields["tool"] = payload.Tool + fields["reason"] = payload.Reason + case SteeringInjectedPayload: + fields["count"] = payload.Count + fields["total_content_len"] = payload.TotalContentLen + case FollowUpQueuedPayload: + fields["source_tool"] = payload.SourceTool + fields["channel"] = payload.Channel + fields["chat_id"] = payload.ChatID + fields["content_len"] = payload.ContentLen + case InterruptReceivedPayload: + fields["interrupt_kind"] = payload.Kind + fields["role"] = payload.Role + fields["content_len"] = payload.ContentLen + fields["queue_depth"] = payload.QueueDepth + fields["hint_len"] = payload.HintLen + case SubTurnSpawnPayload: + fields["child_agent_id"] = payload.AgentID + fields["label"] = payload.Label + case SubTurnEndPayload: + fields["child_agent_id"] = payload.AgentID + fields["status"] = payload.Status + case SubTurnResultDeliveredPayload: + fields["target_channel"] = payload.TargetChannel + fields["target_chat_id"] = payload.TargetChatID + fields["content_len"] = payload.ContentLen + case ErrorPayload: + fields["stage"] = payload.Stage + fields["error"] = payload.Message + } + + logger.InfoCF("eventbus", fmt.Sprintf("Agent event: %s", evt.Kind.String()), fields) } func (al *AgentLoop) RegisterTool(tool tools.Tool) { @@ -432,7 +947,7 @@ func (al *AgentLoop) ReloadProviderAndConfig( } // Ensure shared tools are re-registered on the new registry - registerSharedTools(cfg, al.bus, registry, provider) + registerSharedTools(al, cfg, al.bus, registry, provider) // Atomically swap the config and registry under write lock // This ensures readers see a consistent pair @@ -448,6 +963,9 @@ func (al *AgentLoop) ReloadProviderAndConfig( al.mu.Unlock() + al.hookRuntime.reset(al) + configureHookManagerFromConfig(al.hooks, cfg) + // Close old provider after releasing the lock // This prevents blocking readers while closing if oldProvider, ok := extractProvider(oldRegistry); ok { @@ -667,6 +1185,9 @@ func (al *AgentLoop) ProcessDirectWithChannel( ctx context.Context, content, sessionKey, channel, chatID string, ) (string, error) { + if err := al.ensureHooksInitialized(ctx); err != nil { + return "", err + } if err := al.ensureMCPInitialized(ctx); err != nil { return "", err } @@ -688,6 +1209,13 @@ func (al *AgentLoop) ProcessHeartbeat( ctx context.Context, content, channel, chatID string, ) (string, error) { + if err := al.ensureHooksInitialized(ctx); err != nil { + return "", err + } + if err := al.ensureMCPInitialized(ctx); err != nil { + return "", err + } + agent := al.GetRegistry().GetDefaultAgent() if agent == nil { return "", fmt.Errorf("no default agent for heartbeat") @@ -814,6 +1342,32 @@ func resolveScopeKey(route routing.ResolvedRoute, msgSessionKey string) string { return route.SessionKey } +func (al *AgentLoop) resolveSteeringTarget(msg bus.InboundMessage) (string, string, bool) { + if msg.Channel == "system" { + return "", "", false + } + + route, agent, err := al.resolveMessageRoute(msg) + if err != nil || agent == nil { + return "", "", false + } + + return resolveScopeKey(route, msg.SessionKey), agent.ID, true +} + +func (al *AgentLoop) requeueInboundMessage(msg bus.InboundMessage) error { + if al.bus == nil { + return nil + } + pubCtx, cancel := context.WithTimeout(context.Background(), time.Second) + defer cancel() + return al.bus.PublishOutbound(pubCtx, bus.OutboundMessage{ + Channel: msg.Channel, + ChatID: msg.ChatID, + Content: msg.Content, + }) +} + func (al *AgentLoop) processSystemMessage( ctx context.Context, msg bus.InboundMessage, @@ -879,44 +1433,27 @@ func (al *AgentLoop) processSystemMessage( }) } -// runAgentLoop is the core message processing logic. +// runAgentLoop remains the top-level shell that starts a turn and publishes +// any post-turn work. runTurn owns the full turn lifecycle. func (al *AgentLoop) runAgentLoop( ctx context.Context, agent *AgentInstance, opts processOptions, ) (string, error) { - // 0. Record last channel for heartbeat notifications (skip internal channels and cli) - if opts.Channel != "" && opts.ChatID != "" { - if !constants.IsInternalChannel(opts.Channel) { - channelKey := fmt.Sprintf("%s:%s", opts.Channel, opts.ChatID) - if err := al.RecordLastChannel(channelKey); err != nil { - logger.WarnCF( - "agent", - "Failed to record last channel", - map[string]any{"error": err.Error()}, - ) - } + // Record last channel for heartbeat notifications (skip internal channels and cli) + if opts.Channel != "" && opts.ChatID != "" && !constants.IsInternalChannel(opts.Channel) { + channelKey := fmt.Sprintf("%s:%s", opts.Channel, opts.ChatID) + if err := al.RecordLastChannel(channelKey); err != nil { + logger.WarnCF( + "agent", + "Failed to record last channel", + map[string]any{"error": err.Error()}, + ) } } - // 1. Build messages (skip history for heartbeat) - var history []providers.Message - var summary string - if !opts.NoHistory { - history = agent.Sessions.GetHistory(opts.SessionKey) - summary = agent.Sessions.GetSummary(opts.SessionKey) - } - messages := agent.ContextBuilder.BuildMessages( - history, - summary, - opts.UserMessage, - opts.Media, - opts.Channel, - opts.ChatID, - opts.SenderID, - opts.SenderDisplayName, - ) - + ts := newTurnState(agent, opts, al.newTurnEventScope(agent.ID, opts.SessionKey)) + result, err := al.runTurn(ctx, ts) // Resolve media:// refs: images→base64 data URLs, non-images→local paths in content cfg := al.GetConfig() maxMediaSize := cfg.Agents.Defaults.GetMaxMediaSize() @@ -930,6 +1467,9 @@ func (al *AgentLoop) runAgentLoop( if err != nil { return "", err } + if result.status == TurnEndStatusAborted { + return "", nil + } if responseHandled { agent.Sessions.Save(opts.SessionKey) @@ -947,44 +1487,36 @@ func (al *AgentLoop) runAgentLoop( return "", nil } - // 4. Handle empty response - if finalContent == "" { - if iteration >= agent.MaxIterations && agent.MaxIterations > 0 { - finalContent = toolLimitResponse - } else { - finalContent = opts.DefaultResponse + for _, followUp := range result.followUps { + if pubErr := al.bus.PublishInbound(ctx, followUp); pubErr != nil { + logger.WarnCF("agent", "Failed to publish follow-up after turn", + map[string]any{ + "turn_id": ts.turnID, + "error": pubErr.Error(), + }) } } - // 5. Save final assistant message to session - agent.Sessions.AddMessage(opts.SessionKey, "assistant", finalContent) - agent.Sessions.Save(opts.SessionKey) - - // 6. Optional: summarization - if opts.EnableSummary { - al.maybeSummarize(agent, opts.SessionKey, opts.Channel, opts.ChatID) - } - - // 7. Optional: send response via bus - if opts.SendResponse { + if opts.SendResponse && result.finalContent != "" { al.bus.PublishOutbound(ctx, bus.OutboundMessage{ Channel: opts.Channel, ChatID: opts.ChatID, - Content: finalContent, + Content: result.finalContent, }) } - // 8. Log response - responsePreview := utils.Truncate(finalContent, 120) - logger.InfoCF("agent", fmt.Sprintf("Response: %s", responsePreview), - map[string]any{ - "agent_id": agent.ID, - "session_key": opts.SessionKey, - "iterations": iteration, - "final_length": len(finalContent), - }) + if result.finalContent != "" { + responsePreview := utils.Truncate(result.finalContent, 120) + logger.InfoCF("agent", fmt.Sprintf("Response: %s", responsePreview), + map[string]any{ + "agent_id": agent.ID, + "session_key": opts.SessionKey, + "iterations": ts.currentIteration(), + "final_length": len(result.finalContent), + }) + } - return finalContent, nil + return result.finalContent, nil } func (al *AgentLoop) targetReasoningChannelID(channelName string) (chatID string) { @@ -1045,6 +1577,113 @@ func (al *AgentLoop) handleReasoning( const handledToolResponseSummary = "Requested output delivered via tool attachment." +func (al *AgentLoop) runTurn(ctx context.Context, ts *turnState) (turnResult, error) { + turnCtx, turnCancel := context.WithCancel(ctx) + defer turnCancel() + ts.setTurnCancel(turnCancel) + + // Inject turnState and AgentLoop into context so tools (e.g. spawn) can retrieve them. + turnCtx = withTurnState(turnCtx, ts) + turnCtx = WithAgentLoop(turnCtx, al) + + al.registerActiveTurn(ts) + defer al.clearActiveTurn(ts) + + turnStatus := TurnEndStatusCompleted + defer func() { + al.emitEvent( + EventKindTurnEnd, + ts.eventMeta("runTurn", "turn.end"), + TurnEndPayload{ + Status: turnStatus, + Iterations: ts.currentIteration(), + Duration: time.Since(ts.startedAt), + FinalContentLen: ts.finalContentLen(), + }, + ) + }() + + al.emitEvent( + EventKindTurnStart, + ts.eventMeta("runTurn", "turn.start"), + TurnStartPayload{ + Channel: ts.channel, + ChatID: ts.chatID, + UserMessage: ts.userMessage, + MediaCount: len(ts.media), + }, + ) + + var history []providers.Message + var summary string + if !ts.opts.NoHistory { + history = ts.agent.Sessions.GetHistory(ts.sessionKey) + summary = ts.agent.Sessions.GetSummary(ts.sessionKey) + } + ts.captureRestorePoint(history, summary) + + messages := ts.agent.ContextBuilder.BuildMessages( + history, + summary, + ts.userMessage, + ts.media, + ts.channel, + ts.chatID, + ts.opts.SenderID, + ts.opts.SenderDisplayName, + ) + + cfg := al.GetConfig() + maxMediaSize := cfg.Agents.Defaults.GetMaxMediaSize() + messages = resolveMediaRefs(messages, al.mediaStore, maxMediaSize) + + if !ts.opts.NoHistory { + toolDefs := ts.agent.Tools.ToProviderDefs() + if isOverContextBudget(ts.agent.ContextWindow, messages, toolDefs, ts.agent.MaxTokens) { + logger.WarnCF("agent", "Proactive compression: context budget exceeded before LLM call", + map[string]any{"session_key": ts.sessionKey}) + if compression, ok := al.forceCompression(ts.agent, ts.sessionKey); ok { + al.emitEvent( + EventKindContextCompress, + ts.eventMeta("runTurn", "turn.context.compress"), + ContextCompressPayload{ + Reason: ContextCompressReasonProactive, + DroppedMessages: compression.DroppedMessages, + RemainingMessages: compression.RemainingMessages, + }, + ) + ts.refreshRestorePointFromSession(ts.agent) + } + newHistory := ts.agent.Sessions.GetHistory(ts.sessionKey) + newSummary := ts.agent.Sessions.GetSummary(ts.sessionKey) + messages = ts.agent.ContextBuilder.BuildMessages( + newHistory, newSummary, ts.userMessage, + ts.media, ts.channel, ts.chatID, + ts.opts.SenderID, ts.opts.SenderDisplayName, + ) + messages = resolveMediaRefs(messages, al.mediaStore, maxMediaSize) + } + } + + // Save user message to session (from Incoming) + if !ts.opts.NoHistory && (strings.TrimSpace(ts.userMessage) != "" || len(ts.media) > 0) { + rootMsg := providers.Message{ + Role: "user", + Content: ts.userMessage, + Media: append([]string(nil), ts.media...), + } + if len(rootMsg.Media) > 0 { + ts.agent.Sessions.AddFullMessage(ts.sessionKey, rootMsg) + } else { + ts.agent.Sessions.AddMessage(ts.sessionKey, rootMsg.Role, rootMsg.Content) + } + ts.recordPersistedMessage(rootMsg) + } + + activeCandidates, activeModel := al.selectCandidates(ts.agent, ts.userMessage, messages) + pendingMessages := append([]providers.Message(nil), ts.opts.InitialSteeringMessages...) +const handledToolResponseSummary = "Requested output delivered via tool attachment." + func (al *AgentLoop) buildOutboundMediaMessage( channel string, chatID string, @@ -1097,110 +1736,224 @@ func (al *AgentLoop) runLLMIteration( iteration := 0 var finalContent string - // Check if both the provider and channel support streaming - streamProvider, providerCanStream := agent.Provider.(providers.StreamingProvider) - var streamer bus.Streamer - if providerCanStream && !opts.NoHistory && !constants.IsInternalChannel(opts.Channel) { - streamer, _ = al.bus.GetStreamer(ctx, opts.Channel, opts.ChatID) - } +turnLoop: + for ts.currentIteration() < ts.agent.MaxIterations || len(pendingMessages) > 0 || func() bool { + graceful, _ := ts.gracefulInterruptRequested() + return graceful + }() { + if ts.hardAbortRequested() { + turnStatus = TurnEndStatusAborted + return al.abortTurn(ts) + } - // Determine effective model tier for this conversation turn. - // selectCandidates evaluates routing once and the decision is sticky for - // all tool-follow-up iterations within the same turn so that a multi-step - // tool chain doesn't switch models mid-way through. - activeCandidates, activeModel := al.selectCandidates(agent, opts.UserMessage, messages) + iteration := ts.currentIteration() + 1 + ts.setIteration(iteration) + ts.setPhase(TurnPhaseRunning) - for iteration < agent.MaxIterations { - iteration++ + if iteration > 1 { + if steerMsgs := al.dequeueSteeringMessagesForScope(ts.sessionKey); len(steerMsgs) > 0 { + pendingMessages = append(pendingMessages, steerMsgs...) + } + } else if !ts.opts.SkipInitialSteeringPoll { + if steerMsgs := al.dequeueSteeringMessagesForScopeWithFallback(ts.sessionKey); len(steerMsgs) > 0 { + pendingMessages = append(pendingMessages, steerMsgs...) + } + } + + // Check if parent turn has ended (SubTurn support from HEAD) + if ts.parentTurnState != nil && ts.IsParentEnded() { + if !ts.critical { + logger.InfoCF("agent", "Parent turn ended, non-critical SubTurn exiting gracefully", map[string]any{ + "agent_id": ts.agentID, + "iteration": iteration, + "turn_id": ts.turnID, + }) + break + } + logger.InfoCF("agent", "Parent turn ended, critical SubTurn continues running", map[string]any{ + "agent_id": ts.agentID, + "iteration": iteration, + "turn_id": ts.turnID, + }) + } + + // Poll for pending SubTurn results (from HEAD) + if ts.pendingResults != nil { + select { + case result, ok := <-ts.pendingResults: + if ok && result != nil && result.ForLLM != "" { + msg := providers.Message{Role: "user", Content: fmt.Sprintf("[SubTurn Result] %s", result.ForLLM)} + pendingMessages = append(pendingMessages, msg) + } + default: + // No results available + } + } + + // Inject pending steering messages + if len(pendingMessages) > 0 { + resolvedPending := resolveMediaRefs(pendingMessages, al.mediaStore, maxMediaSize) + totalContentLen := 0 + for i, pm := range pendingMessages { + messages = append(messages, resolvedPending[i]) + totalContentLen += len(pm.Content) + if !ts.opts.NoHistory { + ts.agent.Sessions.AddFullMessage(ts.sessionKey, pm) + ts.recordPersistedMessage(pm) + } + logger.InfoCF("agent", "Injected steering message into context", + map[string]any{ + "agent_id": ts.agent.ID, + "iteration": iteration, + "content_len": len(pm.Content), + "media_count": len(pm.Media), + }) + } + al.emitEvent( + EventKindSteeringInjected, + ts.eventMeta("runTurn", "turn.steering.injected"), + SteeringInjectedPayload{ + Count: len(pendingMessages), + TotalContentLen: totalContentLen, + }, + ) + pendingMessages = nil + } logger.DebugCF("agent", "LLM iteration", map[string]any{ - "agent_id": agent.ID, + "agent_id": ts.agent.ID, "iteration": iteration, - "max": agent.MaxIterations, + "max": ts.agent.MaxIterations, }) - // Build tool definitions - providerToolDefs := agent.Tools.ToProviderDefs() + gracefulTerminal, _ := ts.gracefulInterruptRequested() + providerToolDefs := ts.agent.Tools.ToProviderDefs() - // Determine whether the provider's native web search should replace - // the client-side web_search tool for this request. Only enable when web - // search is actually enabled and registered (so users who disabled web - // access do not get provider-side search or billing). - _, hasWebSearch := agent.Tools.Get("web_search") + // Native web search support (from HEAD) + _, hasWebSearch := ts.agent.Tools.Get("web_search") useNativeSearch := al.cfg.Tools.Web.PreferNative && - isNativeSearchProvider(agent.Provider) && - hasWebSearch + hasWebSearch && + func() bool { + // Check if provider supports native search + if ns, ok := ts.agent.Provider.(interface{ SupportsNativeSearch() bool }); ok { + return ns.SupportsNativeSearch() + } + return false + }() if useNativeSearch { - providerToolDefs = filterClientWebSearch(providerToolDefs) + // Filter out client-side web_search tool + filtered := make([]providers.ToolDefinition, 0, len(providerToolDefs)) + for _, td := range providerToolDefs { + if td.Function.Name != "web_search" { + filtered = append(filtered, td) + } + } + providerToolDefs = filtered } - // Log LLM request details - logger.DebugCF("agent", "LLM request", - map[string]any{ - "agent_id": agent.ID, - "iteration": iteration, - "model": activeModel, - "messages_count": len(messages), - "tools_count": len(providerToolDefs), - "native_search": useNativeSearch, - "max_tokens": agent.MaxTokens, - "temperature": agent.Temperature, - "system_prompt_len": len(messages[0].Content), - }) - - // Log full messages (detailed) - logger.DebugCF("agent", "Full LLM request", - map[string]any{ - "iteration": iteration, - "messages_json": formatMessagesForLog(messages), - "tools_json": formatToolsForLog(providerToolDefs), - }) - - // Call LLM with fallback chain if multiple candidates are configured. - var response *providers.LLMResponse - var err error + callMessages := messages + if gracefulTerminal { + callMessages = append(append([]providers.Message(nil), messages...), ts.interruptHintMessage()) + providerToolDefs = nil + ts.markGracefulTerminalUsed() + } llmOpts := map[string]any{ - "max_tokens": agent.MaxTokens, - "temperature": agent.Temperature, - "prompt_cache_key": agent.ID, + "max_tokens": ts.agent.MaxTokens, + "temperature": ts.agent.Temperature, + "prompt_cache_key": ts.agent.ID, } if useNativeSearch { llmOpts["native_search"] = true } - // parseThinkingLevel guarantees ThinkingOff for empty/unknown values, - // so checking != ThinkingOff is sufficient. - if agent.ThinkingLevel != ThinkingOff { - if tc, ok := agent.Provider.(providers.ThinkingCapable); ok && tc.SupportsThinking() { - llmOpts["thinking_level"] = string(agent.ThinkingLevel) + if ts.agent.ThinkingLevel != ThinkingOff { + if tc, ok := ts.agent.Provider.(providers.ThinkingCapable); ok && tc.SupportsThinking() { + llmOpts["thinking_level"] = string(ts.agent.ThinkingLevel) } else { logger.WarnCF("agent", "thinking_level is set but current provider does not support it, ignoring", - map[string]any{"agent_id": agent.ID, "thinking_level": string(agent.ThinkingLevel)}) + map[string]any{"agent_id": ts.agent.ID, "thinking_level": string(ts.agent.ThinkingLevel)}) } } - callLLM := func() (*providers.LLMResponse, error) { + llmModel := activeModel + if al.hooks != nil { + llmReq, decision := al.hooks.BeforeLLM(turnCtx, &LLMHookRequest{ + Meta: ts.eventMeta("runTurn", "turn.llm.request"), + Model: llmModel, + Messages: callMessages, + Tools: providerToolDefs, + Options: llmOpts, + Channel: ts.channel, + ChatID: ts.chatID, + GracefulTerminal: gracefulTerminal, + }) + switch decision.normalizedAction() { + case HookActionContinue, HookActionModify: + if llmReq != nil { + llmModel = llmReq.Model + callMessages = llmReq.Messages + providerToolDefs = llmReq.Tools + llmOpts = llmReq.Options + } + case HookActionAbortTurn: + turnStatus = TurnEndStatusError + return turnResult{}, al.hookAbortError(ts, "before_llm", decision) + case HookActionHardAbort: + _ = ts.requestHardAbort() + turnStatus = TurnEndStatusAborted + return al.abortTurn(ts) + } + } + + al.emitEvent( + EventKindLLMRequest, + ts.eventMeta("runTurn", "turn.llm.request"), + LLMRequestPayload{ + Model: llmModel, + MessagesCount: len(callMessages), + ToolsCount: len(providerToolDefs), + MaxTokens: ts.agent.MaxTokens, + Temperature: ts.agent.Temperature, + }, + ) + + logger.DebugCF("agent", "LLM request", + map[string]any{ + "agent_id": ts.agent.ID, + "iteration": iteration, + "model": llmModel, + "messages_count": len(callMessages), + "tools_count": len(providerToolDefs), + "max_tokens": ts.agent.MaxTokens, + "temperature": ts.agent.Temperature, + "system_prompt_len": len(callMessages[0].Content), + }) + logger.DebugCF("agent", "Full LLM request", + map[string]any{ + "iteration": iteration, + "messages_json": formatMessagesForLog(callMessages), + "tools_json": formatToolsForLog(providerToolDefs), + }) + + callLLM := func(messagesForCall []providers.Message, toolDefsForCall []providers.ToolDefinition) (*providers.LLMResponse, error) { + providerCtx, providerCancel := context.WithCancel(turnCtx) + ts.setProviderCancel(providerCancel) + defer func() { + providerCancel() + ts.clearProviderCancel(providerCancel) + }() + al.activeRequests.Add(1) defer al.activeRequests.Done() - // Use streaming when available (streamer obtained, provider supports it) - if streamer != nil && streamProvider != nil { - return streamProvider.ChatStream( - ctx, messages, providerToolDefs, activeModel, llmOpts, - func(accumulated string) { - streamer.Update(ctx, accumulated) - }, - ) - } - if len(activeCandidates) > 1 && al.fallback != nil { fbResult, fbErr := al.fallback.Execute( - ctx, + providerCtx, activeCandidates, func(ctx context.Context, provider, model string) (*providers.LLMResponse, error) { - return agent.Provider.Chat(ctx, messages, providerToolDefs, model, llmOpts) + return ts.agent.Provider.Chat(ctx, messagesForCall, toolDefsForCall, model, llmOpts) }, ) if fbErr != nil { @@ -1211,32 +1964,34 @@ func (al *AgentLoop) runLLMIteration( "agent", fmt.Sprintf("Fallback: succeeded with %s/%s after %d attempts", fbResult.Provider, fbResult.Model, len(fbResult.Attempts)+1), - map[string]any{"agent_id": agent.ID, "iteration": iteration}, + map[string]any{"agent_id": ts.agent.ID, "iteration": iteration}, ) } return fbResult.Response, nil } - return agent.Provider.Chat(ctx, messages, providerToolDefs, activeModel, llmOpts) + return ts.agent.Provider.Chat(providerCtx, messagesForCall, toolDefsForCall, llmModel, llmOpts) } - // Retry loop for context/token errors + var response *providers.LLMResponse + var err error maxRetries := 2 for retry := 0; retry <= maxRetries; retry++ { - response, err = callLLM() + response, err = callLLM(callMessages, providerToolDefs) if err == nil { break } + if ts.hardAbortRequested() && errors.Is(err, context.Canceled) { + turnStatus = TurnEndStatusAborted + return al.abortTurn(ts) + } errMsg := strings.ToLower(err.Error()) - - // Check if this is a network/HTTP timeout — not a context window error. isTimeoutError := errors.Is(err, context.DeadlineExceeded) || strings.Contains(errMsg, "deadline exceeded") || strings.Contains(errMsg, "client.timeout") || strings.Contains(errMsg, "timed out") || strings.Contains(errMsg, "timeout exceeded") - // Detect real context window / token limit errors, excluding network timeouts. isContextError := !isTimeoutError && (strings.Contains(errMsg, "context_length_exceeded") || strings.Contains(errMsg, "context window") || strings.Contains(errMsg, "maximum context length") || @@ -1249,16 +2004,44 @@ func (al *AgentLoop) runLLMIteration( if isTimeoutError && retry < maxRetries { backoff := time.Duration(retry+1) * 5 * time.Second + al.emitEvent( + EventKindLLMRetry, + ts.eventMeta("runTurn", "turn.llm.retry"), + LLMRetryPayload{ + Attempt: retry + 1, + MaxRetries: maxRetries, + Reason: "timeout", + Error: err.Error(), + Backoff: backoff, + }, + ) logger.WarnCF("agent", "Timeout error, retrying after backoff", map[string]any{ "error": err.Error(), "retry": retry, "backoff": backoff.String(), }) - time.Sleep(backoff) + if sleepErr := sleepWithContext(turnCtx, backoff); sleepErr != nil { + if ts.hardAbortRequested() { + turnStatus = TurnEndStatusAborted + return al.abortTurn(ts) + } + err = sleepErr + break + } continue } - if isContextError && retry < maxRetries { + if isContextError && retry < maxRetries && !ts.opts.NoHistory { + al.emitEvent( + EventKindLLMRetry, + ts.eventMeta("runTurn", "turn.llm.retry"), + LLMRetryPayload{ + Attempt: retry + 1, + MaxRetries: maxRetries, + Reason: "context_limit", + Error: err.Error(), + }, + ) logger.WarnCF( "agent", "Context window error detected, attempting compression", @@ -1268,73 +2051,142 @@ func (al *AgentLoop) runLLMIteration( }, ) - if retry == 0 && !constants.IsInternalChannel(opts.Channel) { + if retry == 0 && !constants.IsInternalChannel(ts.channel) { al.bus.PublishOutbound(ctx, bus.OutboundMessage{ - Channel: opts.Channel, - ChatID: opts.ChatID, + Channel: ts.channel, + ChatID: ts.chatID, Content: "Context window exceeded. Compressing history and retrying...", }) } - al.forceCompression(agent, opts.SessionKey) - newHistory := agent.Sessions.GetHistory(opts.SessionKey) - newSummary := agent.Sessions.GetSummary(opts.SessionKey) - messages = agent.ContextBuilder.BuildMessages( + if compression, ok := al.forceCompression(ts.agent, ts.sessionKey); ok { + al.emitEvent( + EventKindContextCompress, + ts.eventMeta("runTurn", "turn.context.compress"), + ContextCompressPayload{ + Reason: ContextCompressReasonRetry, + DroppedMessages: compression.DroppedMessages, + RemainingMessages: compression.RemainingMessages, + }, + ) + ts.refreshRestorePointFromSession(ts.agent) + } + + newHistory := ts.agent.Sessions.GetHistory(ts.sessionKey) + newSummary := ts.agent.Sessions.GetSummary(ts.sessionKey) + messages = ts.agent.ContextBuilder.BuildMessages( newHistory, newSummary, "", - nil, opts.Channel, opts.ChatID, opts.SenderID, opts.SenderDisplayName, + nil, ts.channel, ts.chatID, + "", "", // Empty SenderID and SenderDisplayName for retry ) + callMessages = messages + if gracefulTerminal { + callMessages = append(append([]providers.Message(nil), messages...), ts.interruptHintMessage()) + } continue } break } if err != nil { + turnStatus = TurnEndStatusError + al.emitEvent( + EventKindError, + ts.eventMeta("runTurn", "turn.error"), + ErrorPayload{ + Stage: "llm", + Message: err.Error(), + }, + ) logger.ErrorCF("agent", "LLM call failed", map[string]any{ - "agent_id": agent.ID, + "agent_id": ts.agent.ID, "iteration": iteration, - "model": activeModel, + "model": llmModel, "error": err.Error(), }) + return turnResult{}, fmt.Errorf("LLM call failed after retries: %w", err) + } + + if al.hooks != nil { + llmResp, decision := al.hooks.AfterLLM(turnCtx, &LLMHookResponse{ + Meta: ts.eventMeta("runTurn", "turn.llm.response"), + Model: llmModel, + Response: response, + Channel: ts.channel, + ChatID: ts.chatID, + }) + switch decision.normalizedAction() { + case HookActionContinue, HookActionModify: + if llmResp != nil && llmResp.Response != nil { + response = llmResp.Response + } + case HookActionAbortTurn: + turnStatus = TurnEndStatusError + return turnResult{}, al.hookAbortError(ts, "after_llm", decision) + case HookActionHardAbort: + _ = ts.requestHardAbort() + turnStatus = TurnEndStatusAborted + return al.abortTurn(ts) + } + } + + // Save finishReason to turnState for SubTurn truncation detection + if innerTS := turnStateFromContext(ctx); innerTS != nil { + innerTS.SetLastFinishReason(response.FinishReason) + // Save usage for token budget tracking + if response.Usage != nil { + innerTS.SetLastUsage(response.Usage) + } return "", iteration, false, fmt.Errorf("LLM call failed after retries: %w", err) } go al.handleReasoning( - ctx, + turnCtx, response.Reasoning, - opts.Channel, - al.targetReasoningChannelID(opts.Channel), + ts.channel, + al.targetReasoningChannelID(ts.channel), + ) + al.emitEvent( + EventKindLLMResponse, + ts.eventMeta("runTurn", "turn.llm.response"), + LLMResponsePayload{ + ContentLen: len(response.Content), + ToolCalls: len(response.ToolCalls), + HasReasoning: response.Reasoning != "" || response.ReasoningContent != "", + }, ) logger.DebugCF("agent", "LLM response", map[string]any{ - "agent_id": agent.ID, + "agent_id": ts.agent.ID, "iteration": iteration, "content_chars": len(response.Content), "tool_calls": len(response.ToolCalls), "reasoning": response.Reasoning, - "target_channel": al.targetReasoningChannelID(opts.Channel), - "channel": opts.Channel, + "target_channel": al.targetReasoningChannelID(ts.channel), + "channel": ts.channel, }) - // Check if no tool calls - then check reasoning content if any - if len(response.ToolCalls) == 0 { - finalContent = response.Content - if finalContent == "" && response.ReasoningContent != "" { - finalContent = response.ReasoningContent - } - // If we were streaming, finalize the message (sends the permanent message) - if streamer != nil { - if err := streamer.Finalize(ctx, finalContent); err != nil { - logger.WarnCF("agent", "Stream finalize failed", map[string]any{ - "error": err.Error(), + if len(response.ToolCalls) == 0 || gracefulTerminal { + responseContent := response.Content + if responseContent == "" && response.ReasoningContent != "" { + responseContent = response.ReasoningContent + } + if steerMsgs := al.dequeueSteeringMessagesForScope(ts.sessionKey); len(steerMsgs) > 0 { + logger.InfoCF("agent", "Steering arrived after direct LLM response; continuing turn", + map[string]any{ + "agent_id": ts.agent.ID, + "iteration": iteration, + "steering_count": len(steerMsgs), }) - } + pendingMessages = append(pendingMessages, steerMsgs...) + continue } - + finalContent = responseContent logger.InfoCF("agent", "LLM response without tool calls (direct answer)", map[string]any{ - "agent_id": agent.ID, + "agent_id": ts.agent.ID, "iteration": iteration, "content_chars": len(finalContent), "streamed": streamer != nil, @@ -1342,30 +2194,23 @@ func (al *AgentLoop) runLLMIteration( break } - // Tool calls detected — cancel any active stream (draft auto-expires) - if streamer != nil { - streamer.Cancel(ctx) - } - normalizedToolCalls := make([]providers.ToolCall, 0, len(response.ToolCalls)) for _, tc := range response.ToolCalls { normalizedToolCalls = append(normalizedToolCalls, providers.NormalizeToolCall(tc)) } - // Log tool calls toolNames := make([]string, 0, len(normalizedToolCalls)) for _, tc := range normalizedToolCalls { toolNames = append(toolNames, tc.Name) } logger.InfoCF("agent", "LLM requested tool calls", map[string]any{ - "agent_id": agent.ID, + "agent_id": ts.agent.ID, "tools": toolNames, "count": len(normalizedToolCalls), "iteration": iteration, }) - // Build assistant message with tool calls assistantMsg := providers.Message{ Role: "assistant", Content: response.Content, @@ -1373,13 +2218,11 @@ func (al *AgentLoop) runLLMIteration( } for _, tc := range normalizedToolCalls { argumentsJSON, _ := json.Marshal(tc.Arguments) - // Copy ExtraContent to ensure thought_signature is persisted for Gemini 3 extraContent := tc.ExtraContent thoughtSignature := "" if tc.Function != nil { thoughtSignature = tc.Function.ThoughtSignature } - assistantMsg.ToolCalls = append(assistantMsg.ToolCalls, providers.ToolCall{ ID: tc.ID, Type: "function", @@ -1394,104 +2237,231 @@ func (al *AgentLoop) runLLMIteration( }) } messages = append(messages, assistantMsg) - - // Save assistant message with tool calls to session - agent.Sessions.AddFullMessage(opts.SessionKey, assistantMsg) - - // Execute tool calls in parallel - type indexedAgentResult struct { - result *tools.ToolResult - tc providers.ToolCall + if !ts.opts.NoHistory { + ts.agent.Sessions.AddFullMessage(ts.sessionKey, assistantMsg) + ts.recordPersistedMessage(assistantMsg) } - agentResults := make([]indexedAgentResult, len(normalizedToolCalls)) - var wg sync.WaitGroup - + ts.setPhase(TurnPhaseTools) for i, tc := range normalizedToolCalls { - agentResults[i].tc = tc + if ts.hardAbortRequested() { + turnStatus = TurnEndStatusAborted + return al.abortTurn(ts) + } - wg.Add(1) - go func(idx int, tc providers.ToolCall) { - defer wg.Done() + toolName := tc.Name + toolArgs := cloneStringAnyMap(tc.Arguments) - argsJSON, _ := json.Marshal(tc.Arguments) - argsPreview := utils.Truncate(string(argsJSON), 200) - logger.InfoCF("agent", fmt.Sprintf("Tool call: %s(%s)", tc.Name, argsPreview), - map[string]any{ - "agent_id": agent.ID, - "tool": tc.Name, - "iteration": iteration, - }) - - // Send tool feedback to chat channel if enabled - if al.cfg.Agents.Defaults.IsToolFeedbackEnabled() && opts.Channel != "" { - feedbackPreview := utils.Truncate( - string(argsJSON), - al.cfg.Agents.Defaults.GetToolFeedbackMaxArgsLength(), + if al.hooks != nil { + toolReq, decision := al.hooks.BeforeTool(turnCtx, &ToolCallHookRequest{ + Meta: ts.eventMeta("runTurn", "turn.tool.before"), + Tool: toolName, + Arguments: toolArgs, + Channel: ts.channel, + ChatID: ts.chatID, + }) + switch decision.normalizedAction() { + case HookActionContinue, HookActionModify: + if toolReq != nil { + toolName = toolReq.Tool + toolArgs = toolReq.Arguments + } + case HookActionDenyTool: + denyContent := hookDeniedToolContent("Tool execution denied by hook", decision.Reason) + al.emitEvent( + EventKindToolExecSkipped, + ts.eventMeta("runTurn", "turn.tool.skipped"), + ToolExecSkippedPayload{ + Tool: toolName, + Reason: denyContent, + }, ) - feedbackMsg := fmt.Sprintf("\U0001f527 `%s`\n```\n%s\n```", tc.Name, feedbackPreview) - fbCtx, fbCancel := context.WithTimeout(ctx, 3*time.Second) - _ = al.bus.PublishOutbound(fbCtx, bus.OutboundMessage{ - Channel: opts.Channel, - ChatID: opts.ChatID, - Content: feedbackMsg, - }) - fbCancel() - } - - // Create async callback for tools that implement AsyncExecutor. - // When the background work completes, this publishes the result - // as an inbound system message so processSystemMessage routes it - // back to the user via the normal agent loop. - asyncCallback := func(_ context.Context, result *tools.ToolResult) { - // Send ForUser content directly to the user (immediate feedback), - // mirroring the synchronous tool execution path. - if !result.Silent && result.ForUser != "" { - outCtx, outCancel := context.WithTimeout(context.Background(), 5*time.Second) - defer outCancel() - _ = al.bus.PublishOutbound(outCtx, bus.OutboundMessage{ - Channel: opts.Channel, - ChatID: opts.ChatID, - Content: result.ForUser, - }) + deniedMsg := providers.Message{ + Role: "tool", + Content: denyContent, + ToolCallID: tc.ID, } - - // Determine content for the agent loop (ForLLM or error). - content := result.ContentForLLM() - if content == "" { - return + messages = append(messages, deniedMsg) + if !ts.opts.NoHistory { + ts.agent.Sessions.AddFullMessage(ts.sessionKey, deniedMsg) + ts.recordPersistedMessage(deniedMsg) } - - logger.InfoCF("agent", "Async tool completed, publishing result", - map[string]any{ - "tool": tc.Name, - "content_len": len(content), - "channel": opts.Channel, - }) - - pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second) - defer pubCancel() - _ = al.bus.PublishInbound(pubCtx, bus.InboundMessage{ - Channel: "system", - SenderID: fmt.Sprintf("async:%s", tc.Name), - ChatID: fmt.Sprintf("%s:%s", opts.Channel, opts.ChatID), - Content: content, - }) + continue + case HookActionAbortTurn: + turnStatus = TurnEndStatusError + return turnResult{}, al.hookAbortError(ts, "before_tool", decision) + case HookActionHardAbort: + _ = ts.requestHardAbort() + turnStatus = TurnEndStatusAborted + return al.abortTurn(ts) } + } - toolResult := agent.Tools.ExecuteWithContext( - ctx, - tc.Name, - tc.Arguments, - opts.Channel, - opts.ChatID, - asyncCallback, + if al.hooks != nil { + approval := al.hooks.ApproveTool(turnCtx, &ToolApprovalRequest{ + Meta: ts.eventMeta("runTurn", "turn.tool.approve"), + Tool: toolName, + Arguments: toolArgs, + Channel: ts.channel, + ChatID: ts.chatID, + }) + if !approval.Approved { + denyContent := hookDeniedToolContent("Tool execution denied by approval hook", approval.Reason) + al.emitEvent( + EventKindToolExecSkipped, + ts.eventMeta("runTurn", "turn.tool.skipped"), + ToolExecSkippedPayload{ + Tool: toolName, + Reason: denyContent, + }, + ) + deniedMsg := providers.Message{ + Role: "tool", + Content: denyContent, + ToolCallID: tc.ID, + } + messages = append(messages, deniedMsg) + if !ts.opts.NoHistory { + ts.agent.Sessions.AddFullMessage(ts.sessionKey, deniedMsg) + ts.recordPersistedMessage(deniedMsg) + } + continue + } + } + + argsJSON, _ := json.Marshal(toolArgs) + argsPreview := utils.Truncate(string(argsJSON), 200) + logger.InfoCF("agent", fmt.Sprintf("Tool call: %s(%s)", toolName, argsPreview), + map[string]any{ + "agent_id": ts.agent.ID, + "tool": toolName, + "iteration": iteration, + }) + al.emitEvent( + EventKindToolExecStart, + ts.eventMeta("runTurn", "turn.tool.start"), + ToolExecStartPayload{ + Tool: toolName, + Arguments: cloneEventArguments(toolArgs), + }, + ) + + // Send tool feedback to chat channel if enabled (from HEAD) + if al.cfg.Agents.Defaults.IsToolFeedbackEnabled() && ts.channel != "" { + feedbackPreview := utils.Truncate( + string(argsJSON), + al.cfg.Agents.Defaults.GetToolFeedbackMaxArgsLength(), ) - agentResults[idx].result = toolResult - }(i, tc) - } - wg.Wait() + feedbackMsg := fmt.Sprintf("\U0001f527 `%s`\n```\n%s\n```", tc.Name, feedbackPreview) + fbCtx, fbCancel := context.WithTimeout(turnCtx, 3*time.Second) + _ = al.bus.PublishOutbound(fbCtx, bus.OutboundMessage{ + Channel: ts.channel, + ChatID: ts.chatID, + Content: feedbackMsg, + }) + fbCancel() + } + toolCallID := tc.ID + toolIteration := iteration + asyncToolName := toolName + asyncCallback := func(_ context.Context, result *tools.ToolResult) { + // Send ForUser content directly to the user (immediate feedback), + // mirroring the synchronous tool execution path. + if !result.Silent && result.ForUser != "" { + outCtx, outCancel := context.WithTimeout(context.Background(), 5*time.Second) + defer outCancel() + _ = al.bus.PublishOutbound(outCtx, bus.OutboundMessage{ + Channel: ts.channel, + ChatID: ts.chatID, + Content: result.ForUser, + }) + } + + // Determine content for the agent loop (ForLLM or error). + content := result.ContentForLLM() + if content == "" { + return + } + + logger.InfoCF("agent", "Async tool completed, publishing result", + map[string]any{ + "tool": asyncToolName, + "content_len": len(content), + "channel": ts.channel, + }) + al.emitEvent( + EventKindFollowUpQueued, + ts.scope.meta(toolIteration, "runTurn", "turn.follow_up.queued"), + FollowUpQueuedPayload{ + SourceTool: asyncToolName, + Channel: ts.channel, + ChatID: ts.chatID, + ContentLen: len(content), + }, + ) + + pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second) + defer pubCancel() + _ = al.bus.PublishInbound(pubCtx, bus.InboundMessage{ + Channel: "system", + SenderID: fmt.Sprintf("async:%s", asyncToolName), + ChatID: fmt.Sprintf("%s:%s", ts.channel, ts.chatID), + Content: content, + }) + } + + toolStart := time.Now() + toolResult := ts.agent.Tools.ExecuteWithContext( + turnCtx, + toolName, + toolArgs, + ts.channel, + ts.chatID, + asyncCallback, + ) + toolDuration := time.Since(toolStart) + + if ts.hardAbortRequested() { + turnStatus = TurnEndStatusAborted + return al.abortTurn(ts) + } + + if al.hooks != nil { + toolResp, decision := al.hooks.AfterTool(turnCtx, &ToolResultHookResponse{ + Meta: ts.eventMeta("runTurn", "turn.tool.after"), + Tool: toolName, + Arguments: toolArgs, + Result: toolResult, + Duration: toolDuration, + Channel: ts.channel, + ChatID: ts.chatID, + }) + switch decision.normalizedAction() { + case HookActionContinue, HookActionModify: + if toolResp != nil { + if toolResp.Tool != "" { + toolName = toolResp.Tool + } + if toolResp.Result != nil { + toolResult = toolResp.Result + } + } + case HookActionAbortTurn: + turnStatus = TurnEndStatusError + return turnResult{}, al.hookAbortError(ts, "after_tool", decision) + case HookActionHardAbort: + _ = ts.requestHardAbort() + turnStatus = TurnEndStatusAborted + return al.abortTurn(ts) + } + } + + if toolResult == nil { + toolResult = tools.ErrorResult("hook returned nil tool result") + } + + if !toolResult.Silent && toolResult.ForUser != "" && ts.opts.SendResponse { allResponsesHandled := len(agentResults) > 0 // Process results in original order (send to user, save to session) @@ -1503,17 +2473,26 @@ func (al *AgentLoop) runLLMIteration( // Send ForUser content to user immediately if not Silent if !r.result.Silent && r.result.ForUser != "" && opts.SendResponse { al.bus.PublishOutbound(ctx, bus.OutboundMessage{ - Channel: opts.Channel, - ChatID: opts.ChatID, - Content: r.result.ForUser, + Channel: ts.channel, + ChatID: ts.chatID, + Content: toolResult.ForUser, }) logger.DebugCF("agent", "Sent tool result to user", map[string]any{ - "tool": r.tc.Name, - "content_len": len(r.result.ForUser), + "tool": toolName, + "content_len": len(toolResult.ForUser), }) } + if len(toolResult.Media) > 0 { + parts := make([]bus.MediaPart, 0, len(toolResult.Media)) + for _, ref := range toolResult.Media { + part := bus.MediaPart{Ref: ref} + if al.mediaStore != nil { + if _, meta, err := al.mediaStore.ResolveWithMeta(ref); err == nil { + part.Filename = meta.Filename + part.ContentType = meta.ContentType + part.Type = inferMediaType(meta.Filename, meta.ContentType) // If tool returned media refs, publish them as outbound media only when the // tool explicitly marked the user-visible delivery as already handled. if len(r.result.Media) > 0 { @@ -1533,9 +2512,18 @@ func (al *AgentLoop) runLLMIteration( } else { al.bus.PublishOutboundMedia(ctx, outboundMedia) } + parts = append(parts, part) } + al.bus.PublishOutboundMedia(ctx, bus.OutboundMediaMessage{ + Channel: ts.channel, + ChatID: ts.chatID, + Parts: parts, + }) } + contentForLLM := toolResult.ForLLM + if contentForLLM == "" && toolResult.Err != nil { + contentForLLM = toolResult.Err.Error() // Determine content for LLM based on tool result if len(r.result.Media) > 0 && !r.result.ResponseHandled { r.result.ArtifactTags = al.buildArtifactTags(r.result.Media) @@ -1545,14 +2533,91 @@ func (al *AgentLoop) runLLMIteration( toolResultMsg := providers.Message{ Role: "tool", Content: contentForLLM, - ToolCallID: r.tc.ID, + ToolCallID: toolCallID, } + al.emitEvent( + EventKindToolExecEnd, + ts.eventMeta("runTurn", "turn.tool.end"), + ToolExecEndPayload{ + Tool: toolName, + Duration: toolDuration, + ForLLMLen: len(contentForLLM), + ForUserLen: len(toolResult.ForUser), + IsError: toolResult.IsError, + Async: toolResult.Async, + }, + ) messages = append(messages, toolResultMsg) + if !ts.opts.NoHistory { + ts.agent.Sessions.AddFullMessage(ts.sessionKey, toolResultMsg) + ts.recordPersistedMessage(toolResultMsg) + } - // Save tool result message to session - agent.Sessions.AddFullMessage(opts.SessionKey, toolResultMsg) + if steerMsgs := al.dequeueSteeringMessagesForScope(ts.sessionKey); len(steerMsgs) > 0 { + pendingMessages = append(pendingMessages, steerMsgs...) + } + + skipReason := "" + skipMessage := "" + if len(pendingMessages) > 0 { + skipReason = "queued user steering message" + skipMessage = "Skipped due to queued user message." + } else if gracefulPending, _ := ts.gracefulInterruptRequested(); gracefulPending { + skipReason = "graceful interrupt requested" + skipMessage = "Skipped due to graceful interrupt." + } + + if skipReason != "" { + remaining := len(normalizedToolCalls) - i - 1 + if remaining > 0 { + logger.InfoCF("agent", "Turn checkpoint: skipping remaining tools", + map[string]any{ + "agent_id": ts.agent.ID, + "completed": i + 1, + "skipped": remaining, + "reason": skipReason, + }) + for j := i + 1; j < len(normalizedToolCalls); j++ { + skippedTC := normalizedToolCalls[j] + al.emitEvent( + EventKindToolExecSkipped, + ts.eventMeta("runTurn", "turn.tool.skipped"), + ToolExecSkippedPayload{ + Tool: skippedTC.Name, + Reason: skipReason, + }, + ) + skippedMsg := providers.Message{ + Role: "tool", + Content: skipMessage, + ToolCallID: skippedTC.ID, + } + messages = append(messages, skippedMsg) + if !ts.opts.NoHistory { + ts.agent.Sessions.AddFullMessage(ts.sessionKey, skippedMsg) + ts.recordPersistedMessage(skippedMsg) + } + } + } + break + } + + // Also poll for any SubTurn results that arrived during tool execution. + if ts.pendingResults != nil { + select { + case result, ok := <-ts.pendingResults: + if ok && result != nil && result.ForLLM != "" { + msg := providers.Message{Role: "user", Content: fmt.Sprintf("[SubTurn Result] %s", result.ForLLM)} + messages = append(messages, msg) + ts.agent.Sessions.AddFullMessage(ts.sessionKey, msg) + } + default: + // No results available + } + } } + ts.agent.Tools.TickTTL() if allResponsesHandled { summaryMsg := providers.Message{ Role: "assistant", @@ -1578,11 +2643,96 @@ func (al *AgentLoop) runLLMIteration( // ToProviderDefs and Get must be re-evaluated. agent.Tools.TickTTL() logger.DebugCF("agent", "TTL tick after tool execution", map[string]any{ - "agent_id": agent.ID, "iteration": iteration, + "agent_id": ts.agent.ID, "iteration": iteration, }) } + if steerMsgs := al.dequeueSteeringMessagesForScope(ts.sessionKey); len(steerMsgs) > 0 { + logger.InfoCF("agent", "Steering arrived after turn completion; continuing turn before finalizing", + map[string]any{ + "agent_id": ts.agent.ID, + "steering_count": len(steerMsgs), + "session_key": ts.sessionKey, + }) + pendingMessages = append(pendingMessages, steerMsgs...) + finalContent = "" + goto turnLoop + } + + if ts.hardAbortRequested() { + turnStatus = TurnEndStatusAborted + return al.abortTurn(ts) + } + return finalContent, iteration, false, nil + if finalContent == "" { + if ts.currentIteration() >= ts.agent.MaxIterations && ts.agent.MaxIterations > 0 { + finalContent = toolLimitResponse + } else { + finalContent = ts.opts.DefaultResponse + } + } + + ts.setPhase(TurnPhaseFinalizing) + ts.setFinalContent(finalContent) + if !ts.opts.NoHistory { + finalMsg := providers.Message{Role: "assistant", Content: finalContent} + ts.agent.Sessions.AddMessage(ts.sessionKey, finalMsg.Role, finalMsg.Content) + ts.recordPersistedMessage(finalMsg) + if err := ts.agent.Sessions.Save(ts.sessionKey); err != nil { + turnStatus = TurnEndStatusError + al.emitEvent( + EventKindError, + ts.eventMeta("runTurn", "turn.error"), + ErrorPayload{ + Stage: "session_save", + Message: err.Error(), + }, + ) + return turnResult{}, err + } + } + + if ts.opts.EnableSummary { + al.maybeSummarize(ts.agent, ts.sessionKey, ts.scope) + } + + ts.setPhase(TurnPhaseCompleted) + return turnResult{ + finalContent: finalContent, + status: turnStatus, + followUps: append([]bus.InboundMessage(nil), ts.followUps...), + }, nil +} + +func (al *AgentLoop) abortTurn(ts *turnState) (turnResult, error) { + ts.setPhase(TurnPhaseAborted) + if !ts.opts.NoHistory { + if err := ts.restoreSession(ts.agent); err != nil { + al.emitEvent( + EventKindError, + ts.eventMeta("abortTurn", "turn.error"), + ErrorPayload{ + Stage: "session_restore", + Message: err.Error(), + }, + ) + return turnResult{}, err + } + } + return turnResult{status: TurnEndStatusAborted}, nil +} + +func sleepWithContext(ctx context.Context, d time.Duration) error { + timer := time.NewTimer(d) + defer timer.Stop() + + select { + case <-ctx.Done(): + return ctx.Err() + case <-timer.C: + return nil + } } // selectCandidates returns the model candidates and resolved model name to use @@ -1624,7 +2774,7 @@ func (al *AgentLoop) selectCandidates( } // maybeSummarize triggers summarization if the session history exceeds thresholds. -func (al *AgentLoop) maybeSummarize(agent *AgentInstance, sessionKey, channel, chatID string) { +func (al *AgentLoop) maybeSummarize(agent *AgentInstance, sessionKey string, turnScope turnEventScope) { newHistory := agent.Sessions.GetHistory(sessionKey) tokenEstimate := al.estimateTokens(newHistory) threshold := agent.ContextWindow * agent.SummarizeTokenPercent / 100 @@ -1635,63 +2785,91 @@ func (al *AgentLoop) maybeSummarize(agent *AgentInstance, sessionKey, channel, c go func() { defer al.summarizing.Delete(summarizeKey) logger.Debug("Memory threshold reached. Optimizing conversation history...") - al.summarizeSession(agent, sessionKey) + al.summarizeSession(agent, sessionKey, turnScope) }() } } } +type compressionResult struct { + DroppedMessages int + RemainingMessages int +} + // forceCompression aggressively reduces context when the limit is hit. -// It drops the oldest 50% of messages (keeping system prompt and last user message). -func (al *AgentLoop) forceCompression(agent *AgentInstance, sessionKey string) { +// It drops the oldest ~50% of Turns (a Turn is a complete user→LLM→response +// cycle, as defined in #1316), so tool-call sequences are never split. +// +// If the history is a single Turn with no safe split point, the function +// falls back to keeping only the most recent user message. This breaks +// Turn atomicity as a last resort to avoid a context-exceeded loop. +// +// Session history contains only user/assistant/tool messages — the system +// prompt is built dynamically by BuildMessages and is NOT stored here. +// The compression note is recorded in the session summary so that +// BuildMessages can include it in the next system prompt. +func (al *AgentLoop) forceCompression(agent *AgentInstance, sessionKey string) (compressionResult, bool) { history := agent.Sessions.GetHistory(sessionKey) - if len(history) <= 4 { - return + if len(history) <= 2 { + return compressionResult{}, false } - // Keep system prompt (usually [0]) and the very last message (user's trigger) - // We want to drop the oldest half of the *conversation* - // Assuming [0] is system, [1:] is conversation - conversation := history[1 : len(history)-1] - if len(conversation) == 0 { - return + // Split at a Turn boundary so no tool-call sequence is torn apart. + // parseTurnBoundaries gives us the start of each Turn; we drop the + // oldest half of Turns and keep the most recent ones. + turns := parseTurnBoundaries(history) + var mid int + if len(turns) >= 2 { + mid = turns[len(turns)/2] + } else { + // Fewer than 2 Turns — fall back to message-level midpoint + // aligned to the nearest Turn boundary. + mid = findSafeBoundary(history, len(history)/2) + } + var keptHistory []providers.Message + if mid <= 0 { + // No safe Turn boundary — the entire history is a single Turn + // (e.g. one user message followed by a massive tool response). + // Keeping everything would leave the agent stuck in a context- + // exceeded loop, so fall back to keeping only the most recent + // user message. This breaks Turn atomicity as a last resort. + for i := len(history) - 1; i >= 0; i-- { + if history[i].Role == "user" { + keptHistory = []providers.Message{history[i]} + break + } + } + } else { + keptHistory = history[mid:] } - // Helper to find the mid-point of the conversation - mid := len(conversation) / 2 + droppedCount := len(history) - len(keptHistory) - // New history structure: - // 1. System Prompt (with compression note appended) - // 2. Second half of conversation - // 3. Last message - - droppedCount := mid - keptConversation := conversation[mid:] - - newHistory := make([]providers.Message, 0, 1+len(keptConversation)+1) - - // Append compression note to the original system prompt instead of adding a new system message - // This avoids having two consecutive system messages which some APIs (like Zhipu) reject + // Record compression in the session summary so BuildMessages includes it + // in the system prompt. We do not modify history messages themselves. + existingSummary := agent.Sessions.GetSummary(sessionKey) compressionNote := fmt.Sprintf( - "\n\n[System Note: Emergency compression dropped %d oldest messages due to context limit]", + "[Emergency compression dropped %d oldest messages due to context limit]", droppedCount, ) - enhancedSystemPrompt := history[0] - enhancedSystemPrompt.Content = enhancedSystemPrompt.Content + compressionNote - newHistory = append(newHistory, enhancedSystemPrompt) + if existingSummary != "" { + compressionNote = existingSummary + "\n\n" + compressionNote + } + agent.Sessions.SetSummary(sessionKey, compressionNote) - newHistory = append(newHistory, keptConversation...) - newHistory = append(newHistory, history[len(history)-1]) // Last message - - // Update session - agent.Sessions.SetHistory(sessionKey, newHistory) + agent.Sessions.SetHistory(sessionKey, keptHistory) agent.Sessions.Save(sessionKey) logger.WarnCF("agent", "Forced compression executed", map[string]any{ "session_key": sessionKey, "dropped_msgs": droppedCount, - "new_count": len(newHistory), + "new_count": len(keptHistory), }) + + return compressionResult{ + DroppedMessages: droppedCount, + RemainingMessages: len(keptHistory), + }, true } // GetStartupInfo returns information about loaded tools and skills for logging. @@ -1783,19 +2961,25 @@ func formatToolsForLog(toolDefs []providers.ToolDefinition) string { } // summarizeSession summarizes the conversation history for a session. -func (al *AgentLoop) summarizeSession(agent *AgentInstance, sessionKey string) { +func (al *AgentLoop) summarizeSession(agent *AgentInstance, sessionKey string, turnScope turnEventScope) { ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second) defer cancel() history := agent.Sessions.GetHistory(sessionKey) summary := agent.Sessions.GetSummary(sessionKey) - // Keep last 4 messages for continuity + // Keep the most recent Turns for continuity, aligned to a Turn boundary + // so that no tool-call sequence is split. if len(history) <= 4 { return } - toSummarize := history[:len(history)-4] + safeCut := findSafeBoundary(history, len(history)-4) + if safeCut <= 0 { + return + } + keepCount := len(history) - safeCut + toSummarize := history[:safeCut] // Oversized Message Guard maxMessageTokens := agent.ContextWindow / 2 @@ -1860,8 +3044,18 @@ func (al *AgentLoop) summarizeSession(agent *AgentInstance, sessionKey string) { if finalSummary != "" { agent.Sessions.SetSummary(sessionKey, finalSummary) - agent.Sessions.TruncateHistory(sessionKey, 4) + agent.Sessions.TruncateHistory(sessionKey, keepCount) agent.Sessions.Save(sessionKey) + al.emitEvent( + EventKindSessionSummarize, + turnScope.meta(0, "summarizeSession", "turn.session.summarize"), + SessionSummarizePayload{ + SummarizedMessages: len(validMessages), + KeptMessages: keepCount, + SummaryLen: len(finalSummary), + OmittedOversized: omitted, + }, + ) } } @@ -1998,15 +3192,14 @@ func (al *AgentLoop) summarizeBatch( } // estimateTokens estimates the number of tokens in a message list. -// Uses a safe heuristic of 2.5 characters per token to account for CJK and other -// overheads better than the previous 3 chars/token. +// Counts Content, ToolCalls arguments, and ToolCallID metadata so that +// tool-heavy conversations are not systematically undercounted. func (al *AgentLoop) estimateTokens(messages []providers.Message) int { - totalChars := 0 + total := 0 for _, m := range messages { - totalChars += utf8.RuneCountInString(m.Content) + total += estimateMessageTokens(m) } - // 2.5 chars per token = totalChars * 2 / 5 - return totalChars * 2 / 5 + return total } func (al *AgentLoop) handleCommand( @@ -2065,6 +3258,13 @@ func (al *AgentLoop) buildCommandsRuntime(agent *AgentInstance, opts *processOpt } return al.channelManager.GetEnabledChannels() }, + GetActiveTurn: func() any { + info := al.GetActiveTurn() + if info == nil { + return nil + } + return info + }, SwitchChannel: func(value string) error { if al.channelManager == nil { return fmt.Errorf("channel manager not initialized") diff --git a/pkg/agent/loop_test.go b/pkg/agent/loop_test.go index ea63d963..8dbc5fae 100644 --- a/pkg/agent/loop_test.go +++ b/pkg/agent/loop_test.go @@ -1374,11 +1374,11 @@ func TestAgentLoop_ContextExhaustionRetry(t *testing.T) { al := NewAgentLoop(cfg, msgBus, provider) - // Inject some history to simulate a full context + // Inject some history to simulate a full context. + // Session history only stores user/assistant/tool messages — the system + // prompt is built dynamically by BuildMessages and is NOT stored here. sessionKey := "test-session-context" - // Create dummy history history := []providers.Message{ - {Role: "system", Content: "System prompt"}, {Role: "user", Content: "Old message 1"}, {Role: "assistant", Content: "Old response 1"}, {Role: "user", Content: "Old message 2"}, @@ -1416,12 +1416,11 @@ func TestAgentLoop_ContextExhaustionRetry(t *testing.T) { // Check final history length finalHistory := defaultAgent.Sessions.GetHistory(sessionKey) // We verify that the history has been modified (compressed) - // Original length: 6 - // Expected behavior: compression drops ~50% of history (mid slice) - // We can assert that the length is NOT what it would be without compression. - // Without compression: 6 + 1 (new user msg) + 1 (assistant msg) = 8 - if len(finalHistory) >= 8 { - t.Errorf("Expected history to be compressed (len < 8), got %d", len(finalHistory)) + // Original length: 5 + // Expected behavior: compression drops ~50% of Turns + // Without compression: 5 + 1 (new user msg) + 1 (assistant msg) = 7 + if len(finalHistory) >= 7 { + t.Errorf("Expected history to be compressed (len < 7), got %d", len(finalHistory)) } } diff --git a/pkg/agent/steering.go b/pkg/agent/steering.go new file mode 100644 index 00000000..ad6613e8 --- /dev/null +++ b/pkg/agent/steering.go @@ -0,0 +1,503 @@ +package agent + +import ( + "context" + "fmt" + "strings" + "sync" + + "github.com/sipeed/picoclaw/pkg/logger" + "github.com/sipeed/picoclaw/pkg/providers" + "github.com/sipeed/picoclaw/pkg/routing" + "github.com/sipeed/picoclaw/pkg/tools" +) + +// SteeringMode controls how queued steering messages are dequeued. +type SteeringMode string + +const ( + // SteeringOneAtATime dequeues only the first queued message per poll. + SteeringOneAtATime SteeringMode = "one-at-a-time" + // SteeringAll drains the entire queue in a single poll. + SteeringAll SteeringMode = "all" + // MaxQueueSize number of possible messages in the Steering Queue + MaxQueueSize = 10 + // manualSteeringScope is the legacy fallback queue used when no active + // turn/session scope is available. + manualSteeringScope = "__manual__" +) + +// parseSteeringMode normalizes a config string into a SteeringMode. +func parseSteeringMode(s string) SteeringMode { + switch s { + case "all": + return SteeringAll + default: + return SteeringOneAtATime + } +} + +// steeringQueue is a thread-safe queue of user messages that can be injected +// into a running agent loop to interrupt it between tool calls. +type steeringQueue struct { + mu sync.Mutex + queues map[string][]providers.Message + mode SteeringMode +} + +func newSteeringQueue(mode SteeringMode) *steeringQueue { + return &steeringQueue{ + queues: make(map[string][]providers.Message), + mode: mode, + } +} + +func normalizeSteeringScope(scope string) string { + scope = strings.TrimSpace(scope) + if scope == "" { + return manualSteeringScope + } + return scope +} + +// push enqueues a steering message in the legacy fallback scope. +func (sq *steeringQueue) push(msg providers.Message) error { + return sq.pushScope(manualSteeringScope, msg) +} + +// pushScope enqueues a steering message for the provided scope. +func (sq *steeringQueue) pushScope(scope string, msg providers.Message) error { + sq.mu.Lock() + defer sq.mu.Unlock() + + scope = normalizeSteeringScope(scope) + queue := sq.queues[scope] + if len(queue) >= MaxQueueSize { + return fmt.Errorf("steering queue is full") + } + sq.queues[scope] = append(queue, msg) + return nil +} + +// dequeue removes and returns pending steering messages from the legacy +// fallback scope according to the configured mode. +func (sq *steeringQueue) dequeue() []providers.Message { + return sq.dequeueScope(manualSteeringScope) +} + +// dequeueScope removes and returns pending steering messages for the provided +// scope according to the configured mode. +func (sq *steeringQueue) dequeueScope(scope string) []providers.Message { + sq.mu.Lock() + defer sq.mu.Unlock() + + return sq.dequeueLocked(normalizeSteeringScope(scope)) +} + +// dequeueScopeWithFallback drains the scoped queue first and falls back to the +// legacy manual scope for backwards compatibility. +func (sq *steeringQueue) dequeueScopeWithFallback(scope string) []providers.Message { + sq.mu.Lock() + defer sq.mu.Unlock() + + scope = strings.TrimSpace(scope) + if scope != "" { + if msgs := sq.dequeueLocked(scope); len(msgs) > 0 { + return msgs + } + } + + return sq.dequeueLocked(manualSteeringScope) +} + +func (sq *steeringQueue) dequeueLocked(scope string) []providers.Message { + queue := sq.queues[scope] + if len(queue) == 0 { + return nil + } + + switch sq.mode { + case SteeringAll: + msgs := append([]providers.Message(nil), queue...) + delete(sq.queues, scope) + return msgs + default: + msg := queue[0] + queue[0] = providers.Message{} // Clear reference for GC + queue = queue[1:] + if len(queue) == 0 { + delete(sq.queues, scope) + } else { + sq.queues[scope] = queue + } + return []providers.Message{msg} + } +} + +// len returns the number of queued messages across all scopes. +func (sq *steeringQueue) len() int { + sq.mu.Lock() + defer sq.mu.Unlock() + + total := 0 + for _, queue := range sq.queues { + total += len(queue) + } + return total +} + +// lenScope returns the number of queued messages for a specific scope. +func (sq *steeringQueue) lenScope(scope string) int { + sq.mu.Lock() + defer sq.mu.Unlock() + return len(sq.queues[normalizeSteeringScope(scope)]) +} + +// setMode updates the steering mode. +func (sq *steeringQueue) setMode(mode SteeringMode) { + sq.mu.Lock() + defer sq.mu.Unlock() + sq.mode = mode +} + +// getMode returns the current steering mode. +func (sq *steeringQueue) getMode() SteeringMode { + sq.mu.Lock() + defer sq.mu.Unlock() + return sq.mode +} + +// Steer enqueues a user message to be injected into the currently running +// agent loop. The message will be picked up after the current tool finishes +// executing, causing any remaining tool calls in the batch to be skipped. +func (al *AgentLoop) Steer(msg providers.Message) error { + scope := "" + agentID := "" + if ts := al.getAnyActiveTurnState(); ts != nil { + scope = ts.sessionKey + agentID = ts.agentID + } + return al.enqueueSteeringMessage(scope, agentID, msg) +} + +func (al *AgentLoop) enqueueSteeringMessage(scope, agentID string, msg providers.Message) error { + if al.steering == nil { + return fmt.Errorf("steering queue is not initialized") + } + + if err := al.steering.pushScope(scope, msg); err != nil { + logger.WarnCF("agent", "Failed to enqueue steering message", map[string]any{ + "error": err.Error(), + "role": msg.Role, + "scope": normalizeSteeringScope(scope), + }) + return err + } + + queueDepth := al.steering.lenScope(scope) + logger.DebugCF("agent", "Steering message enqueued", map[string]any{ + "role": msg.Role, + "content_len": len(msg.Content), + "media_count": len(msg.Media), + "queue_len": queueDepth, + "scope": normalizeSteeringScope(scope), + }) + + meta := EventMeta{ + Source: "Steer", + TracePath: "turn.interrupt.received", + } + if ts := al.getAnyActiveTurnState(); ts != nil { + meta = ts.eventMeta("Steer", "turn.interrupt.received") + } else { + if strings.TrimSpace(agentID) != "" { + meta.AgentID = agentID + } + normalizedScope := normalizeSteeringScope(scope) + if normalizedScope != manualSteeringScope { + meta.SessionKey = normalizedScope + } + if meta.AgentID == "" { + if registry := al.GetRegistry(); registry != nil { + if agent := registry.GetDefaultAgent(); agent != nil { + meta.AgentID = agent.ID + } + } + } + } + + al.emitEvent( + EventKindInterruptReceived, + meta, + InterruptReceivedPayload{ + Kind: InterruptKindSteering, + Role: msg.Role, + ContentLen: len(msg.Content), + QueueDepth: queueDepth, + }, + ) + + return nil +} + +// SteeringMode returns the current steering mode. +func (al *AgentLoop) SteeringMode() SteeringMode { + if al.steering == nil { + return SteeringOneAtATime + } + return al.steering.getMode() +} + +// SetSteeringMode updates the steering mode. +func (al *AgentLoop) SetSteeringMode(mode SteeringMode) { + if al.steering == nil { + return + } + al.steering.setMode(mode) +} + +// dequeueSteeringMessages is the internal method called by the agent loop +// to poll for steering messages in the legacy fallback scope. +func (al *AgentLoop) dequeueSteeringMessages() []providers.Message { + if al.steering == nil { + return nil + } + return al.steering.dequeue() +} + +func (al *AgentLoop) dequeueSteeringMessagesForScope(scope string) []providers.Message { + if al.steering == nil { + return nil + } + return al.steering.dequeueScope(scope) +} + +func (al *AgentLoop) dequeueSteeringMessagesForScopeWithFallback(scope string) []providers.Message { + if al.steering == nil { + return nil + } + return al.steering.dequeueScopeWithFallback(scope) +} + +func (al *AgentLoop) pendingSteeringCountForScope(scope string) int { + if al.steering == nil { + return 0 + } + return al.steering.lenScope(scope) +} + +func (al *AgentLoop) continueWithSteeringMessages( + ctx context.Context, + agent *AgentInstance, + sessionKey, channel, chatID string, + steeringMsgs []providers.Message, +) (string, error) { + return al.runAgentLoop(ctx, agent, processOptions{ + SessionKey: sessionKey, + Channel: channel, + ChatID: chatID, + DefaultResponse: defaultResponse, + EnableSummary: true, + SendResponse: false, + InitialSteeringMessages: steeringMsgs, + SkipInitialSteeringPoll: true, + }) +} + +func (al *AgentLoop) agentForSession(sessionKey string) *AgentInstance { + registry := al.GetRegistry() + if registry == nil { + return nil + } + + if parsed := routing.ParseAgentSessionKey(sessionKey); parsed != nil { + if agent, ok := registry.GetAgent(parsed.AgentID); ok { + return agent + } + } + + return registry.GetDefaultAgent() +} + +// Continue resumes an idle agent by dequeuing any pending steering messages +// and running them through the agent loop. This is used when the agent's last +// message was from the assistant (i.e., it has stopped processing) and the +// user has since enqueued steering messages. +// +// If no steering messages are pending, it returns an empty string. +func (al *AgentLoop) Continue(ctx context.Context, sessionKey, channel, chatID string) (string, error) { + if active := al.GetActiveTurn(); active != nil { + return "", fmt.Errorf("turn %s is still active", active.TurnID) + } + if err := al.ensureHooksInitialized(ctx); err != nil { + return "", err + } + if err := al.ensureMCPInitialized(ctx); err != nil { + return "", err + } + + steeringMsgs := al.dequeueSteeringMessagesForScopeWithFallback(sessionKey) + if len(steeringMsgs) == 0 { + return "", nil + } + + agent := al.agentForSession(sessionKey) + if agent == nil { + return "", fmt.Errorf("no agent available for session %q", sessionKey) + } + + if tool, ok := agent.Tools.Get("message"); ok { + if resetter, ok := tool.(interface{ ResetSentInRound() }); ok { + resetter.ResetSentInRound() + } + } + + return al.continueWithSteeringMessages(ctx, agent, sessionKey, channel, chatID, steeringMsgs) +} + +func (al *AgentLoop) InterruptGraceful(hint string) error { + ts := al.getAnyActiveTurnState() + if ts == nil { + return fmt.Errorf("no active turn") + } + if !ts.requestGracefulInterrupt(hint) { + return fmt.Errorf("turn %s cannot accept graceful interrupt", ts.turnID) + } + + al.emitEvent( + EventKindInterruptReceived, + ts.eventMeta("InterruptGraceful", "turn.interrupt.received"), + InterruptReceivedPayload{ + Kind: InterruptKindGraceful, + HintLen: len(hint), + }, + ) + + return nil +} + +func (al *AgentLoop) InterruptHard() error { + ts := al.getAnyActiveTurnState() + if ts == nil { + return fmt.Errorf("no active turn") + } + if !ts.requestHardAbort() { + return fmt.Errorf("turn %s is already aborting", ts.turnID) + } + + al.emitEvent( + EventKindInterruptReceived, + ts.eventMeta("InterruptHard", "turn.interrupt.received"), + InterruptReceivedPayload{ + Kind: InterruptKindHard, + }, + ) + + return nil +} + +// ====================== SubTurn Result Polling ====================== + +// dequeuePendingSubTurnResults polls the SubTurn result channel for the given +// session and returns all available results without blocking. +// Returns nil if no active turn state exists for this session. +func (al *AgentLoop) dequeuePendingSubTurnResults(sessionKey string) []*tools.ToolResult { + tsInterface, ok := al.activeTurnStates.Load(sessionKey) + if !ok { + return nil + } + ts, ok := tsInterface.(*turnState) + if !ok { + return nil + } + + var results []*tools.ToolResult + for { + select { + case result, ok := <-ts.pendingResults: + if !ok { + return results + } + if result != nil { + results = append(results, result) + } + default: + return results + } + } +} + +// ====================== Hard Abort ====================== + +// HardAbort immediately cancels the running agent loop for the given session, +// cascading the cancellation to all child SubTurns. This is a destructive operation +// that terminates execution without waiting for graceful cleanup. +// +// Use this when the user explicitly requests immediate termination (e.g., "stop now", "abort"). +// For graceful interruption that allows the agent to finish the current tool and summarize, +// use Steer() instead. +func (al *AgentLoop) HardAbort(sessionKey string) error { + tsInterface, ok := al.activeTurnStates.Load(sessionKey) + if !ok { + return fmt.Errorf("no active turn state found for session %s", sessionKey) + } + + ts, ok := tsInterface.(*turnState) + if !ok { + return fmt.Errorf("invalid turn state type for session %s", sessionKey) + } + + logger.InfoCF("agent", "Hard abort triggered", map[string]any{ + "session_key": sessionKey, + "turn_id": ts.turnID, + "depth": ts.depth, + "initial_history_length": ts.initialHistoryLength, + }) + + // IMPORTANT: Trigger cascading cancellation FIRST to stop all child SubTurns + // from adding more messages to the session. This prevents race conditions + // where rollback happens while children are still writing. + // Use isHardAbort=true for hard abort to immediately cancel all children. + ts.Finish(true) + + // Roll back session history to the state before the turn started. + if ts.session != nil { + history := ts.session.GetHistory(sessionKey) + if ts.initialHistoryLength < len(history) { + ts.session.SetHistory(sessionKey, history[:ts.initialHistoryLength]) + } + } + + return nil +} + +// ====================== Follow-Up Injection ====================== + +// InjectFollowUp enqueues a message to be automatically processed after the current +// turn completes. Unlike Steer(), which interrupts the current execution, InjectFollowUp +// waits for the current turn to finish naturally before processing the message. +// +// This is useful for: +// - Automated workflows that need to chain multiple turns +// - Background tasks that should run after the main task completes +// - Scheduled follow-up actions +// +// The message will be processed via Continue() when the agent becomes idle. +func (al *AgentLoop) InjectFollowUp(msg providers.Message) error { + // InjectFollowUp uses the same steering queue mechanism as Steer(), + // but the semantic difference is in when it's called: + // - Steer() is called during active execution to interrupt + // - InjectFollowUp() is called when planning future work + // + // Both end up in the same queue and are processed by Continue() + // when the agent is idle. + return al.Steer(msg) +} + +// ====================== API Aliases for Design Document Compatibility ====================== + +// InjectSteering is an alias for Steer() to match the design document naming. +// It injects a steering message into the currently running agent loop. +func (al *AgentLoop) InjectSteering(msg providers.Message) error { + return al.Steer(msg) +} diff --git a/pkg/agent/steering_test.go b/pkg/agent/steering_test.go new file mode 100644 index 00000000..fe4863f0 --- /dev/null +++ b/pkg/agent/steering_test.go @@ -0,0 +1,1591 @@ +package agent + +import ( + "context" + "encoding/json" + "fmt" + "os" + "path/filepath" + "reflect" + "strings" + "sync" + "testing" + "time" + + "github.com/sipeed/picoclaw/pkg/bus" + "github.com/sipeed/picoclaw/pkg/config" + "github.com/sipeed/picoclaw/pkg/media" + "github.com/sipeed/picoclaw/pkg/providers" + "github.com/sipeed/picoclaw/pkg/routing" + "github.com/sipeed/picoclaw/pkg/tools" +) + +// --- steeringQueue unit tests --- + +func TestSteeringQueue_PushDequeue_OneAtATime(t *testing.T) { + sq := newSteeringQueue(SteeringOneAtATime) + + sq.push(providers.Message{Role: "user", Content: "msg1"}) + sq.push(providers.Message{Role: "user", Content: "msg2"}) + sq.push(providers.Message{Role: "user", Content: "msg3"}) + + if sq.len() != 3 { + t.Fatalf("expected 3 messages, got %d", sq.len()) + } + + msgs := sq.dequeue() + if len(msgs) != 1 { + t.Fatalf("expected 1 message in one-at-a-time mode, got %d", len(msgs)) + } + if msgs[0].Content != "msg1" { + t.Fatalf("expected 'msg1', got %q", msgs[0].Content) + } + if sq.len() != 2 { + t.Fatalf("expected 2 remaining, got %d", sq.len()) + } + + msgs = sq.dequeue() + if len(msgs) != 1 || msgs[0].Content != "msg2" { + t.Fatalf("expected 'msg2', got %v", msgs) + } + + msgs = sq.dequeue() + if len(msgs) != 1 || msgs[0].Content != "msg3" { + t.Fatalf("expected 'msg3', got %v", msgs) + } + + msgs = sq.dequeue() + if msgs != nil { + t.Fatalf("expected nil from empty queue, got %v", msgs) + } +} + +func TestSteeringQueue_PushDequeue_All(t *testing.T) { + sq := newSteeringQueue(SteeringAll) + + sq.push(providers.Message{Role: "user", Content: "msg1"}) + sq.push(providers.Message{Role: "user", Content: "msg2"}) + sq.push(providers.Message{Role: "user", Content: "msg3"}) + + msgs := sq.dequeue() + if len(msgs) != 3 { + t.Fatalf("expected 3 messages in all mode, got %d", len(msgs)) + } + if msgs[0].Content != "msg1" || msgs[1].Content != "msg2" || msgs[2].Content != "msg3" { + t.Fatalf("unexpected messages: %v", msgs) + } + + if sq.len() != 0 { + t.Fatalf("expected 0 remaining, got %d", sq.len()) + } + + msgs = sq.dequeue() + if msgs != nil { + t.Fatalf("expected nil from empty queue, got %v", msgs) + } +} + +func TestSteeringQueue_EmptyDequeue(t *testing.T) { + sq := newSteeringQueue(SteeringOneAtATime) + if msgs := sq.dequeue(); msgs != nil { + t.Fatalf("expected nil, got %v", msgs) + } +} + +func TestSteeringQueue_SetMode(t *testing.T) { + sq := newSteeringQueue(SteeringOneAtATime) + if sq.getMode() != SteeringOneAtATime { + t.Fatalf("expected one-at-a-time, got %v", sq.getMode()) + } + + sq.setMode(SteeringAll) + if sq.getMode() != SteeringAll { + t.Fatalf("expected all, got %v", sq.getMode()) + } + + // Push two messages and verify all-mode drains them + sq.push(providers.Message{Role: "user", Content: "a"}) + sq.push(providers.Message{Role: "user", Content: "b"}) + + msgs := sq.dequeue() + if len(msgs) != 2 { + t.Fatalf("expected 2 messages after mode switch, got %d", len(msgs)) + } +} + +func TestSteeringQueue_ConcurrentAccess(t *testing.T) { + sq := newSteeringQueue(SteeringOneAtATime) + + var wg sync.WaitGroup + const n = MaxQueueSize + + // Push from multiple goroutines + for i := 0; i < n; i++ { + wg.Add(1) + go func(i int) { + defer wg.Done() + sq.push(providers.Message{Role: "user", Content: fmt.Sprintf("msg%d", i)}) + }(i) + } + wg.Wait() + + if sq.len() != n { + t.Fatalf("expected %d messages, got %d", n, sq.len()) + } + + // Drain from multiple goroutines + var drained int + var mu sync.Mutex + for i := 0; i < n; i++ { + wg.Add(1) + go func() { + defer wg.Done() + if msgs := sq.dequeue(); len(msgs) > 0 { + mu.Lock() + drained += len(msgs) + mu.Unlock() + } + }() + } + wg.Wait() + + if drained != n { + t.Fatalf("expected to drain %d messages, got %d", n, drained) + } +} + +func TestSteeringQueue_Overflow(t *testing.T) { + sq := newSteeringQueue(SteeringOneAtATime) + + // Fill the queue up to its maximum capacity + for i := 0; i < MaxQueueSize; i++ { + err := sq.push(providers.Message{Role: "user", Content: fmt.Sprintf("msg%d", i)}) + if err != nil { + t.Fatalf("unexpected error pushing message %d: %v", i, err) + } + } + + // Sanity check: ensure the queue is actually full + if sq.len() != MaxQueueSize { + t.Fatalf("expected queue length %d, got %d", MaxQueueSize, sq.len()) + } + + // Attempt to push one more message, which MUST fail + err := sq.push(providers.Message{Role: "user", Content: "overflow_msg"}) + + // Assert the error happened and is the exact one we expect + if err == nil { + t.Fatal("expected an error when pushing to a full queue, but got nil") + } + + expectedErr := "steering queue is full" + if err.Error() != expectedErr { + t.Errorf("expected error message %q, got %q", expectedErr, err.Error()) + } +} + +func TestParseSteeringMode(t *testing.T) { + tests := []struct { + input string + expected SteeringMode + }{ + {"", SteeringOneAtATime}, + {"one-at-a-time", SteeringOneAtATime}, + {"all", SteeringAll}, + {"unknown", SteeringOneAtATime}, + } + + for _, tt := range tests { + t.Run(tt.input, func(t *testing.T) { + if got := parseSteeringMode(tt.input); got != tt.expected { + t.Fatalf("parseSteeringMode(%q) = %v, want %v", tt.input, got, tt.expected) + } + }) + } +} + +// --- AgentLoop steering integration tests --- + +func TestAgentLoop_Steer_Enqueues(t *testing.T) { + al, cfg, msgBus, provider, cleanup := newTestAgentLoop(t) + defer cleanup() + + if cfg == nil { + t.Fatal("expected config to be initialized") + } + if msgBus == nil { + t.Fatal("expected message bus to be initialized") + } + if provider == nil { + t.Fatal("expected provider to be initialized") + } + + al.Steer(providers.Message{Role: "user", Content: "interrupt me"}) + + if al.steering.len() != 1 { + t.Fatalf("expected 1 steering message, got %d", al.steering.len()) + } + + msgs := al.dequeueSteeringMessages() + if len(msgs) != 1 || msgs[0].Content != "interrupt me" { + t.Fatalf("unexpected dequeued message: %v", msgs) + } +} + +func TestAgentLoop_SteeringMode_GetSet(t *testing.T) { + al, cfg, msgBus, provider, cleanup := newTestAgentLoop(t) + defer cleanup() + + if cfg == nil { + t.Fatal("expected config to be initialized") + } + if msgBus == nil { + t.Fatal("expected message bus to be initialized") + } + if provider == nil { + t.Fatal("expected provider to be initialized") + } + + if al.SteeringMode() != SteeringOneAtATime { + t.Fatalf("expected default mode one-at-a-time, got %v", al.SteeringMode()) + } + + al.SetSteeringMode(SteeringAll) + if al.SteeringMode() != SteeringAll { + t.Fatalf("expected all mode, got %v", al.SteeringMode()) + } +} + +func TestAgentLoop_SteeringMode_ConfiguredFromConfig(t *testing.T) { + tmpDir, err := os.MkdirTemp("", "agent-test-*") + if err != nil { + t.Fatalf("Failed to create temp dir: %v", err) + } + defer os.RemoveAll(tmpDir) + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: tmpDir, + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + SteeringMode: "all", + }, + }, + } + + msgBus := bus.NewMessageBus() + provider := &mockProvider{} + al := NewAgentLoop(cfg, msgBus, provider) + + if al.SteeringMode() != SteeringAll { + t.Fatalf("expected 'all' mode from config, got %v", al.SteeringMode()) + } +} + +func TestAgentLoop_Continue_NoMessages(t *testing.T) { + al, cfg, msgBus, provider, cleanup := newTestAgentLoop(t) + defer cleanup() + + if cfg == nil { + t.Fatal("expected config to be initialized") + } + if msgBus == nil { + t.Fatal("expected message bus to be initialized") + } + if provider == nil { + t.Fatal("expected provider to be initialized") + } + + resp, err := al.Continue(context.Background(), "test-session", "test", "chat1") + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if resp != "" { + t.Fatalf("expected empty response for no steering messages, got %q", resp) + } +} + +func TestAgentLoop_Continue_WithMessages(t *testing.T) { + tmpDir, err := os.MkdirTemp("", "agent-test-*") + if err != nil { + t.Fatalf("Failed to create temp dir: %v", err) + } + defer os.RemoveAll(tmpDir) + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: tmpDir, + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + }, + }, + } + + msgBus := bus.NewMessageBus() + provider := &simpleMockProvider{response: "continued response"} + al := NewAgentLoop(cfg, msgBus, provider) + + al.Steer(providers.Message{Role: "user", Content: "new direction"}) + + resp, err := al.Continue(context.Background(), "test-session", "test", "chat1") + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if resp != "continued response" { + t.Fatalf("expected 'continued response', got %q", resp) + } +} + +func TestDrainBusToSteering_RequeuesDifferentScopeMessage(t *testing.T) { + tmpDir, err := os.MkdirTemp("", "agent-test-*") + if err != nil { + t.Fatalf("Failed to create temp dir: %v", err) + } + defer os.RemoveAll(tmpDir) + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: tmpDir, + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + }, + }, + Session: config.SessionConfig{ + DMScope: "per-peer", + }, + } + + msgBus := bus.NewMessageBus() + al := NewAgentLoop(cfg, msgBus, &mockProvider{}) + + activeMsg := bus.InboundMessage{ + Channel: "telegram", + SenderID: "user1", + ChatID: "chat1", + Content: "active turn", + Peer: bus.Peer{ + Kind: "direct", + ID: "user1", + }, + } + activeScope, activeAgentID, ok := al.resolveSteeringTarget(activeMsg) + if !ok { + t.Fatal("expected active message to resolve to a steering scope") + } + + otherMsg := bus.InboundMessage{ + Channel: "telegram", + SenderID: "user2", + ChatID: "chat2", + Content: "other session", + Peer: bus.Peer{ + Kind: "direct", + ID: "user2", + }, + } + otherScope, _, ok := al.resolveSteeringTarget(otherMsg) + if !ok { + t.Fatal("expected other message to resolve to a steering scope") + } + if otherScope == activeScope { + t.Fatalf("expected different steering scopes, got same scope %q", activeScope) + } + + if err := msgBus.PublishInbound(context.Background(), otherMsg); err != nil { + t.Fatalf("PublishInbound failed: %v", err) + } + + ctx, cancel := context.WithTimeout(context.Background(), time.Second) + defer cancel() + + done := make(chan struct{}) + go func() { + al.drainBusToSteering(ctx, activeScope, activeAgentID) + close(done) + }() + + select { + case <-done: + case <-time.After(2 * time.Second): + t.Fatal("timeout waiting for drainBusToSteering to stop") + } + + if msgs := al.dequeueSteeringMessagesForScope(activeScope); len(msgs) != 0 { + t.Fatalf("expected no steering messages for active scope, got %v", msgs) + } + + select { + case <-ctx.Done(): + t.Fatalf("timeout waiting for requeued message on outbound bus") + case requeued := <-msgBus.OutboundChan(): + if requeued.Channel != otherMsg.Channel || requeued.ChatID != otherMsg.ChatID || + requeued.Content != otherMsg.Content { + t.Fatalf("requeued message mismatch: got %+v want %+v", requeued, otherMsg) + } + } +} + +// slowTool simulates a tool that takes some time to execute. +type slowTool struct { + name string + duration time.Duration + execCh chan struct{} // closed when Execute starts +} + +func (t *slowTool) Name() string { return t.name } +func (t *slowTool) Description() string { return "slow tool for testing" } +func (t *slowTool) Parameters() map[string]any { + return map[string]any{ + "type": "object", + "properties": map[string]any{}, + } +} + +func (t *slowTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult { + if t.execCh != nil { + close(t.execCh) + } + time.Sleep(t.duration) + return tools.SilentResult(fmt.Sprintf("executed %s", t.name)) +} + +// toolCallProvider returns an LLM response with tool calls on the first call, +// then a direct response on subsequent calls. +type toolCallProvider struct { + mu sync.Mutex + calls int + toolCalls []providers.ToolCall + finalResp string +} + +func (m *toolCallProvider) Chat( + ctx context.Context, + messages []providers.Message, + tools []providers.ToolDefinition, + model string, + opts map[string]any, +) (*providers.LLMResponse, error) { + m.mu.Lock() + defer m.mu.Unlock() + m.calls++ + + if m.calls == 1 && len(m.toolCalls) > 0 { + return &providers.LLMResponse{ + Content: "", + ToolCalls: m.toolCalls, + }, nil + } + + return &providers.LLMResponse{ + Content: m.finalResp, + ToolCalls: []providers.ToolCall{}, + }, nil +} + +func (m *toolCallProvider) GetDefaultModel() string { + return "tool-call-mock" +} + +type gracefulCaptureProvider struct { + mu sync.Mutex + calls int + toolCalls []providers.ToolCall + finalResp string + terminalMessages []providers.Message + terminalToolsCount int +} + +func (p *gracefulCaptureProvider) Chat( + ctx context.Context, + messages []providers.Message, + tools []providers.ToolDefinition, + model string, + opts map[string]any, +) (*providers.LLMResponse, error) { + p.mu.Lock() + defer p.mu.Unlock() + p.calls++ + + if p.calls == 1 { + return &providers.LLMResponse{ + ToolCalls: p.toolCalls, + }, nil + } + + p.terminalMessages = append([]providers.Message(nil), messages...) + p.terminalToolsCount = len(tools) + return &providers.LLMResponse{ + Content: p.finalResp, + }, nil +} + +func (p *gracefulCaptureProvider) GetDefaultModel() string { + return "graceful-capture-mock" +} + +type lateSteeringProvider struct { + mu sync.Mutex + calls int + firstCallStarted chan struct{} + releaseFirstCall chan struct{} + firstStartOnce sync.Once + secondCallMessages []providers.Message +} + +func (p *lateSteeringProvider) Chat( + ctx context.Context, + messages []providers.Message, + tools []providers.ToolDefinition, + model string, + opts map[string]any, +) (*providers.LLMResponse, error) { + p.mu.Lock() + p.calls++ + call := p.calls + p.mu.Unlock() + + if call == 1 { + p.firstStartOnce.Do(func() { close(p.firstCallStarted) }) + <-p.releaseFirstCall + return &providers.LLMResponse{Content: "first response"}, nil + } + + p.mu.Lock() + p.secondCallMessages = append([]providers.Message(nil), messages...) + p.mu.Unlock() + return &providers.LLMResponse{Content: "continued response"}, nil +} + +func (p *lateSteeringProvider) GetDefaultModel() string { + return "late-steering-mock" +} + +type blockingDirectProvider struct { + mu sync.Mutex + calls int + firstStarted chan struct{} + releaseFirst chan struct{} + firstResp string + finalResp string +} + +func (p *blockingDirectProvider) Chat( + ctx context.Context, + messages []providers.Message, + tools []providers.ToolDefinition, + model string, + opts map[string]any, +) (*providers.LLMResponse, error) { + p.mu.Lock() + p.calls++ + call := p.calls + firstStarted := p.firstStarted + releaseFirst := p.releaseFirst + firstResp := p.firstResp + finalResp := p.finalResp + if call == 1 && p.firstStarted != nil { + close(p.firstStarted) + p.firstStarted = nil + } + p.mu.Unlock() + + if call == 1 { + select { + case <-releaseFirst: + case <-ctx.Done(): + return nil, ctx.Err() + } + return &providers.LLMResponse{Content: firstResp}, nil + } + + _ = firstStarted + return &providers.LLMResponse{Content: finalResp}, nil +} + +func (p *blockingDirectProvider) GetDefaultModel() string { + return "blocking-direct-mock" +} + +type interruptibleTool struct { + name string + started chan struct{} + once sync.Once +} + +func (t *interruptibleTool) Name() string { return t.name } +func (t *interruptibleTool) Description() string { return "interruptible tool for testing" } +func (t *interruptibleTool) Parameters() map[string]any { + return map[string]any{ + "type": "object", + "properties": map[string]any{}, + } +} + +func (t *interruptibleTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult { + if t.started != nil { + t.once.Do(func() { close(t.started) }) + } + <-ctx.Done() + return tools.ErrorResult(ctx.Err().Error()).WithError(ctx.Err()) +} + +func TestAgentLoop_Steering_SkipsRemainingTools(t *testing.T) { + tmpDir, err := os.MkdirTemp("", "agent-test-*") + if err != nil { + t.Fatalf("Failed to create temp dir: %v", err) + } + defer os.RemoveAll(tmpDir) + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: tmpDir, + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + }, + }, + } + + tool1ExecCh := make(chan struct{}) + tool1 := &slowTool{name: "tool_one", duration: 50 * time.Millisecond, execCh: tool1ExecCh} + tool2 := &slowTool{name: "tool_two", duration: 50 * time.Millisecond} + + provider := &toolCallProvider{ + toolCalls: []providers.ToolCall{ + { + ID: "call_1", + Type: "function", + Name: "tool_one", + Function: &providers.FunctionCall{ + Name: "tool_one", + Arguments: "{}", + }, + Arguments: map[string]any{}, + }, + { + ID: "call_2", + Type: "function", + Name: "tool_two", + Function: &providers.FunctionCall{ + Name: "tool_two", + Arguments: "{}", + }, + Arguments: map[string]any{}, + }, + }, + finalResp: "steered response", + } + + msgBus := bus.NewMessageBus() + al := NewAgentLoop(cfg, msgBus, provider) + al.RegisterTool(tool1) + al.RegisterTool(tool2) + + // Start processing in a goroutine + type result struct { + resp string + err error + } + resultCh := make(chan result, 1) + + go func() { + resp, err := al.ProcessDirectWithChannel( + context.Background(), + "do something", + "test-session", + "test", + "chat1", + ) + resultCh <- result{resp, err} + }() + + // Wait for tool_one to start executing, then enqueue a steering message + select { + case <-tool1ExecCh: + // tool_one has started executing + case <-time.After(2 * time.Second): + t.Fatal("timeout waiting for tool_one to start") + } + + al.Steer(providers.Message{Role: "user", Content: "change course"}) + + // Get the result + select { + case r := <-resultCh: + if r.err != nil { + t.Fatalf("unexpected error: %v", r.err) + } + if r.resp != "steered response" { + t.Fatalf("expected 'steered response', got %q", r.resp) + } + case <-time.After(5 * time.Second): + t.Fatal("timeout waiting for agent loop to complete") + } + + // The provider should have been called twice: + // 1. first call returned tool calls + // 2. second call (after steering) returned the final response + provider.mu.Lock() + calls := provider.calls + provider.mu.Unlock() + if calls != 2 { + t.Fatalf("expected 2 provider calls, got %d", calls) + } +} + +func TestAgentLoop_Steering_InitialPoll(t *testing.T) { + tmpDir, err := os.MkdirTemp("", "agent-test-*") + if err != nil { + t.Fatalf("Failed to create temp dir: %v", err) + } + defer os.RemoveAll(tmpDir) + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: tmpDir, + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + }, + }, + } + + // Provider that captures messages it receives + var capturedMessages []providers.Message + var capMu sync.Mutex + provider := &capturingMockProvider{ + response: "ack", + captureFn: func(msgs []providers.Message) { + capMu.Lock() + capturedMessages = make([]providers.Message, len(msgs)) + copy(capturedMessages, msgs) + capMu.Unlock() + }, + } + + msgBus := bus.NewMessageBus() + al := NewAgentLoop(cfg, msgBus, provider) + + // Enqueue a steering message before processing starts + al.Steer(providers.Message{Role: "user", Content: "pre-enqueued steering"}) + + // Process a normal message - the initial steering poll should inject the steering message + _, err = al.ProcessDirectWithChannel( + context.Background(), + "initial message", + "test-session", + "test", + "chat1", + ) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + // The steering message should have been injected into the conversation + capMu.Lock() + msgs := capturedMessages + capMu.Unlock() + + // Look for the steering message in the captured messages + found := false + for _, m := range msgs { + if m.Content == "pre-enqueued steering" { + found = true + break + } + } + if !found { + t.Fatal("expected steering message to be injected into conversation context") + } +} + +func TestAgentLoop_Run_AutoContinuesLateSteeringMessage(t *testing.T) { + tmpDir, err := os.MkdirTemp("", "agent-test-*") + if err != nil { + t.Fatalf("Failed to create temp dir: %v", err) + } + defer os.RemoveAll(tmpDir) + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: tmpDir, + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + }, + }, + } + + msgBus := bus.NewMessageBus() + provider := &lateSteeringProvider{ + firstCallStarted: make(chan struct{}), + releaseFirstCall: make(chan struct{}), + } + al := NewAgentLoop(cfg, msgBus, provider) + + runCtx, cancelRun := context.WithCancel(context.Background()) + defer cancelRun() + + runErrCh := make(chan error, 1) + go func() { + runErrCh <- al.Run(runCtx) + }() + + first := bus.InboundMessage{ + Channel: "test", + SenderID: "user1", + ChatID: "chat1", + Content: "first message", + Peer: bus.Peer{ + Kind: "direct", + ID: "user1", + }, + } + late := bus.InboundMessage{ + Channel: "test", + SenderID: "user1", + ChatID: "chat1", + Content: "late append", + Peer: bus.Peer{ + Kind: "direct", + ID: "user1", + }, + } + + pubCtx, pubCancel := context.WithTimeout(context.Background(), 2*time.Second) + defer pubCancel() + if err := msgBus.PublishInbound(pubCtx, first); err != nil { + t.Fatalf("publish first inbound: %v", err) + } + + select { + case <-provider.firstCallStarted: + case <-time.After(2 * time.Second): + t.Fatal("timeout waiting for first provider call to start") + } + + if err := msgBus.PublishInbound(pubCtx, late); err != nil { + t.Fatalf("publish late inbound: %v", err) + } + + close(provider.releaseFirstCall) + + subCtx, subCancel := context.WithTimeout(context.Background(), 5*time.Second) + defer subCancel() + + var out1 bus.OutboundMessage + select { + case out1 = <-msgBus.OutboundChan(): + case <-subCtx.Done(): + t.Fatal("expected outbound response") + } + if out1.Content != "continued response" { + t.Fatalf("expected continued response, got %q", out1.Content) + } + + noExtraCtx, cancelNoExtra := context.WithTimeout(context.Background(), 200*time.Millisecond) + defer cancelNoExtra() + select { + case out2 := <-msgBus.OutboundChan(): + t.Fatalf("expected stale direct response to be suppressed, got extra outbound %q", out2.Content) + case <-noExtraCtx.Done(): + } + + cancelRun() + select { + case err := <-runErrCh: + if err != nil { + t.Fatalf("Run returned error: %v", err) + } + case <-time.After(2 * time.Second): + t.Fatal("timeout waiting for Run to stop") + } + + provider.mu.Lock() + calls := provider.calls + secondMessages := append([]providers.Message(nil), provider.secondCallMessages...) + provider.mu.Unlock() + + if calls != 2 { + t.Fatalf("expected 2 provider calls, got %d", calls) + } + + foundLateMessage := false + for _, msg := range secondMessages { + if msg.Role == "user" && msg.Content == "late append" { + foundLateMessage = true + break + } + } + if !foundLateMessage { + t.Fatal("expected queued late message to be processed in an automatic follow-up turn") + } +} + +func TestAgentLoop_Steering_DirectResponseContinuesWithQueuedMessage(t *testing.T) { + tmpDir, err := os.MkdirTemp("", "agent-test-*") + if err != nil { + t.Fatalf("Failed to create temp dir: %v", err) + } + defer os.RemoveAll(tmpDir) + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: tmpDir, + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + }, + }, + } + + sessionKey := routing.BuildAgentMainSessionKey(routing.DefaultAgentID) + provider := &blockingDirectProvider{ + firstStarted: make(chan struct{}), + releaseFirst: make(chan struct{}), + firstResp: "stale direct response", + finalResp: "fresh response after steering", + } + + msgBus := bus.NewMessageBus() + al := NewAgentLoop(cfg, msgBus, provider) + + resultCh := make(chan struct { + resp string + err error + }, 1) + go func() { + resp, err := al.ProcessDirectWithChannel( + context.Background(), + "initial request", + sessionKey, + "test", + "chat1", + ) + resultCh <- struct { + resp string + err error + }{resp: resp, err: err} + }() + + select { + case <-provider.firstStarted: + case <-time.After(2 * time.Second): + t.Fatal("timeout waiting for first LLM call to start") + } + + if err := al.Steer(providers.Message{Role: "user", Content: "follow-up instruction"}); err != nil { + t.Fatalf("Steer failed: %v", err) + } + close(provider.releaseFirst) + + select { + case result := <-resultCh: + if result.err != nil { + t.Fatalf("unexpected error: %v", result.err) + } + if result.resp != "fresh response after steering" { + t.Fatalf("expected refreshed response, got %q", result.resp) + } + case <-time.After(5 * time.Second): + t.Fatal("timeout waiting for ProcessDirectWithChannel") + } + + provider.mu.Lock() + calls := provider.calls + provider.mu.Unlock() + if calls != 2 { + t.Fatalf("expected 2 provider calls, got %d", calls) + } + + if msgs := al.dequeueSteeringMessagesForScope(sessionKey); len(msgs) != 0 { + t.Fatalf("expected steering queue to be empty after continuation, got %v", msgs) + } +} + +func TestAgentLoop_Continue_PreservesSteeringMedia(t *testing.T) { + tmpDir, err := os.MkdirTemp("", "agent-test-*") + if err != nil { + t.Fatalf("Failed to create temp dir: %v", err) + } + defer os.RemoveAll(tmpDir) + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: tmpDir, + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + }, + }, + } + + store := media.NewFileMediaStore() + pngPath := filepath.Join(tmpDir, "steer.png") + pngHeader := []byte{ + 0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, + 0x00, 0x00, 0x00, 0x0D, + 0x49, 0x48, 0x44, 0x52, + 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x02, + 0x00, 0x00, 0x00, + 0x90, 0x77, 0x53, 0xDE, + } + if err = os.WriteFile(pngPath, pngHeader, 0o644); err != nil { + t.Fatalf("WriteFile failed: %v", err) + } + ref, err := store.Store(pngPath, media.MediaMeta{Filename: "steer.png", ContentType: "image/png"}, "test") + if err != nil { + t.Fatalf("Store failed: %v", err) + } + + var capturedMessages []providers.Message + var capMu sync.Mutex + provider := &capturingMockProvider{ + response: "ack", + captureFn: func(msgs []providers.Message) { + capMu.Lock() + defer capMu.Unlock() + capturedMessages = append([]providers.Message(nil), msgs...) + }, + } + + sessionKey := routing.BuildAgentMainSessionKey(routing.DefaultAgentID) + msgBus := bus.NewMessageBus() + al := NewAgentLoop(cfg, msgBus, provider) + al.SetMediaStore(store) + + if err = al.Steer(providers.Message{ + Role: "user", + Content: "describe this image", + Media: []string{ref}, + }); err != nil { + t.Fatalf("Steer failed: %v", err) + } + + resp, err := al.Continue(context.Background(), sessionKey, "test", "chat1") + if err != nil { + t.Fatalf("Continue failed: %v", err) + } + if resp != "ack" { + t.Fatalf("expected ack, got %q", resp) + } + + capMu.Lock() + msgs := append([]providers.Message(nil), capturedMessages...) + capMu.Unlock() + + foundResolvedMedia := false + for _, msg := range msgs { + if msg.Role != "user" || msg.Content != "describe this image" || len(msg.Media) != 1 { + continue + } + if strings.HasPrefix(msg.Media[0], "data:image/png;base64,") { + foundResolvedMedia = true + break + } + } + if !foundResolvedMedia { + t.Fatal("expected continue path to inject steering media into the provider request") + } + + defaultAgent := al.registry.GetDefaultAgent() + if defaultAgent == nil { + t.Fatal("expected default agent") + } + history := defaultAgent.Sessions.GetHistory(sessionKey) + foundOriginalRef := false + for _, msg := range history { + if msg.Role == "user" && len(msg.Media) == 1 && msg.Media[0] == ref { + foundOriginalRef = true + break + } + } + if !foundOriginalRef { + t.Fatal("expected original steering media ref to be preserved in session history") + } +} + +func TestAgentLoop_InterruptGraceful_UsesTerminalNoToolCall(t *testing.T) { + tmpDir, err := os.MkdirTemp("", "agent-test-*") + if err != nil { + t.Fatalf("Failed to create temp dir: %v", err) + } + defer os.RemoveAll(tmpDir) + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: tmpDir, + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + }, + }, + } + + tool1ExecCh := make(chan struct{}) + tool1 := &slowTool{name: "tool_one", duration: 50 * time.Millisecond, execCh: tool1ExecCh} + tool2 := &slowTool{name: "tool_two", duration: 50 * time.Millisecond} + + provider := &gracefulCaptureProvider{ + toolCalls: []providers.ToolCall{ + { + ID: "call_1", + Type: "function", + Name: "tool_one", + Function: &providers.FunctionCall{ + Name: "tool_one", + Arguments: "{}", + }, + Arguments: map[string]any{}, + }, + { + ID: "call_2", + Type: "function", + Name: "tool_two", + Function: &providers.FunctionCall{ + Name: "tool_two", + Arguments: "{}", + }, + Arguments: map[string]any{}, + }, + }, + finalResp: "graceful summary", + } + + msgBus := bus.NewMessageBus() + al := NewAgentLoop(cfg, msgBus, provider) + al.RegisterTool(tool1) + al.RegisterTool(tool2) + sessionKey := routing.BuildAgentMainSessionKey(routing.DefaultAgentID) + + sub := al.SubscribeEvents(32) + defer al.UnsubscribeEvents(sub.ID) + + type result struct { + resp string + err error + } + resultCh := make(chan result, 1) + go func() { + resp, err := al.ProcessDirectWithChannel( + context.Background(), + "do something", + sessionKey, + "test", + "chat1", + ) + resultCh <- result{resp: resp, err: err} + }() + + select { + case <-tool1ExecCh: + case <-time.After(2 * time.Second): + t.Fatal("timeout waiting for tool_one to start") + } + + active := al.GetActiveTurn() + if active == nil { + t.Fatal("expected active turn while tool is running") + } + if active.SessionKey != sessionKey { + t.Fatalf("expected active session %q, got %q", sessionKey, active.SessionKey) + } + if active.Channel != "test" || active.ChatID != "chat1" { + t.Fatalf("unexpected active turn target: %#v", active) + } + + if err := al.InterruptGraceful("wrap it up"); err != nil { + t.Fatalf("InterruptGraceful failed: %v", err) + } + + select { + case r := <-resultCh: + if r.err != nil { + t.Fatalf("unexpected error: %v", r.err) + } + if r.resp != "graceful summary" { + t.Fatalf("expected graceful summary, got %q", r.resp) + } + case <-time.After(5 * time.Second): + t.Fatal("timeout waiting for graceful interrupt result") + } + + if active := al.GetActiveTurn(); active != nil { + t.Fatalf("expected no active turn after completion, got %#v", active) + } + + provider.mu.Lock() + terminalMessages := append([]providers.Message(nil), provider.terminalMessages...) + terminalToolsCount := provider.terminalToolsCount + calls := provider.calls + provider.mu.Unlock() + + if calls != 2 { + t.Fatalf("expected 2 provider calls, got %d", calls) + } + if terminalToolsCount != 0 { + t.Fatalf("expected graceful terminal call to disable tools, got %d tool defs", terminalToolsCount) + } + + foundHint := false + foundSkipped := false + expectedHint := "Interrupt requested. Stop scheduling tools and provide a short final summary.\n\n" + + "Interrupt hint: wrap it up" + for _, msg := range terminalMessages { + if msg.Role == "user" && msg.Content == expectedHint { + foundHint = true + } + if msg.Role == "tool" && msg.ToolCallID == "call_2" && msg.Content == "Skipped due to graceful interrupt." { + foundSkipped = true + } + } + if !foundHint { + t.Fatal("expected graceful terminal call to include interrupt hint message") + } + if !foundSkipped { + t.Fatal("expected remaining tool to be marked as skipped after graceful interrupt") + } + + events := collectEventStream(sub.C) + interruptEvt, ok := findEvent(events, EventKindInterruptReceived) + if !ok { + t.Fatal("expected interrupt received event") + } + interruptPayload, ok := interruptEvt.Payload.(InterruptReceivedPayload) + if !ok { + t.Fatalf("expected InterruptReceivedPayload, got %T", interruptEvt.Payload) + } + if interruptPayload.Kind != InterruptKindGraceful { + t.Fatalf("expected graceful interrupt payload, got %q", interruptPayload.Kind) + } + + turnEndEvt, ok := findEvent(events, EventKindTurnEnd) + if !ok { + t.Fatal("expected turn end event") + } + turnEndPayload, ok := turnEndEvt.Payload.(TurnEndPayload) + if !ok { + t.Fatalf("expected TurnEndPayload, got %T", turnEndEvt.Payload) + } + if turnEndPayload.Status != TurnEndStatusCompleted { + t.Fatalf("expected completed turn after graceful interrupt, got %q", turnEndPayload.Status) + } +} + +func TestAgentLoop_InterruptHard_RestoresSession(t *testing.T) { + tmpDir, err := os.MkdirTemp("", "agent-test-*") + if err != nil { + t.Fatalf("Failed to create temp dir: %v", err) + } + defer os.RemoveAll(tmpDir) + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: tmpDir, + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + }, + }, + } + + msgBus := bus.NewMessageBus() + provider := &toolCallProvider{ + toolCalls: []providers.ToolCall{ + { + ID: "call_1", + Type: "function", + Name: "cancel_tool", + Function: &providers.FunctionCall{ + Name: "cancel_tool", + Arguments: "{}", + }, + Arguments: map[string]any{}, + }, + }, + finalResp: "should not happen", + } + + al := NewAgentLoop(cfg, msgBus, provider) + started := make(chan struct{}) + al.RegisterTool(&interruptibleTool{name: "cancel_tool", started: started}) + sessionKey := routing.BuildAgentMainSessionKey(routing.DefaultAgentID) + + defaultAgent := al.registry.GetDefaultAgent() + if defaultAgent == nil { + t.Fatal("expected default agent") + } + + originalHistory := []providers.Message{ + {Role: "user", Content: "before"}, + {Role: "assistant", Content: "after"}, + } + defaultAgent.Sessions.SetHistory(sessionKey, originalHistory) + + sub := al.SubscribeEvents(16) + defer al.UnsubscribeEvents(sub.ID) + + type result struct { + resp string + err error + } + resultCh := make(chan result, 1) + go func() { + resp, err := al.ProcessDirectWithChannel( + context.Background(), + "do work", + sessionKey, + "test", + "chat1", + ) + resultCh <- result{resp: resp, err: err} + }() + + select { + case <-started: + case <-time.After(2 * time.Second): + t.Fatal("timeout waiting for interruptible tool to start") + } + + if active := al.GetActiveTurn(); active == nil { + t.Fatal("expected active turn before hard abort") + } + + if err := al.InterruptHard(); err != nil { + t.Fatalf("InterruptHard failed: %v", err) + } + + select { + case r := <-resultCh: + if r.err != nil { + t.Fatalf("unexpected error: %v", r.err) + } + if r.resp != "" { + t.Fatalf("expected no final response after hard abort, got %q", r.resp) + } + case <-time.After(5 * time.Second): + t.Fatal("timeout waiting for hard abort result") + } + + if active := al.GetActiveTurn(); active != nil { + t.Fatalf("expected no active turn after hard abort, got %#v", active) + } + + finalHistory := defaultAgent.Sessions.GetHistory(sessionKey) + if !reflect.DeepEqual(finalHistory, originalHistory) { + t.Fatalf("expected history rollback after hard abort, got %#v", finalHistory) + } + + events := collectEventStream(sub.C) + interruptEvt, ok := findEvent(events, EventKindInterruptReceived) + if !ok { + t.Fatal("expected interrupt received event") + } + interruptPayload, ok := interruptEvt.Payload.(InterruptReceivedPayload) + if !ok { + t.Fatalf("expected InterruptReceivedPayload, got %T", interruptEvt.Payload) + } + if interruptPayload.Kind != InterruptKindHard { + t.Fatalf("expected hard interrupt payload, got %q", interruptPayload.Kind) + } + + turnEndEvt, ok := findEvent(events, EventKindTurnEnd) + if !ok { + t.Fatal("expected turn end event") + } + turnEndPayload, ok := turnEndEvt.Payload.(TurnEndPayload) + if !ok { + t.Fatalf("expected TurnEndPayload, got %T", turnEndEvt.Payload) + } + if turnEndPayload.Status != TurnEndStatusAborted { + t.Fatalf("expected aborted turn, got %q", turnEndPayload.Status) + } +} + +// capturingMockProvider captures messages sent to Chat for inspection. +type capturingMockProvider struct { + response string + calls int + captureFn func([]providers.Message) +} + +func (m *capturingMockProvider) Chat( + ctx context.Context, + messages []providers.Message, + tools []providers.ToolDefinition, + model string, + opts map[string]any, +) (*providers.LLMResponse, error) { + m.calls++ + if m.captureFn != nil { + m.captureFn(messages) + } + return &providers.LLMResponse{ + Content: m.response, + ToolCalls: []providers.ToolCall{}, + }, nil +} + +func (m *capturingMockProvider) GetDefaultModel() string { + return "capturing-mock" +} + +func TestAgentLoop_Steering_SkippedToolsHaveErrorResults(t *testing.T) { + tmpDir, err := os.MkdirTemp("", "agent-test-*") + if err != nil { + t.Fatalf("Failed to create temp dir: %v", err) + } + defer os.RemoveAll(tmpDir) + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: tmpDir, + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + }, + }, + } + + execCh := make(chan struct{}) + tool1 := &slowTool{name: "slow_tool", duration: 50 * time.Millisecond, execCh: execCh} + tool2 := &slowTool{name: "skipped_tool", duration: 50 * time.Millisecond} + + // Provider that captures messages on the second call (after tools) + var secondCallMessages []providers.Message + var capMu sync.Mutex + callCount := 0 + + provider := &toolCallProvider{ + toolCalls: []providers.ToolCall{ + { + ID: "call_1", + Type: "function", + Name: "slow_tool", + Function: &providers.FunctionCall{ + Name: "slow_tool", + Arguments: "{}", + }, + Arguments: map[string]any{}, + }, + { + ID: "call_2", + Type: "function", + Name: "skipped_tool", + Function: &providers.FunctionCall{ + Name: "skipped_tool", + Arguments: "{}", + }, + Arguments: map[string]any{}, + }, + }, + finalResp: "done", + } + + // Wrap provider to capture messages on second call + wrappedProvider := &wrappingProvider{ + inner: provider, + onChat: func(msgs []providers.Message) { + capMu.Lock() + callCount++ + if callCount >= 2 { + secondCallMessages = make([]providers.Message, len(msgs)) + copy(secondCallMessages, msgs) + } + capMu.Unlock() + }, + } + + msgBus := bus.NewMessageBus() + al := NewAgentLoop(cfg, msgBus, wrappedProvider) + al.RegisterTool(tool1) + al.RegisterTool(tool2) + + resultCh := make(chan string, 1) + go func() { + resp, _ := al.ProcessDirectWithChannel( + context.Background(), "go", "test-session", "test", "chat1", + ) + resultCh <- resp + }() + + <-execCh + al.Steer(providers.Message{Role: "user", Content: "interrupt!"}) + + select { + case <-resultCh: + case <-time.After(5 * time.Second): + t.Fatal("timeout") + } + + // Check that the skipped tool result message is in the conversation + capMu.Lock() + msgs := secondCallMessages + capMu.Unlock() + + foundSkipped := false + for _, m := range msgs { + if m.Role == "tool" && m.ToolCallID == "call_2" && m.Content == "Skipped due to queued user message." { + foundSkipped = true + break + } + } + if !foundSkipped { + // Log what we actually got + for i, m := range msgs { + t.Logf("msg[%d]: role=%s toolCallID=%s content=%s", i, m.Role, m.ToolCallID, truncate(m.Content, 80)) + } + t.Fatal("expected skipped tool result for call_2") + } +} + +func truncate(s string, n int) string { + if len(s) <= n { + return s + } + return s[:n] + "..." +} + +// wrappingProvider wraps another provider to hook into Chat calls. +type wrappingProvider struct { + inner providers.LLMProvider + onChat func([]providers.Message) +} + +func (w *wrappingProvider) Chat( + ctx context.Context, + messages []providers.Message, + tools []providers.ToolDefinition, + model string, + opts map[string]any, +) (*providers.LLMResponse, error) { + if w.onChat != nil { + w.onChat(messages) + } + return w.inner.Chat(ctx, messages, tools, model, opts) +} + +func (w *wrappingProvider) GetDefaultModel() string { + return w.inner.GetDefaultModel() +} + +// Ensure NormalizeToolCall handles our test tool calls. +func init() { + // This is a no-op init; we just need the tool call tests to work + // with the proper argument serialization. + _ = json.Marshal +} diff --git a/pkg/agent/subturn.go b/pkg/agent/subturn.go new file mode 100644 index 00000000..f5ba412a --- /dev/null +++ b/pkg/agent/subturn.go @@ -0,0 +1,671 @@ +package agent + +import ( + "context" + "errors" + "fmt" + "sync" + "sync/atomic" + "time" + + "github.com/sipeed/picoclaw/pkg/logger" + "github.com/sipeed/picoclaw/pkg/providers" + "github.com/sipeed/picoclaw/pkg/tools" +) + +// ====================== Config & Constants ====================== +const ( + // Default values for SubTurn configuration (used when config is not set or is zero) + defaultMaxSubTurnDepth = 3 + defaultMaxConcurrentSubTurns = 5 + defaultConcurrencyTimeout = 30 * time.Second + defaultSubTurnTimeout = 5 * time.Minute + // maxEphemeralHistorySize limits the number of messages stored in ephemeral sessions. + // This prevents memory accumulation in long-running sub-turns. + maxEphemeralHistorySize = 50 +) + +var ( + ErrDepthLimitExceeded = errors.New("sub-turn depth limit exceeded") + ErrInvalidSubTurnConfig = errors.New("invalid sub-turn config") + ErrConcurrencyTimeout = errors.New("timeout waiting for concurrency slot") +) + +// getSubTurnConfig returns the effective SubTurn configuration with defaults applied. +func (al *AgentLoop) getSubTurnConfig() subTurnRuntimeConfig { + cfg := al.cfg.Agents.Defaults.SubTurn + + maxDepth := cfg.MaxDepth + if maxDepth <= 0 { + maxDepth = defaultMaxSubTurnDepth + } + + maxConcurrent := cfg.MaxConcurrent + if maxConcurrent <= 0 { + maxConcurrent = defaultMaxConcurrentSubTurns + } + + concurrencyTimeout := time.Duration(cfg.ConcurrencyTimeoutSec) * time.Second + if concurrencyTimeout <= 0 { + concurrencyTimeout = defaultConcurrencyTimeout + } + + defaultTimeout := time.Duration(cfg.DefaultTimeoutMinutes) * time.Minute + if defaultTimeout <= 0 { + defaultTimeout = defaultSubTurnTimeout + } + + return subTurnRuntimeConfig{ + maxDepth: maxDepth, + maxConcurrent: maxConcurrent, + concurrencyTimeout: concurrencyTimeout, + defaultTimeout: defaultTimeout, + defaultTokenBudget: cfg.DefaultTokenBudget, + } +} + +// subTurnRuntimeConfig holds the effective runtime configuration for SubTurn execution. +type subTurnRuntimeConfig struct { + maxDepth int + maxConcurrent int + concurrencyTimeout time.Duration + defaultTimeout time.Duration + defaultTokenBudget int +} + +// ====================== SubTurn Config ====================== + +// SubTurnConfig configures the execution of a child sub-turn. +// +// Usage Examples: +// +// Synchronous sub-turn (Async=false): +// +// cfg := SubTurnConfig{ +// Model: "gpt-4o-mini", +// SystemPrompt: "Analyze this code", +// Async: false, // Result returned immediately +// } +// result, err := SpawnSubTurn(ctx, cfg) +// // Use result directly here +// processResult(result) +// +// Asynchronous sub-turn (Async=true): +// +// cfg := SubTurnConfig{ +// Model: "gpt-4o-mini", +// SystemPrompt: "Background analysis", +// Async: true, // Result delivered to channel +// } +// result, err := SpawnSubTurn(ctx, cfg) +// // Result also available in parent's pendingResults channel +// // Parent turn will poll and process it in a later iteration +type SubTurnConfig struct { + Model string + Tools []tools.Tool + SystemPrompt string + MaxTokens int + + // Async controls the result delivery mechanism: + // + // When Async = false (synchronous sub-turn): + // - The caller blocks until the sub-turn completes + // - The result is ONLY returned via the function return value + // - The result is NOT delivered to the parent's pendingResults channel + // - This prevents double delivery: caller gets result immediately, no need for channel + // - Use case: When the caller needs the result immediately to continue execution + // - Example: A tool that needs to process the sub-turn result before returning + // + // When Async = true (asynchronous sub-turn): + // - The sub-turn runs in the background (still blocks the caller, but semantically async) + // - The result is delivered to the parent's pendingResults channel + // - The result is ALSO returned via the function return value (for consistency) + // - The parent turn can poll pendingResults in later iterations to process results + // - Use case: Fire-and-forget operations, or when results are processed in batches + // - Example: Spawning multiple sub-turns in parallel and collecting results later + // + // IMPORTANT: The Async flag does NOT make the call non-blocking. It only controls + // whether the result is delivered via the channel. For true non-blocking execution, + // the caller must spawn the sub-turn in a separate goroutine. + Async bool + + // Critical indicates this SubTurn's result is important and should continue + // running even after the parent turn finishes gracefully. + // + // When parent finishes gracefully (Finish(false)): + // - Critical=true: SubTurn continues running, delivers result as orphan + // - Critical=false: SubTurn exits gracefully without error + // + // When parent finishes with hard abort (Finish(true)): + // - All SubTurns are canceled regardless of Critical flag + Critical bool + + // Timeout is the maximum duration for this SubTurn. + // If the SubTurn runs longer than this, it will be canceled. + // Default is 5 minutes (defaultSubTurnTimeout) if not specified. + Timeout time.Duration + + // MaxContextRunes limits the context size (in runes) passed to the SubTurn. + // This prevents context window overflow by truncating message history before LLM calls. + // + // Values: + // 0 = Auto-calculate based on model's ContextWindow * 0.75 (default, recommended) + // -1 = No limit (disable soft truncation, rely only on hard context errors) + // >0 = Use specified rune limit + // + // The soft limit acts as a first line of defense before hitting the provider's + // hard context window limit. When exceeded, older messages are intelligently + // truncated while preserving system messages and recent context. + MaxContextRunes int + + // ActualSystemPrompt is injected as the true 'system' role message for the childAgent. + // The legacy SystemPrompt field is actually used as the first 'user' message (task description). + ActualSystemPrompt string + + // InitialMessages preloads the ephemeral session history before the agent loop starts. + // Used by evaluator-optimizer patterns to pass the full worker context across multiple iterations. + InitialMessages []providers.Message + + // InitialTokenBudget is a shared atomic counter for tracking remaining tokens. + // If set, the SubTurn will inherit this budget and deduct tokens after each LLM call. + // If nil, the SubTurn will inherit the parent's tokenBudget (if any). + // Used by team tool to enforce token limits across all team members. + InitialTokenBudget *atomic.Int64 + + // Can be extended with temperature, topP, etc. +} + +// ====================== Context Keys ====================== +type agentLoopKeyType struct{} + +var agentLoopKey = agentLoopKeyType{} + +// WithAgentLoop injects AgentLoop into context for tool access +func WithAgentLoop(ctx context.Context, al *AgentLoop) context.Context { + return context.WithValue(ctx, agentLoopKey, al) +} + +// AgentLoopFromContext retrieves AgentLoop from context +func AgentLoopFromContext(ctx context.Context) *AgentLoop { + al, _ := ctx.Value(agentLoopKey).(*AgentLoop) + return al +} + +// ====================== Helper Functions ====================== + +func (al *AgentLoop) generateSubTurnID() string { + return fmt.Sprintf("subturn-%d", al.subTurnCounter.Add(1)) +} + +// ====================== Core Function: spawnSubTurn ====================== + +// AgentLoopSpawner implements tools.SubTurnSpawner interface. +// This allows tools to spawn sub-turns without circular dependency. +type AgentLoopSpawner struct { + al *AgentLoop +} + +// SpawnSubTurn implements tools.SubTurnSpawner interface. +func (s *AgentLoopSpawner) SpawnSubTurn( + ctx context.Context, + cfg tools.SubTurnConfig, +) (*tools.ToolResult, error) { + parentTS := turnStateFromContext(ctx) + if parentTS == nil { + return nil, errors.New( + "parent turnState not found in context - cannot spawn sub-turn outside of a turn", + ) + } + + // Convert tools.SubTurnConfig to agent.SubTurnConfig + agentCfg := SubTurnConfig{ + Model: cfg.Model, + Tools: cfg.Tools, + SystemPrompt: cfg.SystemPrompt, + ActualSystemPrompt: cfg.ActualSystemPrompt, + InitialMessages: cfg.InitialMessages, + InitialTokenBudget: cfg.InitialTokenBudget, + MaxTokens: cfg.MaxTokens, + Async: cfg.Async, + Critical: cfg.Critical, + Timeout: cfg.Timeout, + MaxContextRunes: cfg.MaxContextRunes, + } + + return spawnSubTurn(ctx, s.al, parentTS, agentCfg) +} + +// NewSubTurnSpawner creates a SubTurnSpawner for the given AgentLoop. +func NewSubTurnSpawner(al *AgentLoop) *AgentLoopSpawner { + return &AgentLoopSpawner{al: al} +} + +// SpawnSubTurn is the exported entry point for tools to spawn sub-turns. +// It retrieves AgentLoop and parent turnState from context and delegates to spawnSubTurn. +func SpawnSubTurn(ctx context.Context, cfg SubTurnConfig) (*tools.ToolResult, error) { + al := AgentLoopFromContext(ctx) + if al == nil { + return nil, errors.New( + "AgentLoop not found in context - ensure context is properly initialized", + ) + } + + parentTS := turnStateFromContext(ctx) + if parentTS == nil { + return nil, errors.New( + "parent turnState not found in context - cannot spawn sub-turn outside of a turn", + ) + } + + return spawnSubTurn(ctx, al, parentTS, cfg) +} + +func spawnSubTurn( + ctx context.Context, + al *AgentLoop, + parentTS *turnState, + cfg SubTurnConfig, +) (result *tools.ToolResult, err error) { + // Get effective SubTurn configuration + rtCfg := al.getSubTurnConfig() + + // 0. Acquire concurrency semaphore FIRST to ensure it's released even if early validation fails. + // Blocks if parent already has maxConcurrentSubTurns running, with a timeout to prevent indefinite blocking. + // Also respects context cancellation so we don't block forever if parent is aborted. + // NOTE: The semaphore is released immediately after runTurn completes (not in a defer) to + // ensure it is freed before the cleanup phase (async result delivery), which may block on + // a full pendingResults channel. Holding the semaphore through cleanup would allow the + // parent's goroutine to be blocked waiting for a semaphore slot while child turns are + // blocked delivering results — a deadlock. + var semAcquired bool + if parentTS.concurrencySem != nil { + // Create a timeout context for semaphore acquisition + timeoutCtx, cancel := context.WithTimeout(ctx, rtCfg.concurrencyTimeout) + defer cancel() + + select { + case parentTS.concurrencySem <- struct{}{}: + semAcquired = true + defer func() { + if semAcquired { + <-parentTS.concurrencySem + } + }() + case <-timeoutCtx.Done(): + // Check parent context first - if it was canceled, propagate that error + if ctx.Err() != nil { + return nil, ctx.Err() + } + // Otherwise it's our timeout + return nil, fmt.Errorf("%w: all %d slots occupied for %v", + ErrConcurrencyTimeout, rtCfg.maxConcurrent, rtCfg.concurrencyTimeout) + } + } + + // 1. Depth limit check + if parentTS.depth >= rtCfg.maxDepth { + logger.WarnCF("subturn", "Depth limit exceeded", map[string]any{ + "parent_id": parentTS.turnID, + "depth": parentTS.depth, + "max_depth": rtCfg.maxDepth, + }) + return nil, ErrDepthLimitExceeded + } + + // 2. Config validation + if cfg.Model == "" { + return nil, ErrInvalidSubTurnConfig + } + + // 3. Determine timeout for child SubTurn + timeout := cfg.Timeout + if timeout <= 0 { + timeout = rtCfg.defaultTimeout + } + + // 4. Create INDEPENDENT child context (not derived from parent ctx). + // This allows the child to continue running after parent finishes gracefully. + // The child has its own timeout for self-protection. + childCtx, cancel := context.WithTimeout(context.Background(), timeout) + defer cancel() + + childID := al.generateSubTurnID() + + // Get the agent instance from parent, falling back to the default agent. + // Wrap it in a shallow copy that uses an ephemeral (in-memory only) session store + // so that child turns never pollute or persist to the parent's session history. + baseAgent := parentTS.agent + if baseAgent == nil { + baseAgent = al.registry.GetDefaultAgent() + } + if baseAgent == nil { + return nil, errors.New("parent turnState has no agent instance") + } + ephemeralStore := newEphemeralSession(nil) + agent := *baseAgent // shallow copy + agent.Sessions = ephemeralStore + // Clone the tool registry so child turn's tool registrations + // don't pollute the parent's registry. + if baseAgent.Tools != nil { + agent.Tools = baseAgent.Tools.Clone() + } + + // Create processOptions for the child turn + opts := processOptions{ + SessionKey: childID, + Channel: parentTS.channel, + ChatID: parentTS.chatID, + SenderID: parentTS.opts.SenderID, + SenderDisplayName: parentTS.opts.SenderDisplayName, + UserMessage: cfg.SystemPrompt, // Task description becomes the first user message + SystemPromptOverride: cfg.ActualSystemPrompt, + Media: nil, + InitialSteeringMessages: cfg.InitialMessages, + DefaultResponse: "", + EnableSummary: false, + SendResponse: false, + NoHistory: true, // SubTurns don't use session history + SkipInitialSteeringPoll: true, + } + + // Create event scope for the child turn + scope := al.newTurnEventScope(agent.ID, childID) + + // Create child turnState using the new API + childTS := newTurnState(&agent, opts, scope) + + // Set SubTurn-specific fields + childTS.cancelFunc = cancel + childTS.critical = cfg.Critical + childTS.depth = parentTS.depth + 1 + childTS.parentTurnID = parentTS.turnID + childTS.parentTurnState = parentTS + childTS.pendingResults = make(chan *tools.ToolResult, 16) + childTS.concurrencySem = make(chan struct{}, rtCfg.maxConcurrent) + childTS.al = al // back-ref for hard abort cascade + childTS.session = ephemeralStore // same store as agent.Sessions + + // Token budget initialization/inheritance + // If InitialTokenBudget is explicitly provided (e.g., by team tool), use it. + // Otherwise, inherit from parent's tokenBudget (for nested SubTurns). + if cfg.InitialTokenBudget != nil { + childTS.tokenBudget = cfg.InitialTokenBudget + } else if parentTS.tokenBudget != nil { + childTS.tokenBudget = parentTS.tokenBudget + } else if rtCfg.defaultTokenBudget > 0 { + // Apply default token budget from config if no budget is set + budget := &atomic.Int64{} + budget.Store(int64(rtCfg.defaultTokenBudget)) + childTS.tokenBudget = budget + } + + // IMPORTANT: Put childTS into childCtx so that code inside runTurn can retrieve it + childCtx = withTurnState(childCtx, childTS) + childCtx = WithAgentLoop(childCtx, al) // Propagate AgentLoop to child turn + + childTS.ctx = childCtx + + // Register child turn state so GetAllActiveTurns/Subagents can find it + al.activeTurnStates.Store(childID, childTS) + defer al.activeTurnStates.Delete(childID) + + // 5. Establish parent-child relationship (thread-safe) + parentTS.mu.Lock() + parentTS.childTurnIDs = append(parentTS.childTurnIDs, childID) + parentTS.mu.Unlock() + + // 6. Emit Spawn event + al.emitEvent(EventKindSubTurnSpawn, + childTS.eventMeta("spawnSubTurn", "subturn.spawn"), + SubTurnSpawnPayload{ + AgentID: childTS.agentID, + Label: childID, + ParentTurnID: parentTS.turnID, + }, + ) + + // 7. Defer cleanup: deliver result (for async), emit End event, and recover from panics + defer func() { + if r := recover(); r != nil { + err = fmt.Errorf("subturn panicked: %v", r) + result = nil + logger.ErrorCF("subturn", "SubTurn panicked", map[string]any{ + "child_id": childID, + "parent_id": parentTS.turnID, + "panic": r, + }) + } + + // Result Delivery Strategy (Async vs Sync) + if cfg.Async { + deliverSubTurnResult(al, parentTS, childID, result) + } + + status := "completed" + if err != nil { + status = "error" + } + al.emitEvent(EventKindSubTurnEnd, + childTS.eventMeta("spawnSubTurn", "subturn.end"), + SubTurnEndPayload{ + AgentID: childTS.agentID, + Status: status, + }, + ) + }() + + // 8. Execute sub-turn via the real agent loop. + turnRes, turnErr := al.runTurn(childCtx, childTS) + + // Release the concurrency semaphore immediately after runTurn completes, + // before the cleanup defer runs. This prevents a deadlock where: + // - All semaphore slots are held by sub-turns in their cleanup phase + // - Cleanup blocks on a full pendingResults channel + // - The parent goroutine is blocked waiting for a semaphore slot + // - The parent cannot consume pendingResults because it is blocked on the semaphore + if semAcquired { + <-parentTS.concurrencySem + semAcquired = false // prevent the defer from double-releasing + } + + // Convert turnResult to tools.ToolResult + if turnErr != nil { + err = turnErr + result = &tools.ToolResult{ + Err: turnErr, + ForLLM: fmt.Sprintf("SubTurn failed: %v", turnErr), + } + } else { + result = &tools.ToolResult{ + ForLLM: turnRes.finalContent, + ForUser: turnRes.finalContent, + } + } + + return result, err +} + +// ====================== Result Delivery ====================== + +// deliverSubTurnResult delivers a sub-turn result to the parent turn's pendingResults channel. +// +// IMPORTANT: This function is ONLY called for asynchronous sub-turns (Async=true). +// For synchronous sub-turns (Async=false), results are returned directly via the function +// return value to avoid double delivery. +// +// Delivery behavior: +// - If parent turn is still running: attempts to deliver to pendingResults channel +// - If channel is full: emits SubTurnOrphanResultEvent (result is lost from channel but tracked) +// - If parent turn has finished: emits SubTurnOrphanResultEvent (late arrival) +// +// Thread safety: +// - Reads parent state under lock, then releases lock before channel send +// - Small race window exists but is acceptable (worst case: result becomes orphan) +// +// Event emissions: +// - SubTurnResultDeliveredEvent: successful delivery to channel +// - SubTurnOrphanResultEvent: delivery failed (parent finished or channel full) +func deliverSubTurnResult(al *AgentLoop, parentTS *turnState, childID string, result *tools.ToolResult) { + // Let GC clean up the pendingResults channel; parent Finish will no longer close it. + // We use defer/recover to catch any unlikely channel panics if it were ever closed. + defer func() { + if r := recover(); r != nil { + logger.WarnCF("subturn", "recovered panic sending to pendingResults", map[string]any{ + "parent_id": parentTS.turnID, + "child_id": childID, + "recover": r, + }) + if result != nil && al != nil { + al.emitEvent(EventKindSubTurnOrphan, + parentTS.eventMeta("deliverSubTurnResult", "subturn.orphan"), + SubTurnOrphanPayload{ParentTurnID: parentTS.turnID, ChildTurnID: childID, Reason: "panic"}, + ) + } + } + }() + parentTS.mu.Lock() + isFinished := parentTS.isFinished.Load() + resultChan := parentTS.pendingResults + parentTS.mu.Unlock() + + // If parent turn has already finished, treat this as an orphan result + if isFinished || resultChan == nil { + if result != nil && al != nil { + al.emitEvent(EventKindSubTurnOrphan, + parentTS.eventMeta("deliverSubTurnResult", "subturn.orphan"), + SubTurnOrphanPayload{ParentTurnID: parentTS.turnID, ChildTurnID: childID, Reason: "parent_finished"}, + ) + } + return + } + + // Parent Turn is still running → attempt to deliver result + // We use a select statement with parentTS.Finished() to ensure that if the + // parent turn finishes while we are waiting to send the result (e.g. channel + // is full), we don't leak this goroutine by blocking forever. + select { + case resultChan <- result: + // Successfully delivered + if al != nil { + al.emitEvent(EventKindSubTurnResultDelivered, + parentTS.eventMeta("deliverSubTurnResult", "subturn.result_delivered"), + SubTurnResultDeliveredPayload{ContentLen: len(result.ForLLM)}, + ) + } + case <-parentTS.Finished(): + // Parent finished while we were waiting to deliver. + // The result cannot be delivered to the LLM, so it becomes an orphan. + logger.WarnCF("subturn", "parent finished before result could be delivered", map[string]any{ + "parent_id": parentTS.turnID, + "child_id": childID, + }) + if result != nil && al != nil { + al.emitEvent( + EventKindSubTurnOrphan, + parentTS.eventMeta("deliverSubTurnResult", "subturn.orphan"), + SubTurnOrphanPayload{ + ParentTurnID: parentTS.turnID, + ChildTurnID: childID, + Reason: "parent_finished_waiting", + }, + ) + } + } +} + +// ====================== Other Types ====================== + +// ephemeralSessionStore is an in-memory session.SessionStore used by SubTurns. +// It does not persist to disk and auto-truncates history to maxEphemeralHistorySize. +type ephemeralSessionStore struct { + mu sync.Mutex + history []providers.Message + summary string +} + +func newEphemeralSession(initial []providers.Message) ephemeralSessionStoreIface { + s := &ephemeralSessionStore{} + if len(initial) > 0 { + s.history = append(s.history, initial...) + } + return s +} + +// ephemeralSessionStoreIface is satisfied by *ephemeralSessionStore. +// Declared so newEphemeralSession can return a typed interface. +type ephemeralSessionStoreIface interface { + AddMessage(sessionKey, role, content string) + AddFullMessage(sessionKey string, msg providers.Message) + GetHistory(key string) []providers.Message + GetSummary(key string) string + SetSummary(key, summary string) + SetHistory(key string, history []providers.Message) + TruncateHistory(key string, keepLast int) + Save(key string) error + Close() error +} + +func (e *ephemeralSessionStore) AddMessage(_, role, content string) { + e.mu.Lock() + defer e.mu.Unlock() + e.history = append(e.history, providers.Message{Role: role, Content: content}) + e.truncateLocked() +} + +func (e *ephemeralSessionStore) AddFullMessage(_ string, msg providers.Message) { + e.mu.Lock() + defer e.mu.Unlock() + e.history = append(e.history, msg) + e.truncateLocked() +} + +func (e *ephemeralSessionStore) GetHistory(_ string) []providers.Message { + e.mu.Lock() + defer e.mu.Unlock() + out := make([]providers.Message, len(e.history)) + copy(out, e.history) + return out +} + +func (e *ephemeralSessionStore) GetSummary(_ string) string { + e.mu.Lock() + defer e.mu.Unlock() + return e.summary +} + +func (e *ephemeralSessionStore) SetSummary(_, summary string) { + e.mu.Lock() + defer e.mu.Unlock() + e.summary = summary +} + +func (e *ephemeralSessionStore) SetHistory(_ string, history []providers.Message) { + e.mu.Lock() + defer e.mu.Unlock() + e.history = make([]providers.Message, len(history)) + copy(e.history, history) + e.truncateLocked() +} + +func (e *ephemeralSessionStore) TruncateHistory(_ string, keepLast int) { + e.mu.Lock() + defer e.mu.Unlock() + if keepLast <= 0 { + e.history = nil + return + } + + if keepLast >= len(e.history) { + return + } + e.history = e.history[len(e.history)-keepLast:] +} + +func (e *ephemeralSessionStore) Save(_ string) error { return nil } +func (e *ephemeralSessionStore) Close() error { return nil } + +func (e *ephemeralSessionStore) truncateLocked() { + if len(e.history) > maxEphemeralHistorySize { + e.history = e.history[len(e.history)-maxEphemeralHistorySize:] + } +} diff --git a/pkg/agent/subturn_test.go b/pkg/agent/subturn_test.go new file mode 100644 index 00000000..bac786eb --- /dev/null +++ b/pkg/agent/subturn_test.go @@ -0,0 +1,2067 @@ +package agent + +import ( + "context" + "errors" + "fmt" + "sync" + "testing" + "time" + + "github.com/sipeed/picoclaw/pkg/bus" + "github.com/sipeed/picoclaw/pkg/config" + "github.com/sipeed/picoclaw/pkg/providers" + "github.com/sipeed/picoclaw/pkg/tools" +) + +// Test constants (use defaults from subturn.go) +const ( + testMaxConcurrentSubTurns = defaultMaxConcurrentSubTurns +) + +// ====================== Test Helper: Event Collector ====================== +type eventCollector struct { + mu sync.Mutex + events []Event +} + +func newEventCollector(t *testing.T, al *AgentLoop) (*eventCollector, func()) { + t.Helper() + c := &eventCollector{} + sub := al.SubscribeEvents(16) + done := make(chan struct{}) + go func() { + defer close(done) + for evt := range sub.C { + c.mu.Lock() + c.events = append(c.events, evt) + c.mu.Unlock() + } + }() + cleanup := func() { + al.UnsubscribeEvents(sub.ID) + <-done + } + return c, cleanup +} + +func (c *eventCollector) hasEventOfKind(kind EventKind) bool { + c.mu.Lock() + defer c.mu.Unlock() + for _, e := range c.events { + if e.Kind == kind { + return true + } + } + return false +} + +// ====================== Main Test Function ====================== +func TestSpawnSubTurn(t *testing.T) { + tests := []struct { + name string + parentDepth int + config SubTurnConfig + wantErr error + wantSpawn bool + wantEnd bool + wantDepthFail bool + }{ + { + name: "Basic success path - Single layer sub-turn", + parentDepth: 0, + config: SubTurnConfig{ + Model: "gpt-4o-mini", + Tools: []tools.Tool{}, // At least one tool + }, + wantErr: nil, + wantSpawn: true, + wantEnd: true, + }, + { + name: "Nested 2 layers - Normal", + parentDepth: 1, + config: SubTurnConfig{ + Model: "gpt-4o-mini", + Tools: []tools.Tool{}, + }, + wantErr: nil, + wantSpawn: true, + wantEnd: true, + }, + { + name: "Depth limit triggered - 4th layer fails", + parentDepth: 3, + config: SubTurnConfig{ + Model: "gpt-4o-mini", + Tools: []tools.Tool{}, + }, + wantErr: ErrDepthLimitExceeded, + wantSpawn: false, + wantEnd: false, + wantDepthFail: true, + }, + { + name: "Invalid config - Empty Model", + parentDepth: 0, + config: SubTurnConfig{ + Model: "", + Tools: []tools.Tool{}, + }, + wantErr: ErrInvalidSubTurnConfig, + wantSpawn: false, + wantEnd: false, + }, + } + + al, _, _, provider, cleanup := newTestAgentLoop(t) + _ = provider + defer cleanup() + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + // Prepare parent Turn + parent := &turnState{ + ctx: context.Background(), + turnID: "parent-1", + depth: tt.parentDepth, + childTurnIDs: []string{}, + pendingResults: make(chan *tools.ToolResult, 10), + session: &ephemeralSessionStore{}, + agent: al.registry.GetDefaultAgent(), + } + + // Subscribe to real EventBus to capture events + collector, collectCleanup := newEventCollector(t, al) + defer collectCleanup() + + // Execute spawnSubTurn + result, err := spawnSubTurn(context.Background(), al, parent, tt.config) + + // Assert errors + if tt.wantErr != nil { + if err == nil || err != tt.wantErr { + t.Errorf("expected error %v, got %v", tt.wantErr, err) + } + return + } + if err != nil { + t.Errorf("unexpected error: %v", err) + return + } + + // Verify result + if result == nil { + t.Error("expected non-nil result") + } + + // Verify event emission + time.Sleep(10 * time.Millisecond) // let event goroutine flush + if tt.wantSpawn { + if !collector.hasEventOfKind(EventKindSubTurnSpawn) { + t.Error("SubTurnSpawnEvent not emitted") + } + } + if tt.wantEnd { + if !collector.hasEventOfKind(EventKindSubTurnEnd) { + t.Error("SubTurnEndEvent not emitted") + } + } + + // Verify turn tree + if len(parent.childTurnIDs) == 0 && !tt.wantDepthFail { + t.Error("child Turn not added to parent.childTurnIDs") + } + + // For synchronous calls (Async=false, the default), result is returned directly + // and should NOT be in pendingResults. The result was already verified above. + // Only async calls (Async=true) would place results in pendingResults. + }) + } +} + +// ====================== Extra Independent Test: Ephemeral Session Isolation ====================== +func TestSpawnSubTurn_EphemeralSessionIsolation(t *testing.T) { + al, _, _, provider, cleanup := newTestAgentLoop(t) + _ = provider + defer cleanup() + + // Parent uses its own ephemeral store pre-seeded with one message + parentSession := &ephemeralSessionStore{} + parentSession.AddMessage("", "user", "parent msg") + parent := &turnState{ + ctx: context.Background(), + turnID: "parent-1", + depth: 0, + pendingResults: make(chan *tools.ToolResult, 4), + concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns), + session: parentSession, + } + + cfg := SubTurnConfig{Model: "gpt-4o-mini", Tools: []tools.Tool{}} + + originalParentLen := len(parentSession.GetHistory("")) + + _, _ = spawnSubTurn(context.Background(), al, parent, cfg) + + // Parent session must be untouched — child used its own store + if got := len(parentSession.GetHistory("")); got != originalParentLen { + t.Errorf("parent session polluted: expected %d messages, got %d", originalParentLen, got) + } + + // The child's agent.Sessions must NOT be the same pointer as the parent's session. + // We verify this indirectly: spawnSubTurn stores childTS in activeTurnStates during + // execution (deleted on return), so we can't easily grab childTS after the call. + // Instead, confirm that the child session is a distinct ephemeralSessionStore by + // checking the parent session key is only used by the parent store. + // If isolation is correct, parent.session.GetHistory(childID) is always empty + // (the child never wrote to the parent store). + al.activeTurnStates.Range(func(k, v any) bool { + // No active turns should remain after spawnSubTurn returns + t.Errorf("unexpected active turn state left after spawnSubTurn: key=%v", k) + return true + }) +} + +// ====================== Extra Independent Test: Result Delivery Path (Async) ====================== +func TestSpawnSubTurn_ResultDelivery(t *testing.T) { + al, _, _, provider, cleanup := newTestAgentLoop(t) + _ = provider + defer cleanup() + + parent := &turnState{ + ctx: context.Background(), + turnID: "parent-1", + depth: 0, + pendingResults: make(chan *tools.ToolResult, 1), + session: &ephemeralSessionStore{}, + } + + // Set Async=true to test async result delivery via pendingResults channel + cfg := SubTurnConfig{Model: "gpt-4o-mini", Tools: []tools.Tool{}, Async: true} + + _, _ = spawnSubTurn(context.Background(), al, parent, cfg) + + // Check if pendingResults received the result (only for async calls) + select { + case res := <-parent.pendingResults: + if res == nil { + t.Error("received nil result in pendingResults") + } + default: + t.Error("result did not enter pendingResults for async call") + } +} + +// ====================== Extra Independent Test: Result Delivery Path (Sync) ====================== +func TestSpawnSubTurn_ResultDeliverySync(t *testing.T) { + al, _, _, provider, cleanup := newTestAgentLoop(t) + _ = provider + defer cleanup() + + parent := &turnState{ + ctx: context.Background(), + turnID: "parent-sync-1", + depth: 0, + pendingResults: make(chan *tools.ToolResult, 1), + session: &ephemeralSessionStore{}, + } + + // Sync call (Async=false, the default) - result should be returned directly + cfg := SubTurnConfig{Model: "gpt-4o-mini", Tools: []tools.Tool{}, Async: false} + + result, err := spawnSubTurn(context.Background(), al, parent, cfg) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + // Result should be returned directly + if result == nil { + t.Error("expected non-nil result from sync call") + } + + // pendingResults should NOT contain the result (no double delivery) + select { + case <-parent.pendingResults: + t.Error("sync call should not place result in pendingResults (double delivery)") + default: + // Expected - channel should be empty + } +} + +// ====================== Extra Independent Test: Orphan Result Routing ====================== +func TestSpawnSubTurn_OrphanResultRouting(t *testing.T) { + al, _, _, provider, cleanup := newTestAgentLoop(t) + _ = provider + defer cleanup() + + collector, collectCleanup := newEventCollector(t, al) + defer collectCleanup() + + parentCtx, cancelParent := context.WithCancel(context.Background()) + parent := &turnState{ + ctx: parentCtx, + cancelFunc: cancelParent, + turnID: "parent-1", + depth: 0, + pendingResults: make(chan *tools.ToolResult, 1), + session: &ephemeralSessionStore{}, + } + + // Simulate parent finishing before child delivers result + parent.Finish(false) + + // Call deliverSubTurnResult directly to simulate a delayed child + deliverSubTurnResult(al, parent, "delayed-child", &tools.ToolResult{ForLLM: "late result"}) + + time.Sleep(10 * time.Millisecond) // let event goroutine flush + // Verify Orphan event is emitted + if !collector.hasEventOfKind(EventKindSubTurnOrphan) { + t.Error("SubTurnOrphanResultEvent not emitted for finished parent") + } + + // Verify history is NOT polluted + if len(parent.session.GetHistory("")) != 0 { + t.Error("Parent history was polluted by orphan result") + } +} + +// ====================== Extra Independent Test: Result Channel Registration ====================== +func TestSubTurnResultChannelRegistration(t *testing.T) { + al, _, _, provider, cleanup := newTestAgentLoop(t) + _ = provider + defer cleanup() + + parent := &turnState{ + ctx: context.Background(), + turnID: "parent-reg-1", + depth: 0, + pendingResults: make(chan *tools.ToolResult, 4), + session: &ephemeralSessionStore{}, + } + + cfg := SubTurnConfig{Model: "gpt-4o-mini", Tools: []tools.Tool{}} + + // Before spawn: channel should not be registered + if results := al.dequeuePendingSubTurnResults(parent.turnID); results != nil { + t.Error("expected no channel before spawnSubTurn") + } + + _, _ = spawnSubTurn(context.Background(), al, parent, cfg) +} + +// ====================== Extra Independent Test: Dequeue Pending SubTurn Results ====================== +func TestDequeuePendingSubTurnResults(t *testing.T) { + al, _, _, provider, cleanup := newTestAgentLoop(t) + _ = provider + defer cleanup() + + sessionKey := "test-session-dequeue" + + // Empty (no turnState registered) returns nil + if results := al.dequeuePendingSubTurnResults(sessionKey); len(results) != 0 { + t.Errorf("expected empty results, got %d", len(results)) + } + + // Register a turnState so dequeuePendingSubTurnResults can find it + ts := &turnState{ + ctx: context.Background(), + turnID: sessionKey, + depth: 0, + session: &ephemeralSessionStore{}, + pendingResults: make(chan *tools.ToolResult, 4), + } + al.activeTurnStates.Store(sessionKey, ts) + defer al.activeTurnStates.Delete(sessionKey) + + // Put 3 results in + ts.pendingResults <- &tools.ToolResult{ForLLM: "result-1"} + ts.pendingResults <- &tools.ToolResult{ForLLM: "result-2"} + ts.pendingResults <- &tools.ToolResult{ForLLM: "result-3"} + + results := al.dequeuePendingSubTurnResults(sessionKey) + if len(results) != 3 { + t.Errorf("expected 3 results, got %d", len(results)) + } + if results[0].ForLLM != "result-1" || results[2].ForLLM != "result-3" { + t.Error("results order or content mismatch") + } + + // Channel should be drained now + if results := al.dequeuePendingSubTurnResults(sessionKey); len(results) != 0 { + t.Errorf("expected empty after drain, got %d", len(results)) + } + + // After removing from activeTurnStates, returns nil + al.activeTurnStates.Delete(sessionKey) + if results := al.dequeuePendingSubTurnResults(sessionKey); results != nil { + t.Error("expected nil for unregistered session") + } +} + +// ====================== Extra Independent Test: Concurrency Semaphore ====================== +func TestSubTurnConcurrencySemaphore(t *testing.T) { + al, _, _, provider, cleanup := newTestAgentLoop(t) + _ = provider + defer cleanup() + + parent := &turnState{ + ctx: context.Background(), + turnID: "parent-concurrency", + depth: 0, + pendingResults: make(chan *tools.ToolResult, 10), + session: &ephemeralSessionStore{}, + concurrencySem: make(chan struct{}, 2), // Only allow 2 concurrent children + } + + cfg := SubTurnConfig{Model: "gpt-4o-mini", Tools: []tools.Tool{}} + + // Spawn 2 children — should succeed immediately + done := make(chan bool, 3) + for i := 0; i < 2; i++ { + go func() { + _, _ = spawnSubTurn(context.Background(), al, parent, cfg) + done <- true + }() + } + + // Wait a bit to ensure the first 2 are running + // (In real scenario they'd be blocked in runTurn, but mockProvider returns immediately) + // So we just verify the semaphore doesn't block when under limit + <-done + <-done + + // Verify semaphore is now full (2/2 slots used, but they already released) + // Since mockProvider returns immediately, semaphore is already released + // So we can't easily test blocking without a real long-running operation + + // Instead, verify that semaphore exists and has correct capacity + if cap(parent.concurrencySem) != 2 { + t.Errorf("expected semaphore capacity 2, got %d", cap(parent.concurrencySem)) + } +} + +// ====================== Extra Independent Test: Hard Abort Cascading ====================== +func TestHardAbortCascading(t *testing.T) { + al, _, _, provider, cleanup := newTestAgentLoop(t) + _ = provider + defer cleanup() + + sessionKey := "test-session-abort" + + // Root turn with its own independent context (not derived from child) + rootCtx, rootCancel := context.WithCancel(context.Background()) + rootTS := &turnState{ + ctx: rootCtx, + cancelFunc: rootCancel, + turnID: sessionKey, + depth: 0, + session: &ephemeralSessionStore{}, + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, 5), + al: al, + } + al.activeTurnStates.Store(sessionKey, rootTS) + defer al.activeTurnStates.Delete(sessionKey) + + // Child turn with an INDEPENDENT context (simulates spawnSubTurn behavior: + // context.WithTimeout(context.Background(), ...) — NOT derived from parent). + // Cascade must therefore happen via childTurnIDs traversal, not Go context tree. + childCtx, childCancel := context.WithCancel(context.Background()) + childID := "child-independent" + childTS := &turnState{ + ctx: childCtx, + cancelFunc: childCancel, + turnID: childID, + pendingResults: make(chan *tools.ToolResult, 4), + al: al, + } + al.activeTurnStates.Store(childID, childTS) + defer al.activeTurnStates.Delete(childID) + + // Wire child into root's childTurnIDs (as spawnSubTurn would do) + rootTS.childTurnIDs = append(rootTS.childTurnIDs, childID) + + // Verify neither context is canceled yet + select { + case <-rootTS.ctx.Done(): + t.Fatal("root context should not be canceled yet") + default: + } + select { + case <-childTS.ctx.Done(): + t.Fatal("child context should not be canceled yet (independent context)") + default: + } + + // Trigger Hard Abort via al.HardAbort (goes through steering.go → Finish(true)) + err := al.HardAbort(sessionKey) + if err != nil { + t.Fatalf("HardAbort failed: %v", err) + } + + // Root context must be canceled + select { + case <-rootTS.ctx.Done(): + default: + t.Error("root context should be canceled after HardAbort") + } + + // Child context must be canceled via childTurnIDs cascade, NOT via Go context tree + select { + case <-childTS.ctx.Done(): + default: + t.Error("child context should be canceled via childTurnIDs cascade") + } + + // HardAbort on non-existent session should return an error + if err := al.HardAbort("non-existent-session"); err == nil { + t.Error("expected error for non-existent session") + } +} + +// TestHardAbortSessionRollback verifies that HardAbort rolls back session history +// to the state before the turn started, discarding all messages added during the turn. +func TestHardAbortSessionRollback(t *testing.T) { + al, _, _, provider, cleanup := newTestAgentLoop(t) + _ = provider + defer cleanup() + + // Create a session with initial history + sess := &ephemeralSessionStore{ + history: []providers.Message{ + {Role: "user", Content: "initial message 1"}, + {Role: "assistant", Content: "initial response 1"}, + }, + } + + // Create a root turnState with initialHistoryLength = 2 + rootTS := &turnState{ + ctx: context.Background(), + turnID: "test-session", + depth: 0, + session: sess, + initialHistoryLength: 2, // Snapshot: 2 messages + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, 5), + } + + // Register the turn state + al.activeTurnStates.Store("test-session", rootTS) + + // Simulate adding messages during the turn (e.g., user input + assistant response) + sess.AddMessage("", "user", "new user message") + sess.AddMessage("", "assistant", "new assistant response") + + // Verify history grew to 4 messages + if len(sess.GetHistory("")) != 4 { + t.Fatalf("expected 4 messages before abort, got %d", len(sess.GetHistory(""))) + } + + // Trigger HardAbort + err := al.HardAbort("test-session") + if err != nil { + t.Fatalf("HardAbort failed: %v", err) + } + + // Verify history rolled back to initial 2 messages + finalHistory := sess.GetHistory("") + if len(finalHistory) != 2 { + t.Errorf("expected history to rollback to 2 messages, got %d", len(finalHistory)) + } + + // Verify the content matches the initial state + if finalHistory[0].Content != "initial message 1" || finalHistory[1].Content != "initial response 1" { + t.Error("history content does not match initial state after rollback") + } +} + +// TestNestedSubTurnHierarchy verifies that nested SubTurns maintain correct +// parent-child relationships and depth tracking when recursively calling runAgentLoop. +func TestNestedSubTurnHierarchy(t *testing.T) { + al, _, _, provider, cleanup := newTestAgentLoop(t) + _ = provider + defer cleanup() + + // Track spawned turns and their depths + type turnInfo struct { + parentID string + childID string + } + var spawnedTurns []turnInfo + var mu sync.Mutex + + // Subscribe to real EventBus to capture spawn events + sub := al.SubscribeEvents(16) + defer al.UnsubscribeEvents(sub.ID) + go func() { + for evt := range sub.C { + if evt.Kind == EventKindSubTurnSpawn { + p, _ := evt.Payload.(SubTurnSpawnPayload) + mu.Lock() + spawnedTurns = append(spawnedTurns, turnInfo{ + parentID: p.ParentTurnID, + childID: p.Label, + }) + mu.Unlock() + } + } + }() + + // Create a root turn + rootSession := &ephemeralSessionStore{} + rootTS := &turnState{ + ctx: context.Background(), + turnID: "root-turn", + depth: 0, + session: rootSession, + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, 5), + } + + // Spawn a child (depth 1) + childCfg := SubTurnConfig{Model: "gpt-4o-mini"} + _, err := spawnSubTurn(context.Background(), al, rootTS, childCfg) + if err != nil { + t.Fatalf("failed to spawn child: %v", err) + } + + time.Sleep(10 * time.Millisecond) // let event goroutine flush + + // Verify we captured the spawn event + mu.Lock() + if len(spawnedTurns) != 1 { + t.Fatalf("expected 1 spawn event, got %d", len(spawnedTurns)) + } + if spawnedTurns[0].parentID != "root-turn" { + t.Errorf("expected parent ID 'root-turn', got %s", spawnedTurns[0].parentID) + } + mu.Unlock() + + // Verify root turn has the child in its childTurnIDs + rootTS.mu.Lock() + if len(rootTS.childTurnIDs) != 1 { + t.Errorf("expected root to have 1 child, got %d", len(rootTS.childTurnIDs)) + } + rootTS.mu.Unlock() +} + +// TestDeliverSubTurnResultNoDeadlock verifies that deliverSubTurnResult doesn't +// deadlock when multiple goroutines are accessing the parent turnState concurrently. +func TestDeliverSubTurnResultNoDeadlock(t *testing.T) { + parent := &turnState{ + ctx: context.Background(), + turnID: "parent-deadlock-test", + depth: 0, + pendingResults: make(chan *tools.ToolResult, 2), // Small buffer to test blocking + } + + // Simulate multiple child turns delivering results concurrently + var wg sync.WaitGroup + numChildren := 10 + + for i := 0; i < numChildren; i++ { + wg.Add(1) + go func(id int) { + defer wg.Done() + result := &tools.ToolResult{ForLLM: fmt.Sprintf("result-%d", id)} + deliverSubTurnResult(nil, parent, fmt.Sprintf("child-%d", id), result) + }(i) + } + + // Concurrently read from the channel to prevent blocking + // and to actually retrieve the matched number of results + go func() { + for i := 0; i < numChildren; i++ { + select { + case <-parent.pendingResults: + case <-time.After(5 * time.Second): + t.Error("timeout waiting for result") + return + } + } + }() + + // Wait for all deliveries to complete (with timeout) + done := make(chan struct{}) + go func() { + wg.Wait() + close(done) + }() + + select { + case <-done: + // Success - no deadlock + case <-time.After(3 * time.Second): + t.Fatal("deadlock detected: deliverSubTurnResult blocked") + } +} + +// TestHardAbortOrderOfOperations verifies that HardAbort calls Finish() before +// rolling back session history, minimizing the race window where new messages +// could be added after rollback. +func TestHardAbortOrderOfOperations(t *testing.T) { + al, _, _, provider, cleanup := newTestAgentLoop(t) + _ = provider + defer cleanup() + + sess := &ephemeralSessionStore{ + history: []providers.Message{ + {Role: "user", Content: "initial message"}, + {Role: "assistant", Content: "response 1"}, + {Role: "user", Content: "follow-up"}, + }, + } + + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + + rootTS := &turnState{ + ctx: ctx, + cancelFunc: cancel, + turnID: "test-session-order", + depth: 0, + session: sess, + initialHistoryLength: 1, // Snapshot: 1 message + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, 5), + } + + al.activeTurnStates.Store("test-session-order", rootTS) + + // Trigger HardAbort + err := al.HardAbort("test-session-order") + if err != nil { + t.Fatalf("HardAbort failed: %v", err) + } + + // Verify context was canceled (Finish() was called) + select { + case <-rootTS.ctx.Done(): + // Good - context was canceled + default: + t.Error("expected context to be canceled after HardAbort") + } + + // Verify history was rolled back + finalHistory := sess.GetHistory("") + if len(finalHistory) != 1 { + t.Errorf("expected history to rollback to 1 message, got %d", len(finalHistory)) + } + + if finalHistory[0].Content != "initial message" { + t.Error("history content does not match initial state after rollback") + } +} + +// TestFinishedChannelClosedState verifies that Finish() closes the Finished() channel +// so that child turns can safely abort waiting. +func TestFinishedChannelClosedState(t *testing.T) { + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + + ts := &turnState{ + ctx: ctx, + cancelFunc: cancel, + turnID: "test-finished-channel", + depth: 0, + pendingResults: make(chan *tools.ToolResult, 2), + } + + // Verify Finished channel is blocking initially + select { + case <-ts.Finished(): + t.Fatal("finished channel should block initially") + default: + // Good + } + + // Call Finish() with graceful finish + ts.Finish(false) + + // Verify Finished channel is closed + select { + case _, ok := <-ts.Finished(): + if ok { + t.Error("expected Finished() channel to be closed after Finish()") + } + default: + t.Fatal("expected <-ts.Finished() to not block") + } + + // Verify Finish() is idempotent + ts.Finish(false) // Should not panic + + // Verify deliverSubTurnResult correctly uses Finished() channel and treats as orphan + result := &tools.ToolResult{ForLLM: "late result"} + deliverSubTurnResult(nil, ts, "child-1", result) // Will emit orphan due to <-ts.Finished() case +} + +// TestFinalPollCapturesLateResults verifies that the final poll before Finish() +// captures results that arrive after the last iteration poll. +func TestFinalPollCapturesLateResults(t *testing.T) { + al, _, _, provider, cleanup := newTestAgentLoop(t) + _ = provider + defer cleanup() + + sessionKey := "test-session-final-poll" + + // Register a turnState + ts := &turnState{ + ctx: context.Background(), + turnID: sessionKey, + depth: 0, + session: &ephemeralSessionStore{}, + pendingResults: make(chan *tools.ToolResult, 4), + } + al.activeTurnStates.Store(sessionKey, ts) + defer al.activeTurnStates.Delete(sessionKey) + + // Simulate results arriving after last iteration poll + ts.pendingResults <- &tools.ToolResult{ForLLM: "result 1"} + ts.pendingResults <- &tools.ToolResult{ForLLM: "result 2"} + + // Dequeue should capture both results + results := al.dequeuePendingSubTurnResults(sessionKey) + + if len(results) != 2 { + t.Errorf("expected 2 results, got %d", len(results)) + } + + // Verify channel is now empty + results = al.dequeuePendingSubTurnResults(sessionKey) + if len(results) != 0 { + t.Errorf("expected 0 results on second poll, got %d", len(results)) + } +} + +// TestSpawnSubTurn_PanicRecovery verifies that even if runTurn panics, +// the result is still delivered for async calls and SubTurnEndEvent is emitted. +func TestSpawnSubTurn_PanicRecovery(t *testing.T) { + // Create a panic provider + panicProvider := &panicMockProvider{} + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Workspace: t.TempDir(), + Model: "test-model", + MaxTokens: 4096, + MaxToolIterations: 10, + }, + }, + } + al := NewAgentLoop(cfg, bus.NewMessageBus(), panicProvider) + + parent := &turnState{ + ctx: context.Background(), + turnID: "parent-panic", + depth: 0, + pendingResults: make(chan *tools.ToolResult, 1), + session: &ephemeralSessionStore{}, + } + + collector, collectCleanup := newEventCollector(t, al) + defer collectCleanup() + + // Test async call - result should still be delivered via channel + asyncCfg := SubTurnConfig{Model: "gpt-4o-mini", Tools: []tools.Tool{}, Async: true} + result, err := spawnSubTurn(context.Background(), al, parent, asyncCfg) + + // Should return error from panic recovery + if err == nil { + t.Error("expected error from panic recovery") + } + + // Result should be nil because panic occurred before runTurn could return + if result != nil { + t.Error("expected nil result after panic") + } + + time.Sleep(10 * time.Millisecond) // let event goroutine flush + // SubTurnEndEvent should still be emitted + if !collector.hasEventOfKind(EventKindSubTurnEnd) { + t.Error("SubTurnEndEvent not emitted after panic") + } + + // For async call, result should still be delivered to channel (even if nil) + select { + case res := <-parent.pendingResults: + // Result was delivered (nil due to panic) + _ = res + default: + t.Error("async result should be delivered to channel even after panic") + } +} + +// panicMockProvider is a mock provider that always panics +type panicMockProvider struct{} + +func (m *panicMockProvider) Chat( + ctx context.Context, + messages []providers.Message, + tools []providers.ToolDefinition, + model string, + opts map[string]any, +) (*providers.LLMResponse, error) { + panic("intentional panic for testing") +} + +func (m *panicMockProvider) GetDefaultModel() string { + return "panic-model" +} + +// ====================== Public API Tests ====================== + +// simpleMockProviderAPI for testing public APIs +type simpleMockProviderAPI struct { + response string +} + +func (m *simpleMockProviderAPI) Chat( + ctx context.Context, + messages []providers.Message, + toolDefs []providers.ToolDefinition, + model string, + options map[string]any, +) (*providers.LLMResponse, error) { + return &providers.LLMResponse{ + Content: m.response, + }, nil +} + +func (m *simpleMockProviderAPI) GetDefaultModel() string { + return "gpt-4o-mini" +} + +// TestGetActiveTurn verifies that GetActiveTurn returns correct turn information +func TestGetActiveTurn(t *testing.T) { + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Model: "gpt-4o-mini", + Provider: "mock", + }, + }, + } + al := NewAgentLoop(cfg, nil, &simpleMockProviderAPI{response: "ok"}) + + // Create a root turn state + rootCtx := context.Background() + rootTS := &turnState{ + ctx: rootCtx, + turnID: "root-turn", + parentTurnID: "", + depth: 0, + childTurnIDs: []string{}, + session: newEphemeralSession(nil), + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns), + } + + sessionKey := "test-session" + al.activeTurnStates.Store(sessionKey, rootTS) + defer al.activeTurnStates.Delete(sessionKey) + + // Test: GetActiveTurn should return turn info + info := al.GetActiveTurnBySession(sessionKey) + if info == nil { + t.Fatal("GetActiveTurn returned nil for active session") + } + + if info.TurnID != "root-turn" { + t.Errorf("Expected TurnID 'root-turn', got %q", info.TurnID) + } + + if info.Depth != 0 { + t.Errorf("Expected Depth 0, got %d", info.Depth) + } + + if info.ParentTurnID != "" { + t.Errorf("Expected empty ParentTurnID, got %q", info.ParentTurnID) + } + + if len(info.ChildTurnIDs) != 0 { + t.Errorf("Expected 0 child turns, got %d", len(info.ChildTurnIDs)) + } + + // Test: GetActiveTurn should return nil for non-existent session + nonExistentInfo := al.GetActiveTurnBySession("non-existent-session") + if nonExistentInfo != nil { + t.Error("GetActiveTurn should return nil for non-existent session") + } +} + +// TestGetActiveTurn_WithChildren verifies that child turn IDs are correctly reported +func TestGetActiveTurn_WithChildren(t *testing.T) { + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Model: "gpt-4o-mini", + Provider: "mock", + }, + }, + } + al := NewAgentLoop(cfg, nil, &simpleMockProviderAPI{response: "ok"}) + + rootCtx := context.Background() + rootTS := &turnState{ + ctx: rootCtx, + turnID: "root-turn", + parentTurnID: "", + depth: 0, + childTurnIDs: []string{"child-1", "child-2"}, + session: newEphemeralSession(nil), + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns), + } + + sessionKey := "test-session-with-children" + al.activeTurnStates.Store(sessionKey, rootTS) + defer al.activeTurnStates.Delete(sessionKey) + + info := al.GetActiveTurnBySession(sessionKey) + if info == nil { + t.Fatal("GetActiveTurn returned nil") + } + + if len(info.ChildTurnIDs) != 2 { + t.Fatalf("Expected 2 child turns, got %d", len(info.ChildTurnIDs)) + } + + if info.ChildTurnIDs[0] != "child-1" || info.ChildTurnIDs[1] != "child-2" { + t.Errorf("Child turn IDs mismatch: got %v", info.ChildTurnIDs) + } +} + +// TestTurnStateInfo_ThreadSafety verifies that Info() is thread-safe +func TestTurnStateInfo_ThreadSafety(t *testing.T) { + rootCtx := context.Background() + ts := &turnState{ + ctx: rootCtx, + turnID: "test-turn", + parentTurnID: "parent", + depth: 1, + childTurnIDs: []string{}, + session: newEphemeralSession(nil), + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns), + } + + // Concurrently read Info() and modify childTurnIDs + done := make(chan bool) + go func() { + for i := 0; i < 100; i++ { + ts.mu.Lock() + ts.childTurnIDs = append(ts.childTurnIDs, "child") + ts.mu.Unlock() + } + done <- true + }() + + go func() { + for i := 0; i < 100; i++ { + info := ts.snapshot() + if info.TurnID == "" { + t.Error("snapshot() returned empty TurnID") + } + } + done <- true + }() + + <-done + <-done +} + +// TestInjectFollowUp verifies that InjectFollowUp enqueues messages +func TestInjectFollowUp(t *testing.T) { + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Model: "gpt-4o-mini", + Provider: "mock", + }, + }, + } + + al := NewAgentLoop(cfg, nil, &simpleMockProviderAPI{response: "ok"}) + + msg := providers.Message{ + Role: "user", + Content: "Follow-up task", + } + + err := al.InjectFollowUp(msg) + if err != nil { + t.Fatalf("InjectFollowUp failed: %v", err) + } + + // Verify message was enqueued + if al.steering.len() != 1 { + t.Errorf("Expected 1 message in queue, got %d", al.steering.len()) + } +} + +// TestAPIAliases verifies that API aliases work correctly +func TestAPIAliases(t *testing.T) { + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Model: "gpt-4o-mini", + Provider: "mock", + }, + }, + } + + al := NewAgentLoop(cfg, nil, &simpleMockProviderAPI{response: "ok"}) + + msg := providers.Message{ + Role: "user", + Content: "Test message", + } + + // Test InterruptGraceful: requires active turn, so error is expected here + _ = al.InterruptGraceful(msg.Content) + + // Test InjectSteering (enqueues a steering message) + err := al.InjectSteering(msg) + if err != nil { + t.Errorf("InjectSteering failed: %v", err) + } + + // Also enqueue via Steer to verify second message + err = al.Steer(msg) + if err != nil { + t.Errorf("Steer failed: %v", err) + } + + // Verify both messages were enqueued + if al.steering.len() != 2 { + t.Errorf("Expected 2 messages in queue, got %d", al.steering.len()) + } +} + +// TestInterruptHard_Alias verifies that InterruptHard is an alias for HardAbort +func TestInterruptHard_Alias(t *testing.T) { + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Model: "gpt-4o-mini", + Provider: "mock", + }, + }, + } + al := NewAgentLoop(cfg, nil, &simpleMockProviderAPI{response: "ok"}) + + rootCtx := context.Background() + rootTS := &turnState{ + ctx: rootCtx, + turnID: "test-turn", + depth: 0, + session: newEphemeralSession(nil), + initialHistoryLength: 0, + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns), + } + + sessionKey := "test-session-interrupt" + al.activeTurnStates.Store(sessionKey, rootTS) + + // Test InterruptHard (alias for HardAbort) + err := al.InterruptHard() + if err != nil { + t.Errorf("InterruptHard failed: %v", err) + } + + // Verify turn was finished (removed from activeTurnStates) + info := al.GetActiveTurnBySession(sessionKey) + _ = info // turn may still be in map briefly; hard abort sets isFinished on the state +} + +// TestFinish_ConcurrentCalls verifies that calling Finish() concurrently from multiple +// goroutines is safe and doesn't cause panics or double-close errors. +func TestFinish_ConcurrentCalls(t *testing.T) { + ctx := context.Background() + parentTS := &turnState{ + ctx: ctx, + turnID: "parent-concurrent-finish", + depth: 0, + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns), + } + parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx) + + // Launch multiple goroutines that all call Finish() concurrently + const numGoroutines = 10 + var wg sync.WaitGroup + wg.Add(numGoroutines) + + for i := 0; i < numGoroutines; i++ { + go func() { + defer wg.Done() + // This should not panic, even when called concurrently + parentTS.Finish(false) + }() + } + + wg.Wait() + + // Verify the Finished() channel is closed + select { + case _, ok := <-parentTS.Finished(): + if ok { + t.Error("Expected Finished() channel to be closed") + } + default: + t.Error("Expected Finished() channel to be closed and readable without blocking") + } + + // Verify isFinished is set + parentTS.mu.Lock() + if !parentTS.isFinished.Load() { + t.Error("Expected isFinished to be true") + } + parentTS.mu.Unlock() +} + +// TestDeliverSubTurnResult_RaceWithFinish verifies that deliverSubTurnResult handles +// the race condition where Finish() is called while results are being delivered. +func TestDeliverSubTurnResult_RaceWithFinish(t *testing.T) { + al, _, _, _, cleanup := newTestAgentLoop(t) //nolint:dogsled + defer cleanup() + + // Collect events via real EventBus + var mu sync.Mutex + var deliveredCount, orphanCount int + sub := al.SubscribeEvents(64) + defer al.UnsubscribeEvents(sub.ID) + go func() { + for evt := range sub.C { + mu.Lock() + switch evt.Kind { + case EventKindSubTurnResultDelivered: + deliveredCount++ + case EventKindSubTurnOrphan: + orphanCount++ + } + mu.Unlock() + } + }() + + ctx := context.Background() + parentTS := &turnState{ + ctx: ctx, + turnID: "parent-race-test", + depth: 0, + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns), + } + parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx) + + // Launch goroutines that deliver results while another goroutine calls Finish() + const numResults = 20 + var wg sync.WaitGroup + wg.Add(numResults + 1) + + // Goroutine that calls Finish() after a short delay + go func() { + defer wg.Done() + time.Sleep(5 * time.Millisecond) + parentTS.Finish(false) + }() + + // Goroutines that deliver results + for i := 0; i < numResults; i++ { + go func(id int) { + defer wg.Done() + result := &tools.ToolResult{ + ForLLM: fmt.Sprintf("result-%d", id), + } + // This should not panic, even if Finish() is called concurrently + deliverSubTurnResult(al, parentTS, fmt.Sprintf("child-%d", id), result) + }(i) + } + + wg.Wait() + time.Sleep(20 * time.Millisecond) // let event goroutine flush + + // Get final counts + mu.Lock() + finalDelivered := deliveredCount + finalOrphan := orphanCount + mu.Unlock() + + t.Logf("Delivered: %d, Orphan: %d, Total: %d", finalDelivered, finalOrphan, finalDelivered+finalOrphan) + + // With the new drainPendingResults behavior, the total events may be >= numResults + // because Finish() drains remaining results from the channel and emits them as orphans. + // So we expect: + // - Some results were delivered successfully (before Finish()) + // - Some results became orphans (after Finish() or channel full) + // - Some results were in the channel when Finish() was called and got drained as orphans + // The total should be at least numResults (could be more due to drain) + if finalDelivered+finalOrphan < numResults { + t.Errorf("Expected at least %d total events, got %d delivered + %d orphan = %d", + numResults, finalDelivered, finalOrphan, finalDelivered+finalOrphan) + } + + // Should have at least some orphan results (those that arrived after Finish() or were drained) + if finalOrphan == 0 { + t.Error("Expected at least some orphan results after Finish()") + } +} + +// TestConcurrencySemaphore_Timeout verifies that spawning sub-turns times out +// when all concurrency slots are occupied for too long. +// Note: This test uses a shorter timeout by temporarily modifying the constant. +func TestConcurrencySemaphore_Timeout(t *testing.T) { + // This test would take 30 seconds with the default timeout. + // Instead, we'll test the mechanism by verifying the timeout context is created correctly. + // A full integration test with actual timeout would be too slow for unit tests. + + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Provider: "mock", + }, + }, + } + msgBus := bus.NewMessageBus() + provider := &simpleMockProviderAPI{} + al := NewAgentLoop(cfg, msgBus, provider) + + ctx := context.Background() + parentTS := &turnState{ + ctx: ctx, + turnID: "parent-timeout-test", + depth: 0, + session: newEphemeralSession(nil), + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns), + } + parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx) + defer parentTS.Finish(false) + + // Fill all concurrency slots + for i := 0; i < testMaxConcurrentSubTurns; i++ { + parentTS.concurrencySem <- struct{}{} + } + + // Create a context with a very short timeout for testing + testCtx, cancel := context.WithTimeout(ctx, 100*time.Millisecond) + defer cancel() + + // Now try to spawn a sub-turn with the short timeout context + subTurnCfg := SubTurnConfig{ + Model: "gpt-4o-mini", + Async: false, + } + + start := time.Now() + _, err := spawnSubTurn(testCtx, al, parentTS, subTurnCfg) + elapsed := time.Since(start) + + // Should get a timeout error (either from our timeout context or the internal one) + if err == nil { + t.Error("Expected timeout error, got nil") + } + + // The error should be related to context cancellation or timeout + if !errors.Is(err, context.DeadlineExceeded) && !errors.Is(err, ErrConcurrencyTimeout) { + t.Logf("Got error: %v (type: %T)", err, err) + // This is acceptable - the error might be wrapped + } + + // Should timeout quickly (within a reasonable margin) + if elapsed > 2*time.Second { + t.Errorf("Timeout took too long: %v", elapsed) + } + + t.Logf("Timeout occurred after %v with error: %v", elapsed, err) + + // Clean up - drain the semaphore + for i := 0; i < testMaxConcurrentSubTurns; i++ { + <-parentTS.concurrencySem + } +} + +// TestEphemeralSession_AutoTruncate verifies that ephemeral sessions automatically +// truncate their history to prevent memory accumulation. +func TestEphemeralSession_AutoTruncate(t *testing.T) { + store := newEphemeralSession(nil).(*ephemeralSessionStore) + + // Add more messages than the limit + for i := 0; i < maxEphemeralHistorySize+20; i++ { + store.AddMessage("test", "user", fmt.Sprintf("message-%d", i)) + } + + // Verify history is truncated to the limit + history := store.GetHistory("test") + if len(history) != maxEphemeralHistorySize { + t.Errorf("Expected history length %d, got %d", maxEphemeralHistorySize, len(history)) + } + + // Verify we kept the most recent messages + lastMsg := history[len(history)-1] + expectedContent := fmt.Sprintf("message-%d", maxEphemeralHistorySize+20-1) + if lastMsg.Content != expectedContent { + t.Errorf("Expected last message to be %q, got %q", expectedContent, lastMsg.Content) + } + + // Verify the oldest messages were discarded + firstMsg := history[0] + expectedFirstContent := fmt.Sprintf("message-%d", 20) // First 20 were discarded + if firstMsg.Content != expectedFirstContent { + t.Errorf("Expected first message to be %q, got %q", expectedFirstContent, firstMsg.Content) + } +} + +// TestContextWrapping_SingleLayer verifies that we only create one context layer +// in spawnSubTurn, not multiple redundant layers. +func TestContextWrapping_SingleLayer(t *testing.T) { + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Provider: "mock", + }, + }, + } + msgBus := bus.NewMessageBus() + provider := &simpleMockProviderAPI{} + al := NewAgentLoop(cfg, msgBus, provider) + + ctx := context.Background() + parentTS := &turnState{ + ctx: ctx, + turnID: "parent-context-test", + depth: 0, + session: newEphemeralSession(nil), + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns), + } + parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx) + defer parentTS.Finish(false) + + // Spawn a sub-turn + subTurnCfg := SubTurnConfig{ + Model: "gpt-4o-mini", + Async: false, + } + + result, err := spawnSubTurn(ctx, al, parentTS, subTurnCfg) + if err != nil { + t.Fatalf("spawnSubTurn failed: %v", err) + } + + if result == nil { + t.Error("Expected non-nil result") + } + + // Verify the child turn was created with a cancel function + // (This is implicit - if the test passes without hanging, the context management is correct) + t.Log("Context wrapping test passed - no redundant layers detected") +} + +// TestSyncSubTurn_NoChannelDelivery verifies that synchronous sub-turns +// do NOT deliver results to the pendingResults channel (only return directly). +func TestSyncSubTurn_NoChannelDelivery(t *testing.T) { + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Provider: "mock", + }, + }, + } + msgBus := bus.NewMessageBus() + provider := &simpleMockProviderAPI{} + al := NewAgentLoop(cfg, msgBus, provider) + + ctx := context.Background() + parentTS := &turnState{ + ctx: ctx, + turnID: "parent-sync-test", + depth: 0, + session: newEphemeralSession(nil), + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns), + } + parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx) + defer parentTS.Finish(false) + + // Spawn a SYNCHRONOUS sub-turn (Async=false) + subTurnCfg := SubTurnConfig{ + Model: "gpt-4o-mini", + Async: false, // Synchronous - should NOT deliver to channel + } + + result, err := spawnSubTurn(ctx, al, parentTS, subTurnCfg) + if err != nil { + t.Fatalf("spawnSubTurn failed: %v", err) + } + + if result == nil { + t.Error("Expected non-nil result from synchronous sub-turn") + } + + // Verify the pendingResults channel is EMPTY + // (synchronous sub-turns should not deliver to channel) + select { + case r := <-parentTS.pendingResults: + t.Errorf("Expected empty channel for sync sub-turn, but got result: %v", r) + default: + // Expected: channel is empty + t.Log("Verified: synchronous sub-turn did not deliver to channel") + } + + // Verify channel length is 0 + if len(parentTS.pendingResults) != 0 { + t.Errorf("Expected channel length 0, got %d", len(parentTS.pendingResults)) + } +} + +// TestAsyncSubTurn_ChannelDelivery verifies that asynchronous sub-turns +// DO deliver results to the pendingResults channel. +func TestAsyncSubTurn_ChannelDelivery(t *testing.T) { + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Provider: "mock", + }, + }, + } + msgBus := bus.NewMessageBus() + provider := &simpleMockProviderAPI{} + al := NewAgentLoop(cfg, msgBus, provider) + + ctx := context.Background() + parentTS := &turnState{ + ctx: ctx, + turnID: "parent-async-test", + depth: 0, + session: newEphemeralSession(nil), + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns), + } + parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx) + defer parentTS.Finish(false) + + // Spawn an ASYNCHRONOUS sub-turn (Async=true) + subTurnCfg := SubTurnConfig{ + Model: "gpt-4o-mini", + Async: true, // Asynchronous - SHOULD deliver to channel + } + + result, err := spawnSubTurn(ctx, al, parentTS, subTurnCfg) + if err != nil { + t.Fatalf("spawnSubTurn failed: %v", err) + } + + if result == nil { + t.Error("Expected non-nil result from asynchronous sub-turn") + } + + // Verify the pendingResults channel has the result + select { + case r := <-parentTS.pendingResults: + if r == nil { + t.Error("Expected non-nil result from channel") + } + t.Log("Verified: asynchronous sub-turn delivered to channel") + case <-time.After(100 * time.Millisecond): + t.Error("Expected result in channel for async sub-turn, but channel was empty") + } +} + +// TestGrandchildAbort_CascadingCancellation verifies that when a grandparent turn +// is hard aborted, the cancellation cascades down to grandchild turns. +func TestGrandchildAbort_CascadingCancellation(t *testing.T) { + al, _, _, provider, cleanup := newTestAgentLoop(t) + _ = provider + defer cleanup() + + // Three independent contexts — none derived from another. + // Cascade must happen exclusively through childTurnIDs traversal in Finish(true). + gpCtx, gpCancel := context.WithCancel(context.Background()) + parentCtx, parentCancel := context.WithCancel(context.Background()) + childCtx, childCancel := context.WithCancel(context.Background()) + + childTS := &turnState{ + ctx: childCtx, + cancelFunc: childCancel, + turnID: "grandchild", + al: al, + } + parentTS := &turnState{ + ctx: parentCtx, + cancelFunc: parentCancel, + turnID: "parent", + childTurnIDs: []string{"grandchild"}, + al: al, + } + grandparentTS := &turnState{ + ctx: gpCtx, + cancelFunc: gpCancel, + turnID: "grandparent", + depth: 0, + session: newEphemeralSession(nil), + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns), + childTurnIDs: []string{"parent"}, + al: al, + } + + al.activeTurnStates.Store("grandparent", grandparentTS) + al.activeTurnStates.Store("parent", parentTS) + al.activeTurnStates.Store("grandchild", childTS) + defer al.activeTurnStates.Delete("grandparent") + defer al.activeTurnStates.Delete("parent") + defer al.activeTurnStates.Delete("grandchild") + + // All contexts must be active before the abort + for _, ctx := range []context.Context{gpCtx, parentCtx, childCtx} { + select { + case <-ctx.Done(): + t.Fatal("context should not be canceled yet") + default: + } + } + + // Hard abort the grandparent — should cascade to parent and grandchild + grandparentTS.Finish(true) + + time.Sleep(10 * time.Millisecond) + + select { + case <-gpCtx.Done(): + t.Log("Grandparent context canceled (expected)") + default: + t.Error("Grandparent context should be canceled") + } + select { + case <-parentCtx.Done(): + t.Log("Parent context canceled via cascade (expected)") + default: + t.Error("Parent context should be canceled via childTurnIDs cascade") + } + select { + case <-childCtx.Done(): + t.Log("Grandchild context canceled via cascade (expected)") + default: + t.Error("Grandchild context should be canceled via childTurnIDs cascade") + } +} + +// TestSpawnDuringAbort_RaceCondition verifies behavior when trying to spawn +// a sub-turn while the parent is being aborted. +func TestSpawnDuringAbort_RaceCondition(t *testing.T) { + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Provider: "mock", + }, + }, + } + msgBus := bus.NewMessageBus() + provider := &simpleMockProviderAPI{} + al := NewAgentLoop(cfg, msgBus, provider) + + ctx := context.Background() + parentTS := &turnState{ + ctx: ctx, + turnID: "parent-abort-race", + depth: 0, + session: newEphemeralSession(nil), + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns), + } + parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx) + + var wg sync.WaitGroup + wg.Add(2) + + var spawnErr error + + // Goroutine 1: Try to spawn a sub-turn + go func() { + defer wg.Done() + subTurnCfg := SubTurnConfig{ + Model: "gpt-4o-mini", + Async: false, + } + _, err := spawnSubTurn(parentTS.ctx, al, parentTS, subTurnCfg) + spawnErr = err + }() + + // Goroutine 2: Abort the parent almost immediately + go func() { + defer wg.Done() + time.Sleep(1 * time.Millisecond) + parentTS.Finish(false) + }() + + wg.Wait() + + // The spawn should either succeed (if it started before abort) + // or fail with context canceled error (if abort happened first) + if spawnErr != nil { + if errors.Is(spawnErr, context.Canceled) { + t.Logf("Spawn failed with expected context cancellation: %v", spawnErr) + } else { + t.Logf("Spawn failed with error: %v", spawnErr) + } + } else { + t.Log("Spawn succeeded before abort") + } + + // The important thing is that it doesn't panic or deadlock + t.Log("Race condition handled gracefully - no panic or deadlock") +} + +// ====================== Slow SubTurn Cancellation Test ====================== + +// slowMockProvider simulates a slow LLM call that takes a long time to complete. +// This is used to test the scenario where a parent turn finishes before the child SubTurn. +type slowMockProvider struct { + delay time.Duration +} + +func (m *slowMockProvider) Chat( + ctx context.Context, + messages []providers.Message, + toolDefs []providers.ToolDefinition, + model string, + options map[string]any, +) (*providers.LLMResponse, error) { + select { + case <-time.After(m.delay): + // Completed normally after delay + return &providers.LLMResponse{ + Content: "slow response completed", + }, nil + case <-ctx.Done(): + // Context was canceled while waiting + return nil, ctx.Err() + } +} + +func (m *slowMockProvider) GetDefaultModel() string { + return "slow-model" +} + +// TestAsyncSubTurn_ParentFinishesEarly simulates the scenario where: +// 1. Parent spawns an async SubTurn that takes a long time +// 2. Parent finishes quickly +// 3. SubTurn should be canceled with context canceled error +func TestAsyncSubTurn_ParentFinishesEarly(t *testing.T) { + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Provider: "mock", + }, + }, + } + msgBus := bus.NewMessageBus() + provider := &slowMockProvider{delay: 5 * time.Second} // SubTurn takes 5 seconds + al := NewAgentLoop(cfg, msgBus, provider) + + // Capture events via real EventBus + var mu sync.Mutex + var events []Event + sub := al.SubscribeEvents(32) + defer al.UnsubscribeEvents(sub.ID) + go func() { + for evt := range sub.C { + mu.Lock() + events = append(events, evt) + mu.Unlock() + } + }() + + ctx := context.Background() + parentTS := &turnState{ + ctx: ctx, + turnID: "parent-fast", + depth: 0, + session: newEphemeralSession(nil), + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns), + } + parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx) + + var subTurnErr error + var subTurnResult *tools.ToolResult + var wg sync.WaitGroup + + // Spawn async SubTurn in a goroutine (it will be slow) + wg.Add(1) + go func() { + defer wg.Done() + subTurnCfg := SubTurnConfig{ + Model: "slow-model", + Async: true, // Asynchronous SubTurn + } + subTurnResult, subTurnErr = spawnSubTurn(parentTS.ctx, al, parentTS, subTurnCfg) + }() + + // Parent finishes quickly (after 100ms), while SubTurn is still running + time.Sleep(100 * time.Millisecond) + t.Log("Parent finishing early...") + parentTS.Finish(false) + + // Wait for SubTurn to complete (or be canceled) + wg.Wait() + + // Check the result + t.Logf("SubTurn error: %v", subTurnErr) + t.Logf("SubTurn result: %v", subTurnResult) + + if subTurnErr != nil { + if errors.Is(subTurnErr, context.Canceled) { + t.Log("✓ SubTurn was canceled as expected (context canceled)") + } else { + t.Logf("SubTurn failed with other error: %v", subTurnErr) + } + } else { + t.Log("SubTurn completed before parent finished (unlikely but possible)") + } + + // Log captured events + mu.Lock() + t.Logf("Captured %d events:", len(events)) + for i, e := range events { + t.Logf(" Event %d: %s", i+1, e.Kind) + } + mu.Unlock() +} + +// TestAsyncSubTurn_ParentWaitsForChild simulates the scenario where: +// 1. Parent spawns an async SubTurn that takes some time +// 2. Parent WAITS for SubTurn to complete before finishing +// 3. Both should complete successfully +func TestAsyncSubTurn_ParentWaitsForChild(t *testing.T) { + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Provider: "mock", + }, + }, + } + msgBus := bus.NewMessageBus() + provider := &slowMockProvider{delay: 200 * time.Millisecond} // SubTurn takes 200ms + al := NewAgentLoop(cfg, msgBus, provider) + + ctx := context.Background() + parentTS := &turnState{ + ctx: ctx, + turnID: "parent-wait", + depth: 0, + session: newEphemeralSession(nil), + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns), + } + parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx) + + var subTurnErr error + var subTurnResult *tools.ToolResult + var wg sync.WaitGroup + + // Spawn async SubTurn in a goroutine + wg.Add(1) + go func() { + defer wg.Done() + subTurnCfg := SubTurnConfig{ + Model: "slow-model", + Async: true, + } + subTurnResult, subTurnErr = spawnSubTurn(parentTS.ctx, al, parentTS, subTurnCfg) + }() + + // Parent WAITS for SubTurn to complete + t.Log("Parent waiting for SubTurn...") + wg.Wait() + t.Log("SubTurn completed, parent now finishing") + + // Now parent can finish safely + parentTS.Finish(false) + + // Check the result + if subTurnErr != nil { + if errors.Is(subTurnErr, context.Canceled) { + t.Errorf("SubTurn should NOT have been canceled: %v", subTurnErr) + } else { + t.Logf("SubTurn failed with error: %v", subTurnErr) + } + } else { + t.Log("✓ SubTurn completed successfully") + if subTurnResult != nil { + t.Logf("SubTurn result: %s", subTurnResult.ForLLM) + } + } + + // Check channel delivery + select { + case r := <-parentTS.pendingResults: + if r != nil { + t.Logf("✓ Result delivered to channel: %s", r.ForLLM) + } + case <-time.After(100 * time.Millisecond): + t.Log("No result in channel (expected since we waited)") + } +} + +// ====================== Graceful vs Hard Finish Tests ====================== + +// TestFinish_GracefulVsHard verifies the behavior difference between: +// - Finish(false): graceful finish, signals parentEnded but doesn't cancel children +// - Finish(true): hard abort, immediately cancels all children +func TestFinish_GracefulVsHard(t *testing.T) { + // Test 1: Graceful finish should set parentEnded but not cancel context + t.Run("Graceful_SetsParentEnded", func(t *testing.T) { + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + + ts := &turnState{ + ctx: ctx, + turnID: "graceful-test", + depth: 0, + pendingResults: make(chan *tools.ToolResult, 16), + } + ts.ctx, ts.cancelFunc = context.WithCancel(ctx) + + // Finish gracefully + ts.Finish(false) + + // Verify parentEnded is set + if !ts.parentEnded.Load() { + t.Error("parentEnded should be true after graceful finish") + } + + // Verify context is NOT canceled (for graceful finish, children continue) + // Note: In graceful mode, we don't call cancelFunc() + // But since we're using WithCancel on the same ctx, it might be canceled + // Let's check that the context is still valid for a moment + time.Sleep(10 * time.Millisecond) + // Context might be canceled by the deferred cancel() in test, which is fine + }) + + // Test 2: Hard abort should cancel context immediately + t.Run("Hard_CancelsContext", func(t *testing.T) { + ctx := context.Background() + + ts := &turnState{ + ctx: ctx, + turnID: "hard-test", + depth: 0, + pendingResults: make(chan *tools.ToolResult, 16), + } + ts.ctx, ts.cancelFunc = context.WithCancel(ctx) + + // Finish with hard abort + ts.Finish(true) + + // Verify context is canceled + select { + case <-ts.ctx.Done(): + t.Log("✓ Context canceled after hard abort") + default: + t.Error("Context should be canceled after hard abort") + } + }) + + // Test 3: IsParentEnded returns correct value + t.Run("IsParentEnded", func(t *testing.T) { + ctx := context.Background() + + parentTS := &turnState{ + ctx: ctx, + turnID: "parent-isended-test", + depth: 0, + pendingResults: make(chan *tools.ToolResult, 16), + } + parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx) + + childTS := &turnState{ + ctx: ctx, + turnID: "child-isended-test", + depth: 1, + parentTurnState: parentTS, + pendingResults: make(chan *tools.ToolResult, 16), + } + + // Before parent finishes + if childTS.IsParentEnded() { + t.Error("IsParentEnded should be false before parent finishes") + } + + // Finish parent gracefully + parentTS.Finish(false) + + // After parent finishes + if !childTS.IsParentEnded() { + t.Error("IsParentEnded should be true after parent finishes gracefully") + } + }) +} + +// TestSubTurn_IndependentContext verifies that SubTurns use independent contexts +// that don't get canceled when the parent finishes gracefully. +func TestSubTurn_IndependentContext(t *testing.T) { + cfg := &config.Config{ + Agents: config.AgentsConfig{ + Defaults: config.AgentDefaults{ + Provider: "mock", + }, + }, + } + msgBus := bus.NewMessageBus() + provider := &slowMockProvider{delay: 500 * time.Millisecond} + al := NewAgentLoop(cfg, msgBus, provider) + + ctx := context.Background() + parentTS := &turnState{ + ctx: ctx, + turnID: "parent-independent", + depth: 0, + session: newEphemeralSession(nil), + pendingResults: make(chan *tools.ToolResult, 16), + concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns), + } + parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx) + + var subTurnErr error + var wg sync.WaitGroup + + // Spawn SubTurn with Critical=true (should continue after parent finishes) + wg.Add(1) + go func() { + defer wg.Done() + subTurnCfg := SubTurnConfig{ + Model: "slow-model", + Async: true, + Critical: true, // Critical SubTurn should continue + } + _, subTurnErr = spawnSubTurn(parentTS.ctx, al, parentTS, subTurnCfg) + }() + + // Let SubTurn start + time.Sleep(50 * time.Millisecond) + + // Parent finishes gracefully (should NOT cancel SubTurn) + parentTS.Finish(false) + t.Log("Parent finished gracefully, SubTurn should continue") + + // Wait for SubTurn to complete + wg.Wait() + + // SubTurn should complete without context canceled error + // (because it uses independent context now) + if subTurnErr != nil { + t.Logf("SubTurn error: %v", subTurnErr) + // The error might be context.DeadlineExceeded if timeout is too short + // but should NOT be context.Canceled from parent + if errors.Is(subTurnErr, context.Canceled) { + t.Error("SubTurn should not be canceled by parent's graceful finish") + } + } else { + t.Log("✓ SubTurn completed successfully (independent context)") + } +} diff --git a/pkg/agent/turn.go b/pkg/agent/turn.go new file mode 100644 index 00000000..e4970c51 --- /dev/null +++ b/pkg/agent/turn.go @@ -0,0 +1,481 @@ +package agent + +import ( + "context" + "reflect" + "sync" + "sync/atomic" + "time" + + "github.com/sipeed/picoclaw/pkg/bus" + "github.com/sipeed/picoclaw/pkg/providers" + "github.com/sipeed/picoclaw/pkg/session" + "github.com/sipeed/picoclaw/pkg/tools" +) + +type TurnPhase string + +const ( + TurnPhaseSetup TurnPhase = "setup" + TurnPhaseRunning TurnPhase = "running" + TurnPhaseTools TurnPhase = "tools" + TurnPhaseFinalizing TurnPhase = "finalizing" + TurnPhaseCompleted TurnPhase = "completed" + TurnPhaseAborted TurnPhase = "aborted" +) + +type ActiveTurnInfo struct { + TurnID string + AgentID string + SessionKey string + Channel string + ChatID string + UserMessage string + Phase TurnPhase + Iteration int + StartedAt time.Time + Depth int + ParentTurnID string + ChildTurnIDs []string +} + +type turnResult struct { + finalContent string + status TurnEndStatus + followUps []bus.InboundMessage +} + +type turnState struct { + mu sync.RWMutex + + agent *AgentInstance + opts processOptions + scope turnEventScope + + turnID string + agentID string + sessionKey string + + channel string + chatID string + userMessage string + media []string + + phase TurnPhase + iteration int + startedAt time.Time + finalContent string + + followUps []bus.InboundMessage + + gracefulInterrupt bool + gracefulInterruptHint string + gracefulTerminalUsed bool + hardAbort bool + providerCancel context.CancelFunc + turnCancel context.CancelFunc + + restorePointHistory []providers.Message + restorePointSummary string + persistedMessages []providers.Message + + // SubTurn support (from HEAD) + depth int // SubTurn depth (0 for root turn) + parentTurnID string // Parent turn ID (empty for root turn) + childTurnIDs []string // Child turn IDs + pendingResults chan *tools.ToolResult // Channel for SubTurn results + concurrencySem chan struct{} // Semaphore for limiting concurrent SubTurns + isFinished atomic.Bool // Whether this turn has finished + session session.SessionStore // Session store reference + initialHistoryLength int // Snapshot of history length at turn start + + // Additional SubTurn fields + ctx context.Context // Context for this turn + cancelFunc context.CancelFunc // Cancel function for this turn's context + critical bool // Whether this SubTurn should continue after parent ends + parentTurnState *turnState // Reference to parent turnState + parentEnded atomic.Bool // Whether parent has ended + closeOnce sync.Once // Ensures pendingResults channel is closed once + finishedChan chan struct{} // Closed when turn finishes + + // Token budget tracking + tokenBudget *atomic.Int64 // Shared token budget counter + lastFinishReason string // Last LLM finish_reason + lastUsage *providers.UsageInfo // Last LLM usage info + + // Back-reference to the owning AgentLoop (set for SubTurns only, used for hard abort cascade) + al *AgentLoop +} + +func newTurnState(agent *AgentInstance, opts processOptions, scope turnEventScope) *turnState { + ts := &turnState{ + agent: agent, + opts: opts, + scope: scope, + turnID: scope.turnID, + agentID: agent.ID, + sessionKey: opts.SessionKey, + channel: opts.Channel, + chatID: opts.ChatID, + userMessage: opts.UserMessage, + media: append([]string(nil), opts.Media...), + phase: TurnPhaseSetup, + startedAt: time.Now(), + } + + // Bind session store and capture initial history length for rollback logic + if agent != nil && agent.Sessions != nil { + ts.session = agent.Sessions + ts.initialHistoryLength = len(agent.Sessions.GetHistory(opts.SessionKey)) + } + + return ts +} + +func (al *AgentLoop) registerActiveTurn(ts *turnState) { + al.activeTurnStates.Store(ts.sessionKey, ts) +} + +func (al *AgentLoop) clearActiveTurn(ts *turnState) { + al.activeTurnStates.Delete(ts.sessionKey) +} + +func (al *AgentLoop) getActiveTurnState(sessionKey string) *turnState { + if val, ok := al.activeTurnStates.Load(sessionKey); ok { + return val.(*turnState) + } + return nil +} + +// getAnyActiveTurnState returns any active turn state (for backward compatibility) +func (al *AgentLoop) getAnyActiveTurnState() *turnState { + var firstTS *turnState + al.activeTurnStates.Range(func(key, value any) bool { + firstTS = value.(*turnState) + return false // stop after first + }) + return firstTS +} + +func (al *AgentLoop) GetActiveTurn() *ActiveTurnInfo { + // For backward compatibility, return the first active turn found + // In the new architecture, there can be multiple concurrent turns + var firstTS *turnState + al.activeTurnStates.Range(func(key, value any) bool { + firstTS = value.(*turnState) + return false // stop after first + }) + if firstTS == nil { + return nil + } + info := firstTS.snapshot() + return &info +} + +func (al *AgentLoop) GetActiveTurnBySession(sessionKey string) *ActiveTurnInfo { + ts := al.getActiveTurnState(sessionKey) + if ts == nil { + return nil + } + info := ts.snapshot() + return &info +} + +func (ts *turnState) snapshot() ActiveTurnInfo { + ts.mu.RLock() + defer ts.mu.RUnlock() + + return ActiveTurnInfo{ + TurnID: ts.turnID, + AgentID: ts.agentID, + SessionKey: ts.sessionKey, + Channel: ts.channel, + ChatID: ts.chatID, + UserMessage: ts.userMessage, + Phase: ts.phase, + Iteration: ts.iteration, + StartedAt: ts.startedAt, + Depth: ts.depth, + ParentTurnID: ts.parentTurnID, + ChildTurnIDs: append([]string(nil), ts.childTurnIDs...), + } +} + +func (ts *turnState) setPhase(phase TurnPhase) { + ts.mu.Lock() + defer ts.mu.Unlock() + ts.phase = phase +} + +func (ts *turnState) setIteration(iteration int) { + ts.mu.Lock() + defer ts.mu.Unlock() + ts.iteration = iteration +} + +func (ts *turnState) currentIteration() int { + ts.mu.RLock() + defer ts.mu.RUnlock() + return ts.iteration +} + +func (ts *turnState) setFinalContent(content string) { + ts.mu.Lock() + defer ts.mu.Unlock() + ts.finalContent = content +} + +func (ts *turnState) finalContentLen() int { + ts.mu.RLock() + defer ts.mu.RUnlock() + return len(ts.finalContent) +} + +func (ts *turnState) setTurnCancel(cancel context.CancelFunc) { + ts.mu.Lock() + defer ts.mu.Unlock() + ts.turnCancel = cancel +} + +func (ts *turnState) setProviderCancel(cancel context.CancelFunc) { + ts.mu.Lock() + defer ts.mu.Unlock() + ts.providerCancel = cancel +} + +func (ts *turnState) clearProviderCancel(_ context.CancelFunc) { + ts.mu.Lock() + defer ts.mu.Unlock() + ts.providerCancel = nil +} + +func (ts *turnState) requestGracefulInterrupt(hint string) bool { + ts.mu.Lock() + defer ts.mu.Unlock() + if ts.hardAbort { + return false + } + ts.gracefulInterrupt = true + ts.gracefulInterruptHint = hint + return true +} + +func (ts *turnState) gracefulInterruptRequested() (bool, string) { + ts.mu.RLock() + defer ts.mu.RUnlock() + return ts.gracefulInterrupt && !ts.gracefulTerminalUsed, ts.gracefulInterruptHint +} + +func (ts *turnState) markGracefulTerminalUsed() { + ts.mu.Lock() + defer ts.mu.Unlock() + ts.gracefulTerminalUsed = true +} + +func (ts *turnState) requestHardAbort() bool { + ts.mu.Lock() + if ts.hardAbort { + ts.mu.Unlock() + return false + } + ts.hardAbort = true + turnCancel := ts.turnCancel + providerCancel := ts.providerCancel + ts.mu.Unlock() + + if providerCancel != nil { + providerCancel() + } + if turnCancel != nil { + turnCancel() + } + return true +} + +func (ts *turnState) hardAbortRequested() bool { + ts.mu.RLock() + defer ts.mu.RUnlock() + return ts.hardAbort +} + +func (ts *turnState) eventMeta(source, tracePath string) EventMeta { + snap := ts.snapshot() + return EventMeta{ + AgentID: snap.AgentID, + TurnID: snap.TurnID, + SessionKey: snap.SessionKey, + Iteration: snap.Iteration, + Source: source, + TracePath: tracePath, + } +} + +func (ts *turnState) captureRestorePoint(history []providers.Message, summary string) { + ts.mu.Lock() + defer ts.mu.Unlock() + ts.restorePointHistory = append([]providers.Message(nil), history...) + ts.restorePointSummary = summary +} + +func (ts *turnState) recordPersistedMessage(msg providers.Message) { + ts.mu.Lock() + defer ts.mu.Unlock() + ts.persistedMessages = append(ts.persistedMessages, msg) +} + +func (ts *turnState) refreshRestorePointFromSession(agent *AgentInstance) { + history := agent.Sessions.GetHistory(ts.sessionKey) + summary := agent.Sessions.GetSummary(ts.sessionKey) + + ts.mu.RLock() + persisted := append([]providers.Message(nil), ts.persistedMessages...) + ts.mu.RUnlock() + + if matched := matchingTurnMessageTail(history, persisted); matched > 0 { + history = append([]providers.Message(nil), history[:len(history)-matched]...) + } + + ts.captureRestorePoint(history, summary) +} + +func (ts *turnState) restoreSession(agent *AgentInstance) error { + ts.mu.RLock() + history := append([]providers.Message(nil), ts.restorePointHistory...) + summary := ts.restorePointSummary + ts.mu.RUnlock() + + agent.Sessions.SetHistory(ts.sessionKey, history) + agent.Sessions.SetSummary(ts.sessionKey, summary) + return agent.Sessions.Save(ts.sessionKey) +} + +func matchingTurnMessageTail(history, persisted []providers.Message) int { + maxMatch := min(len(history), len(persisted)) + for size := maxMatch; size > 0; size-- { + if reflect.DeepEqual(history[len(history)-size:], persisted[len(persisted)-size:]) { + return size + } + } + return 0 +} + +func (ts *turnState) interruptHintMessage() providers.Message { + _, hint := ts.gracefulInterruptRequested() + content := "Interrupt requested. Stop scheduling tools and provide a short final summary." + if hint != "" { + content += "\n\nInterrupt hint: " + hint + } + return providers.Message{ + Role: "user", + Content: content, + } +} + +// SubTurn-related methods + +// Finish marks the turn as finished and closes the pendingResults channel +func (ts *turnState) Finish(isHardAbort bool) { + ts.isFinished.Store(true) + + // Close pendingResults channel exactly once + ts.closeOnce.Do(func() { + if ts.pendingResults != nil { + close(ts.pendingResults) + } + ts.mu.Lock() + if ts.finishedChan == nil { + ts.finishedChan = make(chan struct{}) + } + close(ts.finishedChan) + ts.mu.Unlock() + }) + + // If this is a graceful finish (not hard abort), signal to children + if !isHardAbort && ts.parentTurnState == nil { + // This is a root turn finishing gracefully + ts.parentEnded.Store(true) + } + + // Cancel the turn context + if ts.cancelFunc != nil { + ts.cancelFunc() + } + + // Hard abort cascades to all child turns + if isHardAbort && ts.al != nil { + ts.mu.RLock() + children := append([]string(nil), ts.childTurnIDs...) + ts.mu.RUnlock() + for _, childID := range children { + if val, ok := ts.al.activeTurnStates.Load(childID); ok { + val.(*turnState).Finish(true) + } + } + } +} + +// Finished returns whether the turn has finished +func (ts *turnState) Finished() chan struct{} { + ts.mu.Lock() + defer ts.mu.Unlock() + if ts.finishedChan == nil { + ts.finishedChan = make(chan struct{}) + } + return ts.finishedChan +} + +// IsParentEnded checks if the parent turn has ended +func (ts *turnState) IsParentEnded() bool { + if ts.parentTurnState == nil { + return false + } + return ts.parentTurnState.parentEnded.Load() +} + +// GetLastFinishReason returns the last LLM finish_reason +func (ts *turnState) GetLastFinishReason() string { + ts.mu.RLock() + defer ts.mu.RUnlock() + return ts.lastFinishReason +} + +// SetLastFinishReason sets the last LLM finish_reason +func (ts *turnState) SetLastFinishReason(reason string) { + ts.mu.Lock() + defer ts.mu.Unlock() + ts.lastFinishReason = reason +} + +// GetLastUsage returns the last LLM usage info +func (ts *turnState) GetLastUsage() *providers.UsageInfo { + ts.mu.RLock() + defer ts.mu.RUnlock() + return ts.lastUsage +} + +// SetLastUsage sets the last LLM usage info +func (ts *turnState) SetLastUsage(usage *providers.UsageInfo) { + ts.mu.Lock() + defer ts.mu.Unlock() + ts.lastUsage = usage +} + +// Context helper functions for SubTurn + +type turnStateKeyType struct{} + +var turnStateKey = turnStateKeyType{} + +func withTurnState(ctx context.Context, ts *turnState) context.Context { + return context.WithValue(ctx, turnStateKey, ts) +} + +func turnStateFromContext(ctx context.Context) *turnState { + ts, _ := ctx.Value(turnStateKey).(*turnState) + return ts +} + +// TurnStateFromContext retrieves turnState from context (exported for tools) +func TurnStateFromContext(ctx context.Context) *turnState { + return turnStateFromContext(ctx) +} diff --git a/pkg/channels/manager.go b/pkg/channels/manager.go index fec4922c..9fc16861 100644 --- a/pkg/channels/manager.go +++ b/pkg/channels/manager.go @@ -419,6 +419,10 @@ func (m *Manager) initChannels(channels *config.ChannelsConfig) error { m.initChannel("wecom_app", "WeCom App") } + if channels.Weixin.Enabled && channels.Weixin.Token != "" { + m.initChannel("weixin", "Weixin") + } + if channels.Pico.Enabled && channels.Pico.Token != "" { m.initChannel("pico", "Pico") } diff --git a/pkg/channels/qq/audio_duration.go b/pkg/channels/qq/audio_duration.go new file mode 100644 index 00000000..28a9b2e8 --- /dev/null +++ b/pkg/channels/qq/audio_duration.go @@ -0,0 +1,231 @@ +package qq + +import ( + "encoding/binary" + "io" + "os" + "path/filepath" + "strings" + "time" +) + +const qqVoiceMaxDuration = 60 * time.Second + +func qqAudioDuration(localPath, filename, contentType string) (time.Duration, bool, error) { + if localPath == "" { + return 0, false, nil + } + + switch qqAudioDurationFormat(localPath, filename, contentType) { + case "wav": + return qqWAVDuration(localPath) + case "ogg": + return qqOggDuration(localPath) + default: + return 0, false, nil + } +} + +func qqAudioDurationFormat(localPath, filename, contentType string) string { + contentType = strings.ToLower(contentType) + + switch { + case strings.HasPrefix(contentType, "audio/wav"), strings.HasPrefix(contentType, "audio/x-wav"): + return "wav" + case strings.HasPrefix(contentType, "audio/ogg"), + contentType == "application/ogg", + contentType == "application/x-ogg": + return "ogg" + } + + switch filepath.Ext(strings.ToLower(filename)) { + case ".wav": + return "wav" + case ".ogg", ".opus": + return "ogg" + } + + switch filepath.Ext(strings.ToLower(localPath)) { + case ".wav": + return "wav" + case ".ogg", ".opus": + return "ogg" + } + + return "" +} + +func qqWAVDuration(localPath string) (time.Duration, bool, error) { + file, err := os.Open(localPath) + if err != nil { + return 0, false, err + } + defer file.Close() + + var header [12]byte + if _, err := io.ReadFull(file, header[:]); err != nil { + return 0, false, err + } + + var order binary.ByteOrder + switch string(header[:4]) { + case "RIFF": + order = binary.LittleEndian + case "RIFX": + order = binary.BigEndian + default: + return 0, false, nil + } + + if string(header[8:12]) != "WAVE" { + return 0, false, nil + } + + var byteRate uint32 + var dataSize uint32 + var foundFmt bool + var foundData bool + + for { + var chunkHeader [8]byte + if _, err := io.ReadFull(file, chunkHeader[:]); err != nil { + if err == io.EOF { + break + } + return 0, false, err + } + + chunkSize := order.Uint32(chunkHeader[4:8]) + switch string(chunkHeader[:4]) { + case "fmt ": + chunkData := make([]byte, chunkSize) + if _, err := io.ReadFull(file, chunkData); err != nil { + return 0, false, err + } + if len(chunkData) >= 12 { + byteRate = order.Uint32(chunkData[8:12]) + foundFmt = true + } + case "data": + dataSize = chunkSize + foundData = true + if _, err := io.CopyN(io.Discard, file, int64(chunkSize)); err != nil { + return 0, false, err + } + default: + if _, err := io.CopyN(io.Discard, file, int64(chunkSize)); err != nil { + return 0, false, err + } + } + + if chunkSize%2 == 1 { + if _, err := io.CopyN(io.Discard, file, 1); err != nil { + return 0, false, err + } + } + + if foundFmt && foundData { + break + } + } + + if !foundFmt || !foundData || byteRate == 0 { + return 0, false, nil + } + + durationNS := int64(dataSize) * int64(time.Second) / int64(byteRate) + return time.Duration(durationNS), true, nil +} + +func qqOggDuration(localPath string) (time.Duration, bool, error) { + file, err := os.Open(localPath) + if err != nil { + return 0, false, err + } + defer file.Close() + + var firstPacket []byte + var codec string + var sampleRate uint32 + var lastGranule uint64 + var haveGranule bool + + for { + var header [27]byte + if _, err := io.ReadFull(file, header[:]); err != nil { + if err == io.EOF { + break + } + return 0, false, err + } + + if string(header[:4]) != "OggS" { + return 0, false, nil + } + + pageSegments := int(header[26]) + segments := make([]byte, pageSegments) + if _, err := io.ReadFull(file, segments); err != nil { + return 0, false, err + } + + payloadLen := 0 + for _, segLen := range segments { + payloadLen += int(segLen) + } + + payload := make([]byte, payloadLen) + if _, err := io.ReadFull(file, payload); err != nil { + return 0, false, err + } + + granule := binary.LittleEndian.Uint64(header[6:14]) + if granule != ^uint64(0) { + lastGranule = granule + haveGranule = true + } + + if codec == "" { + offset := 0 + for _, segLen := range segments { + firstPacket = append(firstPacket, payload[offset:offset+int(segLen)]...) + offset += int(segLen) + if segLen < 255 { + codec, sampleRate = qqParseOggCodec(firstPacket) + break + } + } + } + } + + if !haveGranule || codec == "" { + return 0, false, nil + } + + switch codec { + case "opus": + return time.Duration(lastGranule) * time.Second / 48000, true, nil + case "vorbis": + if sampleRate == 0 { + return 0, false, nil + } + return time.Duration(lastGranule) * time.Second / time.Duration(sampleRate), true, nil + default: + return 0, false, nil + } +} + +func qqParseOggCodec(packet []byte) (string, uint32) { + if len(packet) >= 8 && string(packet[:8]) == "OpusHead" { + return "opus", 48000 + } + + if len(packet) >= 16 && packet[0] == 0x01 && string(packet[1:7]) == "vorbis" { + sampleRate := binary.LittleEndian.Uint32(packet[12:16]) + if sampleRate > 0 { + return "vorbis", sampleRate + } + } + + return "", 0 +} diff --git a/pkg/channels/qq/qq.go b/pkg/channels/qq/qq.go index 1a48369f..2cd6e174 100644 --- a/pkg/channels/qq/qq.go +++ b/pkg/channels/qq/qq.go @@ -387,12 +387,11 @@ func (c *QQChannel) uploadMedia( } func (c *QQChannel) buildMediaUpload(part bus.MediaPart) (*qqMediaUpload, error) { - payload := &qqMediaUpload{ - FileType: qqFileType(part.Type), - } + payload := &qqMediaUpload{} mediaRef := part.Ref if isHTTPURL(mediaRef) { + payload.FileType = qqFileType(c.outboundMediaType(part, "")) payload.URL = mediaRef return payload, nil } @@ -402,15 +401,23 @@ func (c *QQChannel) buildMediaUpload(part bus.MediaPart) (*qqMediaUpload, error) return nil, fmt.Errorf("no media store available: %w", channels.ErrSendFailed) } - resolved, err := store.Resolve(part.Ref) + resolved, meta, err := store.ResolveWithMeta(part.Ref) if err != nil { return nil, fmt.Errorf("qq resolve media ref %q: %v: %w", part.Ref, err, channels.ErrSendFailed) } + if part.Filename == "" { + part.Filename = meta.Filename + } + if part.ContentType == "" { + part.ContentType = meta.ContentType + } if isHTTPURL(resolved) { + payload.FileType = qqFileType(c.outboundMediaType(part, "")) payload.URL = resolved return payload, nil } + payload.FileType = qqFileType(c.outboundMediaType(part, resolved)) if limitBytes := c.maxBase64FileSizeBytes(); limitBytes > 0 { info, statErr := os.Stat(resolved) @@ -437,6 +444,48 @@ func (c *QQChannel) buildMediaUpload(part bus.MediaPart) (*qqMediaUpload, error) return payload, nil } +func (c *QQChannel) outboundMediaType(part bus.MediaPart, localPath string) string { + if part.Type != "audio" { + return part.Type + } + + if localPath == "" { + logger.InfoCF("qq", "Sending audio as file because duration is unavailable", map[string]any{ + "ref": part.Ref, + "filename": part.Filename, + }) + return "file" + } + + duration, ok, err := qqAudioDuration(localPath, part.Filename, part.ContentType) + if err != nil { + logger.WarnCF("qq", "Failed to detect audio duration, sending as file", map[string]any{ + "ref": part.Ref, + "filename": part.Filename, + "error": err.Error(), + }) + return "file" + } + if !ok { + logger.InfoCF("qq", "Sending audio as file because duration is unavailable", map[string]any{ + "ref": part.Ref, + "filename": part.Filename, + }) + return "file" + } + if duration > qqVoiceMaxDuration { + logger.InfoCF("qq", "Sending audio as file because it exceeds QQ voice limit", map[string]any{ + "ref": part.Ref, + "filename": part.Filename, + "duration_seconds": duration.Seconds(), + "limit_seconds": qqVoiceMaxDuration.Seconds(), + }) + return "file" + } + + return "audio" +} + func (c *QQChannel) sendUploadedMedia( ctx context.Context, chatKind, chatID string, diff --git a/pkg/channels/qq/qq_test.go b/pkg/channels/qq/qq_test.go index 3cb3d39b..108965c0 100644 --- a/pkg/channels/qq/qq_test.go +++ b/pkg/channels/qq/qq_test.go @@ -1,8 +1,10 @@ package qq import ( + "bytes" "context" "encoding/base64" + "encoding/binary" "encoding/json" "errors" "os" @@ -264,6 +266,142 @@ func TestSendMedia_UploadsLocalFileAsBase64(t *testing.T) { } } +func TestSendMedia_AudioAt60SecondsUsesVoiceUpload(t *testing.T) { + assertAudioWAVUploadType(t, 60*time.Second, 3) +} + +func TestSendMedia_AudioOver60SecondsFallsBackToFileUpload(t *testing.T) { + assertAudioWAVUploadType(t, 61*time.Second, 4) +} + +func assertAudioWAVUploadType(t *testing.T, duration time.Duration, wantFileType uint64) { + t.Helper() + + messageBus := bus.NewMessageBus() + store := media.NewFileMediaStore() + + localPath := writeWAVFile(t, t.TempDir(), "voice.wav", duration) + ref, err := store.Store(localPath, media.MediaMeta{ + Filename: "voice.wav", + ContentType: "audio/wav", + }, "qq:test") + if err != nil { + t.Fatalf("Store() error = %v", err) + } + + api := &fakeQQAPI{ + transportResp: mustJSON(t, dto.Message{FileInfo: []byte("file-info")}), + } + ch := &QQChannel{ + BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil), + api: api, + dedup: make(map[string]time.Time), + done: make(chan struct{}), + ctx: context.Background(), + } + ch.SetRunning(true) + ch.SetMediaStore(store) + ch.chatType.Store("group-1", "group") + + err = ch.SendMedia(context.Background(), bus.OutboundMediaMessage{ + ChatID: "group-1", + Parts: []bus.MediaPart{{ + Type: "audio", + Ref: ref, + }}, + }) + if err != nil { + t.Fatalf("SendMedia() error = %v", err) + } + + if len(api.transportCalls) != 1 { + t.Fatalf("transportCalls = %d, want 1", len(api.transportCalls)) + } + if api.transportCalls[0].body.FileType != wantFileType { + t.Fatalf("upload file_type = %d, want %d", api.transportCalls[0].body.FileType, wantFileType) + } +} + +func TestSendMedia_RemoteAudioFallsBackToFileUpload(t *testing.T) { + messageBus := bus.NewMessageBus() + api := &fakeQQAPI{ + transportResp: mustJSON(t, dto.Message{FileInfo: []byte("remote-file-info")}), + } + ch := &QQChannel{ + BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil), + api: api, + dedup: make(map[string]time.Time), + done: make(chan struct{}), + ctx: context.Background(), + } + ch.SetRunning(true) + ch.chatType.Store("user-1", "direct") + + err := ch.SendMedia(context.Background(), bus.OutboundMediaMessage{ + ChatID: "user-1", + Parts: []bus.MediaPart{{ + Type: "audio", + Ref: "https://cdn.example.com/voice.ogg", + }}, + }) + if err != nil { + t.Fatalf("SendMedia() error = %v", err) + } + + if len(api.transportCalls) != 1 { + t.Fatalf("transportCalls = %d, want 1", len(api.transportCalls)) + } + if api.transportCalls[0].body.FileType != 4 { + t.Fatalf("upload file_type = %d, want 4", api.transportCalls[0].body.FileType) + } +} + +func TestSendMedia_LocalAudioWithUnknownDurationFallsBackToFileUpload(t *testing.T) { + messageBus := bus.NewMessageBus() + store := media.NewFileMediaStore() + + localPath := writeTempFile(t, t.TempDir(), "voice.mp3", []byte("not-a-real-mp3")) + ref, err := store.Store(localPath, media.MediaMeta{ + Filename: "voice.mp3", + ContentType: "audio/mpeg", + }, "qq:test") + if err != nil { + t.Fatalf("Store() error = %v", err) + } + + api := &fakeQQAPI{ + transportResp: mustJSON(t, dto.Message{FileInfo: []byte("file-info")}), + } + ch := &QQChannel{ + BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil), + api: api, + dedup: make(map[string]time.Time), + done: make(chan struct{}), + ctx: context.Background(), + } + ch.SetRunning(true) + ch.SetMediaStore(store) + ch.chatType.Store("group-1", "group") + + err = ch.SendMedia(context.Background(), bus.OutboundMediaMessage{ + ChatID: "group-1", + Parts: []bus.MediaPart{{ + Type: "audio", + Ref: ref, + }}, + }) + if err != nil { + t.Fatalf("SendMedia() error = %v", err) + } + + if len(api.transportCalls) != 1 { + t.Fatalf("transportCalls = %d, want 1", len(api.transportCalls)) + } + if api.transportCalls[0].body.FileType != 4 { + t.Fatalf("upload file_type = %d, want 4", api.transportCalls[0].body.FileType) + } +} + func TestSendMedia_UsesRemoteURLUploadForC2C(t *testing.T) { messageBus := bus.NewMessageBus() api := &fakeQQAPI{ @@ -494,3 +632,53 @@ func writeTempFile(t *testing.T, dir, name string, content []byte) string { } return path } + +func writeWAVFile(t *testing.T, dir, name string, duration time.Duration) string { + t.Helper() + + const ( + sampleRate = 8000 + numChannels = 1 + bitsPerSample = 8 + ) + + dataSize := uint32(duration / time.Second * sampleRate * numChannels * (bitsPerSample / 8)) + byteRate := uint32(sampleRate * numChannels * (bitsPerSample / 8)) + blockAlign := uint16(numChannels * (bitsPerSample / 8)) + + var buf bytes.Buffer + buf.WriteString("RIFF") + if err := binary.Write(&buf, binary.LittleEndian, uint32(36)+dataSize); err != nil { + t.Fatalf("binary.Write(riff size) error = %v", err) + } + buf.WriteString("WAVE") + buf.WriteString("fmt ") + if err := binary.Write(&buf, binary.LittleEndian, uint32(16)); err != nil { + t.Fatalf("binary.Write(fmt chunk size) error = %v", err) + } + if err := binary.Write(&buf, binary.LittleEndian, uint16(1)); err != nil { + t.Fatalf("binary.Write(audio format) error = %v", err) + } + if err := binary.Write(&buf, binary.LittleEndian, uint16(numChannels)); err != nil { + t.Fatalf("binary.Write(channels) error = %v", err) + } + if err := binary.Write(&buf, binary.LittleEndian, uint32(sampleRate)); err != nil { + t.Fatalf("binary.Write(sample rate) error = %v", err) + } + if err := binary.Write(&buf, binary.LittleEndian, byteRate); err != nil { + t.Fatalf("binary.Write(byte rate) error = %v", err) + } + if err := binary.Write(&buf, binary.LittleEndian, blockAlign); err != nil { + t.Fatalf("binary.Write(block align) error = %v", err) + } + if err := binary.Write(&buf, binary.LittleEndian, uint16(bitsPerSample)); err != nil { + t.Fatalf("binary.Write(bits per sample) error = %v", err) + } + buf.WriteString("data") + if err := binary.Write(&buf, binary.LittleEndian, dataSize); err != nil { + t.Fatalf("binary.Write(data size) error = %v", err) + } + buf.Write(make([]byte, dataSize)) + + return writeTempFile(t, dir, name, buf.Bytes()) +} diff --git a/pkg/channels/weixin/api.go b/pkg/channels/weixin/api.go new file mode 100644 index 00000000..7f9b3b5c --- /dev/null +++ b/pkg/channels/weixin/api.go @@ -0,0 +1,241 @@ +package weixin + +import ( + "bytes" + "context" + "crypto/rand" + "encoding/base64" + "encoding/binary" + "encoding/json" + "fmt" + "io" + "net/http" + "net/url" + "path" +) + +type ApiClient struct { + BaseURL string + Token string + HttpClient *http.Client +} + +func NewApiClient(baseURL, token string, proxy string) (*ApiClient, error) { + if baseURL == "" { + baseURL = "https://ilinkai.weixin.qq.com/" + } + + client := &http.Client{ + // Default timeout; will be overridden per context + } + + if proxy != "" { + proxyURL, err := url.Parse(proxy) + if err != nil { + return nil, fmt.Errorf("invalid proxy URL %q: %w", proxy, err) + } + + // Clone the default transport so we preserve all default settings (TLS, HTTP/2, timeouts, keep-alives) + if defaultTransport, ok := http.DefaultTransport.(*http.Transport); ok { + transport := defaultTransport.Clone() + transport.Proxy = http.ProxyURL(proxyURL) + client.Transport = transport + } else { + // Fallback: preserve previous behavior if DefaultTransport is not the expected type + client.Transport = &http.Transport{ + Proxy: http.ProxyURL(proxyURL), + } + } + } + + return &ApiClient{ + BaseURL: baseURL, + Token: token, + HttpClient: client, + }, nil +} + +func randomWechatUIN() string { + var b [4]byte + _, _ = rand.Read(b[:]) + uint32Val := binary.BigEndian.Uint32(b[:]) + return base64.StdEncoding.EncodeToString([]byte(fmt.Sprintf("%d", uint32Val))) +} + +func (c *ApiClient) post(ctx context.Context, endpoint string, body any, responseObj any) error { + u, err := url.Parse(c.BaseURL) + if err != nil { + return err + } + u.Path = path.Join(u.Path, endpoint) + + jsonData, err := json.Marshal(body) + if err != nil { + return fmt.Errorf("failed to marshal request body: %w", err) + } + + req, err := http.NewRequestWithContext(ctx, "POST", u.String(), bytes.NewBuffer(jsonData)) + if err != nil { + return fmt.Errorf("failed to create request: %w", err) + } + + req.Header.Set("Content-Type", "application/json") + if endpoint == "ilink/bot/get_bot_qrcode" || endpoint == "ilink/bot/get_qrcode_status" { + // QR routes have different headers sometimes, but let's stick to base ones + if endpoint == "ilink/bot/get_qrcode_status" { + // Use direct map assignment to send exact header name the Tencent API expects + req.Header["iLink-App-ClientVersion"] = []string{"1"} + } + } else { + req.Header["AuthorizationType"] = []string{"ilink_bot_token"} + req.Header["X-WECHAT-UIN"] = []string{randomWechatUIN()} + if c.Token != "" { + req.Header.Set("Authorization", "Bearer "+c.Token) + } + } + + resp, err := c.HttpClient.Do(req) + if err != nil { + return fmt.Errorf("http POST %s failed: %w", endpoint, err) + } + defer resp.Body.Close() + + respBody, err := io.ReadAll(resp.Body) + if err != nil { + return fmt.Errorf("failed to read response body: %w", err) + } + + if resp.StatusCode < 200 || resp.StatusCode >= 300 { + return fmt.Errorf("http %d %s: %s", resp.StatusCode, resp.Status, string(respBody)) + } + + if responseObj != nil { + if err := json.Unmarshal(respBody, responseObj); err != nil { + return fmt.Errorf("failed to unmarshal response: %w, body: %s", err, string(respBody)) + } + } + + return nil +} + +func (c *ApiClient) GetUpdates(ctx context.Context, req GetUpdatesReq) (*GetUpdatesResp, error) { + req.BaseInfo = BaseInfo{ChannelVersion: "1.0.2"} + var resp GetUpdatesResp + err := c.post(ctx, "ilink/bot/getupdates", req, &resp) + if err != nil { + return nil, err + } + return &resp, nil +} + +func (c *ApiClient) SendMessage(ctx context.Context, req SendMessageReq) (*SendMessageResp, error) { + req.BaseInfo = BaseInfo{ChannelVersion: "1.0.2"} + var resp SendMessageResp + if err := c.post(ctx, "ilink/bot/sendmessage", req, &resp); err != nil { + return nil, err + } + return &resp, nil +} + +func (c *ApiClient) GetUploadUrl(ctx context.Context, req GetUploadUrlReq) (*GetUploadUrlResp, error) { + req.BaseInfo = BaseInfo{ChannelVersion: "1.0.2"} + var resp GetUploadUrlResp + err := c.post(ctx, "ilink/bot/getuploadurl", req, &resp) + if err != nil { + return nil, err + } + return &resp, nil +} + +func (c *ApiClient) GetConfig(ctx context.Context, req GetConfigReq) (*GetConfigResp, error) { + req.BaseInfo = BaseInfo{ChannelVersion: "1.0.2"} + var resp GetConfigResp + if err := c.post(ctx, "ilink/bot/getconfig", req, &resp); err != nil { + return nil, err + } + return &resp, nil +} + +func (c *ApiClient) SendTyping(ctx context.Context, req SendTypingReq) (*SendTypingResp, error) { + req.BaseInfo = BaseInfo{ChannelVersion: "1.0.2"} + var resp SendTypingResp + if err := c.post(ctx, "ilink/bot/sendtyping", req, &resp); err != nil { + return nil, err + } + return &resp, nil +} + +func (c *ApiClient) GetQRCode(ctx context.Context, botType string) (*QRCodeResponse, error) { + // get_bot_qrcode is GET, not POST + u, err := url.Parse(c.BaseURL) + if err != nil { + return nil, err + } + u.Path = path.Join(u.Path, "ilink/bot/get_bot_qrcode") + q := u.Query() + q.Set("bot_type", botType) + u.RawQuery = q.Encode() + + req, err := http.NewRequestWithContext(ctx, "GET", u.String(), nil) + if err != nil { + return nil, err + } + + resp, err := c.HttpClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + + respBody, err := io.ReadAll(resp.Body) + if err != nil { + return nil, err + } + if resp.StatusCode != http.StatusOK { + return nil, fmt.Errorf("get_bot_qrcode failed: %d %s", resp.StatusCode, string(respBody)) + } + + var qrcodeResp QRCodeResponse + if err := json.Unmarshal(respBody, &qrcodeResp); err != nil { + return nil, err + } + return &qrcodeResp, nil +} + +func (c *ApiClient) GetQRCodeStatus(ctx context.Context, qrcode string) (*StatusResponse, error) { + // get_qrcode_status is GET + u, err := url.Parse(c.BaseURL) + if err != nil { + return nil, err + } + u.Path = path.Join(u.Path, "ilink/bot/get_qrcode_status") + q := u.Query() + q.Set("qrcode", qrcode) + u.RawQuery = q.Encode() + + req, err := http.NewRequestWithContext(ctx, "GET", u.String(), nil) + if err != nil { + return nil, err + } + req.Header["iLink-App-ClientVersion"] = []string{"1"} + + resp, err := c.HttpClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + + respBody, err := io.ReadAll(resp.Body) + if err != nil { + return nil, err + } + if resp.StatusCode != http.StatusOK { + return nil, fmt.Errorf("get_qrcode_status failed: %d %s", resp.StatusCode, string(respBody)) + } + + var statusResp StatusResponse + if err := json.Unmarshal(respBody, &statusResp); err != nil { + return nil, err + } + return &statusResp, nil +} diff --git a/pkg/channels/weixin/auth.go b/pkg/channels/weixin/auth.go new file mode 100644 index 00000000..52ec2a6d --- /dev/null +++ b/pkg/channels/weixin/auth.go @@ -0,0 +1,111 @@ +package weixin + +import ( + "context" + "fmt" + "os" + "time" + + "github.com/mdp/qrterminal/v3" + + "github.com/sipeed/picoclaw/pkg/logger" +) + +// AuthFlowOpts configures the interactive QR login flow. +type AuthFlowOpts struct { + BaseURL string + BotType string + Timeout time.Duration + Proxy string +} + +// PerformLoginInteractive starts the Weixin QR login flow and blocks until login is successful or times out. +// It prints a QR code to the terminal for the user to scan. +// Returns the BotToken, UserID, AccountID, and BaseUrl on success. +func PerformLoginInteractive( + ctx context.Context, + opts AuthFlowOpts, +) (botToken, userID, accountID, baseUrl string, err error) { + if opts.BaseURL == "" { + opts.BaseURL = "https://ilinkai.weixin.qq.com/" + } + if opts.BotType == "" { + opts.BotType = "3" // Default iLink Bot Type + } + if opts.Timeout == 0 { + opts.Timeout = 5 * time.Minute + } + + api, err := NewApiClient(opts.BaseURL, "", opts.Proxy) + if err != nil { + return "", "", "", "", fmt.Errorf("failed to create api client: %w", err) + } + + logger.InfoC("weixin", "Requesting Weixin QR code...") + qrResp, err := api.GetQRCode(ctx, opts.BotType) + if err != nil { + return "", "", "", "", fmt.Errorf("failed to get qrcode: %w", err) + } + + fmt.Println("\n=======================================================") + fmt.Println("Please scan the following QR code with WeChat to login:") + fmt.Println("=======================================================") + fmt.Println() + + // Create Small QR + qrconfig := qrterminal.Config{ + Level: qrterminal.L, + Writer: os.Stdout, + HalfBlocks: true, + } + qrterminal.GenerateWithConfig(qrResp.QrcodeImgContent, qrconfig) + + fmt.Printf("\nQR Code Link: %s\n\n", qrResp.QrcodeImgContent) + fmt.Println("Waiting for scan...") + + timeoutCtx, cancel := context.WithTimeout(ctx, opts.Timeout) + defer cancel() + + pollTicker := time.NewTicker(2 * time.Second) + defer pollTicker.Stop() + + scannedPrinted := false + + for { + select { + case <-timeoutCtx.Done(): + return "", "", "", "", fmt.Errorf("login timeout") + case <-pollTicker.C: + statusResp, err := api.GetQRCodeStatus(timeoutCtx, qrResp.Qrcode) + if err != nil { + // Long poll timeout or temporary error + continue + } + + switch statusResp.Status { + case "wait": + // still waiting + case "scaned": + if !scannedPrinted { + fmt.Println("👀 QR Code scanned! Please confirm login on your WeChat app...") + scannedPrinted = true + } + case "confirmed": + if statusResp.BotToken == "" || statusResp.IlinkBotID == "" { + return "", "", "", "", fmt.Errorf("login confirmed but missing bot_token or ilink_bot_id") + } + logger.InfoCF("weixin", "Login successful", map[string]any{ + "account_id": statusResp.IlinkBotID, + }) + + return statusResp.BotToken, statusResp.IlinkUserID, statusResp.IlinkBotID, statusResp.Baseurl, nil + case "expired": + return "", "", "", "", fmt.Errorf("qrcode expired, please try again") + default: + logger.WarnCF("weixin", "Unknown QR code status", map[string]any{ + "status": statusResp.Status, + }) + } + } + } +} diff --git a/pkg/channels/weixin/media.go b/pkg/channels/weixin/media.go new file mode 100644 index 00000000..0332f48f --- /dev/null +++ b/pkg/channels/weixin/media.go @@ -0,0 +1,1037 @@ +package weixin + +import ( + "bytes" + "context" + "crypto/aes" + "crypto/md5" + "crypto/rand" + "encoding/base64" + "encoding/hex" + "fmt" + "io" + "mime" + "net/http" + "net/url" + "os" + "os/exec" + "path" + "path/filepath" + "strings" + "sync" + "time" + + "github.com/google/uuid" + "github.com/h2non/filetype" + + "github.com/sipeed/picoclaw/pkg/bus" + basechannels "github.com/sipeed/picoclaw/pkg/channels" + "github.com/sipeed/picoclaw/pkg/logger" + "github.com/sipeed/picoclaw/pkg/media" +) + +const ( + weixinMediaMaxBytes = 100 << 20 + weixinTypingKeepAlive = 5 * time.Second + weixinUploadRetryMax = 3 + weixinVoiceTranscodeTimeout = 15 * time.Second +) + +type uploadedFileInfo struct { + downloadParam string + aesKeyHex string + fileSize int64 + cipherSize int64 + filename string +} + +func pkcs7Pad(src []byte, blockSize int) []byte { + padding := blockSize - len(src)%blockSize + if padding == 0 { + padding = blockSize + } + out := make([]byte, len(src)+padding) + copy(out, src) + for i := len(src); i < len(out); i++ { + out[i] = byte(padding) + } + return out +} + +func pkcs7Unpad(src []byte, blockSize int) ([]byte, error) { + if len(src) == 0 || len(src)%blockSize != 0 { + return nil, fmt.Errorf("invalid padded data size %d", len(src)) + } + padding := int(src[len(src)-1]) + if padding <= 0 || padding > blockSize || padding > len(src) { + return nil, fmt.Errorf("invalid padding size %d", padding) + } + for i := len(src) - padding; i < len(src); i++ { + if src[i] != byte(padding) { + return nil, fmt.Errorf("invalid padding content") + } + } + return src[:len(src)-padding], nil +} + +func encryptAESECB(plaintext, key []byte) ([]byte, error) { + block, err := aes.NewCipher(key) + if err != nil { + return nil, err + } + padded := pkcs7Pad(plaintext, block.BlockSize()) + out := make([]byte, len(padded)) + for i := 0; i < len(padded); i += block.BlockSize() { + block.Encrypt(out[i:i+block.BlockSize()], padded[i:i+block.BlockSize()]) + } + return out, nil +} + +func decryptAESECB(ciphertext, key []byte) ([]byte, error) { + block, err := aes.NewCipher(key) + if err != nil { + return nil, err + } + if len(ciphertext)%block.BlockSize() != 0 { + return nil, fmt.Errorf("invalid ciphertext size %d", len(ciphertext)) + } + out := make([]byte, len(ciphertext)) + for i := 0; i < len(ciphertext); i += block.BlockSize() { + block.Decrypt(out[i:i+block.BlockSize()], ciphertext[i:i+block.BlockSize()]) + } + return pkcs7Unpad(out, block.BlockSize()) +} + +func parseWeixinMediaAESKey(aesKeyBase64 string) ([]byte, error) { + decoded, err := base64.StdEncoding.DecodeString(aesKeyBase64) + if err != nil { + return nil, err + } + if len(decoded) == 16 { + return decoded, nil + } + if len(decoded) == 32 { + if raw, err := hex.DecodeString(string(decoded)); err == nil && len(raw) == 16 { + return raw, nil + } + } + return nil, fmt.Errorf("unsupported aes_key length %d", len(decoded)) +} + +func imageAESKey(img *ImageItem) ([]byte, bool, error) { + if img == nil { + return nil, false, nil + } + if img.Aeskey != "" { + raw, err := hex.DecodeString(img.Aeskey) + if err != nil { + return nil, false, err + } + return raw, true, nil + } + if img.Media != nil && img.Media.AesKey != "" { + raw, err := parseWeixinMediaAESKey(img.Media.AesKey) + if err != nil { + return nil, false, err + } + return raw, true, nil + } + return nil, false, nil +} + +func genericMediaAESKey(mediaRef *CDNMedia) ([]byte, error) { + if mediaRef == nil || mediaRef.AesKey == "" { + return nil, fmt.Errorf("missing aes_key") + } + return parseWeixinMediaAESKey(mediaRef.AesKey) +} + +func aesEcbPaddedSize(size int64) int64 { + return (size/16 + 1) * 16 +} + +func randomHex(n int) (string, error) { + buf := make([]byte, n) + if _, err := rand.Read(buf); err != nil { + return "", err + } + return hex.EncodeToString(buf), nil +} + +func buildCDNDownloadURL(base, encryptedQueryParam string) string { + return strings.TrimRight(base, "/") + + "/download?encrypted_query_param=" + url.QueryEscape(encryptedQueryParam) +} + +func buildCDNUploadURL(base, uploadParam, filekey string) string { + return strings.TrimRight(base, "/") + + "/upload?encrypted_query_param=" + url.QueryEscape(uploadParam) + + "&filekey=" + url.QueryEscape(filekey) +} + +func (c *WeixinChannel) downloadCDNBuffer(ctx context.Context, encryptedQueryParam string) ([]byte, error) { + req, err := http.NewRequestWithContext( + ctx, + http.MethodGet, + buildCDNDownloadURL(c.cdnBaseURL(), encryptedQueryParam), + nil, + ) + if err != nil { + return nil, err + } + resp, err := c.api.HttpClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + + if resp.StatusCode < 200 || resp.StatusCode >= 300 { + body, _ := io.ReadAll(io.LimitReader(resp.Body, 1024)) + return nil, fmt.Errorf("cdn download HTTP %d: %s", resp.StatusCode, string(body)) + } + + data, err := io.ReadAll(io.LimitReader(resp.Body, weixinMediaMaxBytes+1)) + if err != nil { + return nil, err + } + if len(data) > weixinMediaMaxBytes { + return nil, fmt.Errorf("cdn media too large: %d bytes", len(data)) + } + return data, nil +} + +func (c *WeixinChannel) downloadAndDecryptCDNBuffer( + ctx context.Context, + encryptedQueryParam string, + key []byte, +) ([]byte, error) { + data, err := c.downloadCDNBuffer(ctx, encryptedQueryParam) + if err != nil { + return nil, err + } + if len(key) == 0 { + return data, nil + } + return decryptAESECB(data, key) +} + +func detectMediaMetadata(data []byte, fallbackName, fallbackContentType string) (string, string) { + contentType := strings.TrimSpace(fallbackContentType) + ext := filepath.Ext(fallbackName) + if kind, err := filetype.Match(data); err == nil && kind != filetype.Unknown { + contentType = kind.MIME.Value + if kind.Extension != "" { + ext = "." + kind.Extension + } + } + if contentType == "" && ext != "" { + contentType = mime.TypeByExtension(strings.ToLower(ext)) + } + if contentType == "" { + contentType = http.DetectContentType(data) + } + if ext == "" && contentType != "" { + if exts, err := mime.ExtensionsByType(contentType); err == nil && len(exts) > 0 { + ext = exts[0] + } + } + + filename := sanitizeFilename(fallbackName) + if filename == "" { + filename = "media" + } + if filepath.Ext(filename) == "" && ext != "" { + filename += ext + } + return filename, contentType +} + +func sanitizeFilename(name string) string { + name = filepath.Base(strings.TrimSpace(name)) + if name == "." || name == "/" || name == "" { + return "" + } + return name +} + +func writeManagedTempFile(prefix, filename string, data []byte) (string, error) { + if err := os.MkdirAll(media.TempDir(), 0o700); err != nil { + return "", err + } + pattern := prefix + "-*" + if ext := filepath.Ext(filename); ext != "" { + pattern += ext + } + f, err := os.CreateTemp(media.TempDir(), pattern) + if err != nil { + return "", err + } + defer f.Close() + if _, err := f.Write(data); err != nil { + os.Remove(f.Name()) + return "", err + } + return f.Name(), nil +} + +func (c *WeixinChannel) storeInboundBytes( + chatID, + messageID, + filename, + contentType string, + data []byte, +) (string, error) { + store := c.GetMediaStore() + if store == nil { + return "", fmt.Errorf("no media store available") + } + filename, contentType = detectMediaMetadata(data, filename, contentType) + tmpPath, err := writeManagedTempFile("weixin-inbound", filename, data) + if err != nil { + return "", err + } + ref, err := store.Store(tmpPath, media.MediaMeta{ + Filename: filename, + ContentType: contentType, + Source: "weixin", + }, basechannels.BuildMediaScope("weixin", chatID, messageID)) + if err != nil { + os.Remove(tmpPath) + return "", err + } + return ref, nil +} + +func isDownloadableMediaItem(item *MessageItem) bool { + if item == nil { + return false + } + + switch item.Type { + case MessageItemTypeImage: + return item.ImageItem != nil && item.ImageItem.Media != nil && item.ImageItem.Media.EncryptQueryParam != "" + case MessageItemTypeVideo: + return item.VideoItem != nil && item.VideoItem.Media != nil && item.VideoItem.Media.EncryptQueryParam != "" + case MessageItemTypeFile: + return item.FileItem != nil && item.FileItem.Media != nil && item.FileItem.Media.EncryptQueryParam != "" + case MessageItemTypeVoice: + return item.VoiceItem != nil && + item.VoiceItem.Media != nil && + item.VoiceItem.Media.EncryptQueryParam != "" && + strings.TrimSpace(item.VoiceItem.Text) == "" + default: + return false + } +} + +func selectInboundMediaItem(msg WeixinMessage) *MessageItem { + priorities := []int{ + MessageItemTypeImage, + MessageItemTypeVideo, + MessageItemTypeFile, + MessageItemTypeVoice, + } + + for _, want := range priorities { + for i := range msg.ItemList { + item := &msg.ItemList[i] + if item.Type == want && isDownloadableMediaItem(item) { + return item + } + } + } + + for i := range msg.ItemList { + item := &msg.ItemList[i] + if item.Type != MessageItemTypeText || item.RefMsg == nil || item.RefMsg.MessageItem == nil { + continue + } + if isDownloadableMediaItem(item.RefMsg.MessageItem) { + return item.RefMsg.MessageItem + } + } + + return nil +} + +func tryTranscodeSilkToWAV(ctx context.Context, silk []byte) ([]byte, error) { + decoders := []struct { + name string + args func(inputPath, outputPath string) []string + }{ + { + name: "silk_v3_decoder", + args: func(inputPath, outputPath string) []string { return []string{inputPath, outputPath, "24000"} }, + }, + { + name: "silk_decoder", + args: func(inputPath, outputPath string) []string { return []string{inputPath, outputPath, "24000"} }, + }, + { + name: "ffmpeg", + args: func(inputPath, outputPath string) []string { + return []string{"-y", "-i", inputPath, outputPath} + }, + }, + } + + for _, decoder := range decoders { + bin, err := exec.LookPath(decoder.name) + if err != nil { + continue + } + + tmpIn, err := writeManagedTempFile("weixin-voice", "voice.silk", silk) + if err != nil { + return nil, err + } + tmpOut := filepath.Join(media.TempDir(), "weixin-voice-"+uuid.New().String()+".wav") + wav, ok := func() ([]byte, bool) { + defer os.Remove(tmpIn) + defer os.Remove(tmpOut) + + runCtx, cancel := context.WithTimeout(ctx, weixinVoiceTranscodeTimeout) + cmd := exec.CommandContext(runCtx, bin, decoder.args(tmpIn, tmpOut)...) + out, runErr := cmd.CombinedOutput() + cancel() + if runErr != nil { + logger.DebugCF("weixin", "SILK transcode command failed", map[string]any{ + "decoder": decoder.name, + "error": runErr.Error(), + "output": strings.TrimSpace(string(out)), + }) + return nil, false + } + + wav, readErr := os.ReadFile(tmpOut) + if readErr != nil { + logger.DebugCF("weixin", "Failed to read transcoded WAV", map[string]any{ + "decoder": decoder.name, + "error": readErr.Error(), + }) + return nil, false + } + return wav, len(wav) > 0 + }() + if ok { + return wav, nil + } + } + + return nil, fmt.Errorf("no SILK decoder available") +} + +func (c *WeixinChannel) downloadMediaFromItem( + ctx context.Context, + chatID, + messageID string, + item *MessageItem, +) (string, error) { + if item == nil { + return "", nil + } + + switch item.Type { + case MessageItemTypeImage: + key, ok, err := imageAESKey(item.ImageItem) + if err != nil { + return "", err + } + data, err := c.downloadAndDecryptCDNBuffer(ctx, item.ImageItem.Media.EncryptQueryParam, func() []byte { + if ok { + return key + } + return nil + }()) + if err != nil { + return "", err + } + return c.storeInboundBytes(chatID, messageID, "image", "", data) + + case MessageItemTypeVoice: + key, err := genericMediaAESKey(item.VoiceItem.Media) + if err != nil { + return "", err + } + silk, err := c.downloadAndDecryptCDNBuffer(ctx, item.VoiceItem.Media.EncryptQueryParam, key) + if err != nil { + return "", err + } + if wav, err := tryTranscodeSilkToWAV(ctx, silk); err == nil && len(wav) > 0 { + return c.storeInboundBytes(chatID, messageID, "voice.wav", "audio/wav", wav) + } + return c.storeInboundBytes(chatID, messageID, "voice.silk", "audio/silk", silk) + + case MessageItemTypeFile: + key, err := genericMediaAESKey(item.FileItem.Media) + if err != nil { + return "", err + } + data, err := c.downloadAndDecryptCDNBuffer(ctx, item.FileItem.Media.EncryptQueryParam, key) + if err != nil { + return "", err + } + filename := item.FileItem.FileName + if filename == "" { + filename = "file.bin" + } + contentType := mime.TypeByExtension(strings.ToLower(filepath.Ext(filename))) + return c.storeInboundBytes(chatID, messageID, filename, contentType, data) + + case MessageItemTypeVideo: + key, err := genericMediaAESKey(item.VideoItem.Media) + if err != nil { + return "", err + } + data, err := c.downloadAndDecryptCDNBuffer(ctx, item.VideoItem.Media.EncryptQueryParam, key) + if err != nil { + return "", err + } + return c.storeInboundBytes(chatID, messageID, "video.mp4", "video/mp4", data) + } + + return "", nil +} + +func outboundMediaKind(partType, filename, contentType string) int { + switch strings.ToLower(strings.TrimSpace(partType)) { + case "image": + return UploadMediaTypeImage + case "video": + return UploadMediaTypeVideo + } + + ct := strings.ToLower(contentType) + switch { + case strings.HasPrefix(ct, "image/"): + return UploadMediaTypeImage + case strings.HasPrefix(ct, "video/"): + return UploadMediaTypeVideo + default: + return UploadMediaTypeFile + } +} + +func detectLocalContentType(localPath, hintContentType string) string { + if strings.TrimSpace(hintContentType) != "" { + return hintContentType + } + if kind, err := filetype.MatchFile(localPath); err == nil && kind != filetype.Unknown { + return kind.MIME.Value + } + if ext := filepath.Ext(localPath); ext != "" { + if ct := mime.TypeByExtension(strings.ToLower(ext)); ct != "" { + return ct + } + } + return "application/octet-stream" +} + +func downloadFilenameFromURL(rawURL, fallback string) string { + if fallback = sanitizeFilename(fallback); fallback != "" { + return fallback + } + parsed, err := url.Parse(rawURL) + if err == nil { + if base := sanitizeFilename(path.Base(parsed.Path)); base != "" { + return base + } + } + return "remote-media" +} + +func (c *WeixinChannel) downloadRemoteMediaToTemp( + ctx context.Context, + rawURL, + fallbackName string, +) (string, string, string, error) { + req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil) + if err != nil { + return "", "", "", err + } + resp, err := c.api.HttpClient.Do(req) + if err != nil { + return "", "", "", err + } + defer resp.Body.Close() + + if resp.StatusCode < 200 || resp.StatusCode >= 300 { + body, _ := io.ReadAll(io.LimitReader(resp.Body, 1024)) + return "", "", "", fmt.Errorf("remote media HTTP %d: %s", resp.StatusCode, string(body)) + } + + data, err := io.ReadAll(io.LimitReader(resp.Body, weixinMediaMaxBytes+1)) + if err != nil { + return "", "", "", err + } + if len(data) > weixinMediaMaxBytes { + return "", "", "", fmt.Errorf("remote media too large: %d bytes", len(data)) + } + + filename, contentType := detectMediaMetadata( + data, + downloadFilenameFromURL(rawURL, fallbackName), + resp.Header.Get("Content-Type"), + ) + tmpPath, err := writeManagedTempFile("weixin-remote", filename, data) + if err != nil { + return "", "", "", err + } + return tmpPath, filename, contentType, nil +} + +func (c *WeixinChannel) resolveOutboundPart( + ctx context.Context, + part bus.MediaPart, +) (string, string, string, func(), error) { + cleanup := func() {} + filename := sanitizeFilename(part.Filename) + contentType := strings.TrimSpace(part.ContentType) + + switch { + case strings.HasPrefix(part.Ref, "http://") || strings.HasPrefix(part.Ref, "https://"): + localPath, name, ct, err := c.downloadRemoteMediaToTemp(ctx, part.Ref, filename) + if err != nil { + return "", "", "", cleanup, err + } + return localPath, name, ct, func() { os.Remove(localPath) }, nil + + case strings.HasPrefix(part.Ref, "media://"): + store := c.GetMediaStore() + if store == nil { + return "", "", "", cleanup, fmt.Errorf("no media store available") + } + localPath, meta, err := store.ResolveWithMeta(part.Ref) + if err != nil { + return "", "", "", cleanup, err + } + if filename == "" { + filename = sanitizeFilename(meta.Filename) + } + if contentType == "" { + contentType = meta.ContentType + } + if strings.HasPrefix(localPath, "http://") || strings.HasPrefix(localPath, "https://") { + tmpPath, name, ct, err := c.downloadRemoteMediaToTemp(ctx, localPath, filename) + if err != nil { + return "", "", "", cleanup, err + } + return tmpPath, name, ct, func() { os.Remove(tmpPath) }, nil + } + if filename == "" { + filename = sanitizeFilename(filepath.Base(localPath)) + } + if contentType == "" { + contentType = detectLocalContentType(localPath, "") + } + return localPath, filename, contentType, cleanup, nil + + case strings.HasPrefix(part.Ref, "file://"): + u, err := url.Parse(part.Ref) + if err != nil { + return "", "", "", cleanup, err + } + localPath := u.Path + if filename == "" { + filename = sanitizeFilename(filepath.Base(localPath)) + } + if contentType == "" { + contentType = detectLocalContentType(localPath, "") + } + return localPath, filename, contentType, cleanup, nil + + default: + localPath := part.Ref + if filename == "" { + filename = sanitizeFilename(filepath.Base(localPath)) + } + if contentType == "" { + contentType = detectLocalContentType(localPath, "") + } + return localPath, filename, contentType, cleanup, nil + } +} + +func (c *WeixinChannel) uploadLocalFile( + ctx context.Context, + localPath, + filename, + toUserID string, + mediaType int, +) (*uploadedFileInfo, error) { + data, err := os.ReadFile(localPath) + if err != nil { + return nil, err + } + if len(data) > weixinMediaMaxBytes { + return nil, fmt.Errorf("media too large: %d bytes", len(data)) + } + + filekey, err := randomHex(16) + if err != nil { + return nil, err + } + aesKey := make([]byte, 16) + if _, readErr := rand.Read(aesKey); readErr != nil { + return nil, readErr + } + aesKeyHex := hex.EncodeToString(aesKey) + rawMD5 := md5.Sum(data) + + resp, err := c.api.GetUploadUrl(ctx, GetUploadUrlReq{ + Filekey: filekey, + MediaType: mediaType, + ToUserID: toUserID, + Rawsize: int64(len(data)), + RawfileMD5: hex.EncodeToString(rawMD5[:]), + Filesize: aesEcbPaddedSize(int64(len(data))), + NoNeedThumb: true, + Aeskey: aesKeyHex, + }) + if err != nil { + return nil, err + } + if resp == nil { + return nil, fmt.Errorf("getuploadurl returned nil response") + } + if resp.Ret != 0 || resp.Errcode != 0 { + if isSessionExpiredStatus(resp.Ret, resp.Errcode) { + c.pauseSession("getuploadurl", resp.Ret, resp.Errcode, resp.Errmsg) + } + return nil, fmt.Errorf("getuploadurl failed: ret=%d errcode=%d errmsg=%s", resp.Ret, resp.Errcode, resp.Errmsg) + } + if strings.TrimSpace(resp.UploadParam) == "" { + return nil, fmt.Errorf("getuploadurl returned empty upload_param") + } + + downloadParam, err := c.uploadBufferToCDN(ctx, data, resp.UploadParam, filekey, aesKey) + if err != nil { + return nil, err + } + + return &uploadedFileInfo{ + downloadParam: downloadParam, + aesKeyHex: aesKeyHex, + fileSize: int64(len(data)), + cipherSize: aesEcbPaddedSize(int64(len(data))), + filename: filename, + }, nil +} + +func (c *WeixinChannel) uploadBufferToCDN( + ctx context.Context, + plaintext []byte, + uploadParam, + filekey string, + aesKey []byte, +) (string, error) { + ciphertext, err := encryptAESECB(plaintext, aesKey) + if err != nil { + return "", err + } + + uploadURL := buildCDNUploadURL(c.cdnBaseURL(), uploadParam, filekey) + var lastErr error + + for attempt := 1; attempt <= weixinUploadRetryMax; attempt++ { + req, reqErr := http.NewRequestWithContext(ctx, http.MethodPost, uploadURL, bytes.NewReader(ciphertext)) + if reqErr != nil { + return "", reqErr + } + req.Header.Set("Content-Type", "application/octet-stream") + + resp, doErr := c.api.HttpClient.Do(req) + if doErr != nil { + lastErr = doErr + } else { + func() { + defer resp.Body.Close() + if resp.StatusCode >= 400 && resp.StatusCode < 500 { + body, _ := io.ReadAll(io.LimitReader(resp.Body, 1024)) + lastErr = fmt.Errorf( + "cdn upload client error %d: %s", + resp.StatusCode, + strings.TrimSpace(string(body)), + ) + return + } + if resp.StatusCode != http.StatusOK { + body, _ := io.ReadAll(io.LimitReader(resp.Body, 1024)) + lastErr = fmt.Errorf( + "cdn upload server error %d: %s", + resp.StatusCode, + strings.TrimSpace(string(body)), + ) + return + } + if encrypted := strings.TrimSpace(resp.Header.Get("X-Encrypted-Param")); encrypted != "" { + lastErr = nil + uploadParam = encrypted + return + } + lastErr = fmt.Errorf("cdn upload missing x-encrypted-param header") + }() + } + + if lastErr == nil { + return uploadParam, nil + } + if strings.Contains(lastErr.Error(), "client error") || attempt == weixinUploadRetryMax { + break + } + } + + return "", lastErr +} + +func (c *WeixinChannel) sendMessageItem( + ctx context.Context, + toUserID, + contextToken string, + item MessageItem, +) error { + resp, err := c.api.SendMessage(ctx, SendMessageReq{ + Msg: WeixinMessage{ + ToUserID: toUserID, + ClientID: "picoclaw-" + uuid.New().String(), + MessageType: MessageTypeBot, + MessageState: MessageStateFinish, + ItemList: []MessageItem{item}, + ContextToken: contextToken, + }, + }) + if err != nil { + return err + } + if resp == nil { + return fmt.Errorf("sendmessage returned nil response") + } + if resp.Ret != 0 || resp.Errcode != 0 { + if isSessionExpiredStatus(resp.Ret, resp.Errcode) { + c.pauseSession("sendmessage", resp.Ret, resp.Errcode, resp.Errmsg) + } + return fmt.Errorf("sendmessage failed: ret=%d errcode=%d errmsg=%s", resp.Ret, resp.Errcode, resp.Errmsg) + } + return nil +} + +func (c *WeixinChannel) sendTextMessage( + ctx context.Context, + toUserID, + contextToken, + text string, +) error { + if strings.TrimSpace(text) == "" { + return nil + } + return c.sendMessageItem(ctx, toUserID, contextToken, MessageItem{ + Type: MessageItemTypeText, + TextItem: &TextItem{ + Text: text, + }, + }) +} + +func encodeWeixinOutboundAESKey(aesKeyHex string) string { + return base64.StdEncoding.EncodeToString([]byte(aesKeyHex)) +} + +func (c *WeixinChannel) sendUploadedMedia( + ctx context.Context, + toUserID, + contextToken, + caption string, + mediaType int, + uploaded *uploadedFileInfo, +) error { + if err := c.sendTextMessage(ctx, toUserID, contextToken, caption); err != nil { + return err + } + + mediaRef := &CDNMedia{ + EncryptQueryParam: uploaded.downloadParam, + AesKey: encodeWeixinOutboundAESKey(uploaded.aesKeyHex), + EncryptType: 1, + } + + switch mediaType { + case UploadMediaTypeImage: + return c.sendMessageItem(ctx, toUserID, contextToken, MessageItem{ + Type: MessageItemTypeImage, + ImageItem: &ImageItem{ + Media: mediaRef, + MidSize: uploaded.cipherSize, + }, + }) + + case UploadMediaTypeVideo: + return c.sendMessageItem(ctx, toUserID, contextToken, MessageItem{ + Type: MessageItemTypeVideo, + VideoItem: &VideoItem{ + Media: mediaRef, + VideoSize: uploaded.cipherSize, + }, + }) + + default: + return c.sendMessageItem(ctx, toUserID, contextToken, MessageItem{ + Type: MessageItemTypeFile, + FileItem: &FileItem{ + Media: mediaRef, + FileName: uploaded.filename, + Len: fmt.Sprintf("%d", uploaded.fileSize), + }, + }) + } +} + +func (c *WeixinChannel) sendTypingStatus( + ctx context.Context, + chatID, + typingTicket string, + status int, +) error { + resp, err := c.api.SendTyping(ctx, SendTypingReq{ + IlinkUserID: chatID, + TypingTicket: typingTicket, + Status: status, + }) + if err != nil { + return err + } + if resp == nil { + return fmt.Errorf("sendtyping returned nil response") + } + if resp.Ret != 0 || resp.Errcode != 0 { + if isSessionExpiredStatus(resp.Ret, resp.Errcode) { + c.pauseSession("sendtyping", resp.Ret, resp.Errcode, resp.Errmsg) + } + return fmt.Errorf("sendtyping failed: ret=%d errcode=%d errmsg=%s", resp.Ret, resp.Errcode, resp.Errmsg) + } + return nil +} + +// StartTyping implements channels.TypingCapable. +func (c *WeixinChannel) StartTyping(ctx context.Context, chatID string) (func(), error) { + if strings.TrimSpace(chatID) == "" { + return func() {}, nil + } + if c.remainingPause() > 0 { + return func() {}, nil + } + + ticket, err := c.getTypingTicket(ctx, chatID) + if err != nil { + if ticket == "" { + return func() {}, err + } + logger.DebugCF("weixin", "GetConfig refresh failed; using cached typing ticket", map[string]any{ + "chat_id": chatID, + "error": err.Error(), + }) + } + if ticket == "" { + return func() {}, nil + } + + typingCtx, cancel := context.WithCancel(ctx) + var once sync.Once + stop := func() { + once.Do(func() { + cancel() + stopCtx, stopCancel := context.WithTimeout(context.Background(), 5*time.Second) + defer stopCancel() + if err := c.sendTypingStatus(stopCtx, chatID, ticket, TypingStatusCancel); err != nil { + logger.DebugCF("weixin", "Failed to cancel typing indicator", map[string]any{ + "chat_id": chatID, + "error": err.Error(), + }) + } + }) + } + + if err := c.sendTypingStatus(typingCtx, chatID, ticket, TypingStatusTyping); err != nil { + stop() + return func() {}, err + } + + ticker := time.NewTicker(weixinTypingKeepAlive) + go func() { + defer ticker.Stop() + for { + select { + case <-typingCtx.Done(): + return + case <-ticker.C: + if err := c.sendTypingStatus(typingCtx, chatID, ticket, TypingStatusTyping); err != nil { + logger.DebugCF("weixin", "Failed to refresh typing indicator", map[string]any{ + "chat_id": chatID, + "error": err.Error(), + }) + } + } + } + }() + + return stop, nil +} + +// SendMedia implements channels.MediaSender. +func (c *WeixinChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error { + if !c.IsRunning() { + return basechannels.ErrNotRunning + } + if err := c.ensureSessionActive(); err != nil { + return err + } + + contextToken := "" + if v, ok := c.contextTokens.Load(msg.ChatID); ok { + contextToken, _ = v.(string) + } + if contextToken == "" { + return fmt.Errorf( + "weixin send media: missing context token for chat %s: %w", + msg.ChatID, + basechannels.ErrSendFailed, + ) + } + + for _, part := range msg.Parts { + localPath, filename, contentType, cleanup, err := c.resolveOutboundPart(ctx, part) + if err != nil { + logger.ErrorCF("weixin", "Failed to resolve outbound media", map[string]any{ + "chat_id": msg.ChatID, + "ref": part.Ref, + "error": err.Error(), + }) + return fmt.Errorf("weixin send media: %w", basechannels.ErrSendFailed) + } + func() { + if cleanup != nil { + defer cleanup() + } + + kind := outboundMediaKind(part.Type, filename, contentType) + uploaded, uploadErr := c.uploadLocalFile(ctx, localPath, filename, msg.ChatID, kind) + if uploadErr != nil { + err = uploadErr + return + } + err = c.sendUploadedMedia(ctx, msg.ChatID, contextToken, part.Caption, kind, uploaded) + }() + if err != nil { + logger.ErrorCF("weixin", "Failed to send outbound media", map[string]any{ + "chat_id": msg.ChatID, + "ref": part.Ref, + "error": err.Error(), + }) + if c.remainingPause() > 0 { + return fmt.Errorf("weixin send media: %w", basechannels.ErrSendFailed) + } + return fmt.Errorf("weixin send media: %w", basechannels.ErrTemporary) + } + } + + return nil +} diff --git a/pkg/channels/weixin/state.go b/pkg/channels/weixin/state.go new file mode 100644 index 00000000..02c137b8 --- /dev/null +++ b/pkg/channels/weixin/state.go @@ -0,0 +1,226 @@ +package weixin + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "fmt" + "os" + "path/filepath" + "strings" + "time" + + basechannels "github.com/sipeed/picoclaw/pkg/channels" + "github.com/sipeed/picoclaw/pkg/config" + "github.com/sipeed/picoclaw/pkg/fileutil" + "github.com/sipeed/picoclaw/pkg/logger" +) + +const ( + weixinDefaultCDNBaseURL = "https://novac2c.cdn.weixin.qq.com/c2c" + weixinConfigCacheTTL = 24 * time.Hour + weixinConfigRetryInitial = 2 * time.Second + weixinConfigRetryMax = time.Hour + weixinSessionPauseDuration = time.Hour + weixinSessionExpiredCode = -14 +) + +type typingTicketCacheEntry struct { + ticket string + nextFetchAt time.Time + retryDelay time.Duration +} + +type syncCursorFile struct { + GetUpdatesBuf string `json:"get_updates_buf"` +} + +func picoclawHomeDir() string { + if home := os.Getenv(config.EnvHome); home != "" { + return home + } + userHome, _ := os.UserHomeDir() + return filepath.Join(userHome, ".picoclaw") +} + +func buildWeixinSyncBufPath(cfg config.WeixinConfig) string { + key := "default" + token := strings.TrimSpace(cfg.Token) + if token != "" { + sum := sha256.Sum256([]byte(strings.TrimSpace(cfg.BaseURL) + "|" + token)) + key = hex.EncodeToString(sum[:8]) + } + return filepath.Join(picoclawHomeDir(), "channels", "weixin", "sync", key+".json") +} + +func loadGetUpdatesBuf(path string) (string, error) { + data, err := os.ReadFile(path) + if err != nil { + if os.IsNotExist(err) { + return "", nil + } + return "", err + } + + var decoded syncCursorFile + if err := json.Unmarshal(data, &decoded); err != nil { + return "", err + } + + return decoded.GetUpdatesBuf, nil +} + +func saveGetUpdatesBuf(path, cursor string) error { + data, err := json.Marshal(syncCursorFile{GetUpdatesBuf: cursor}) + if err != nil { + return err + } + return fileutil.WriteFileAtomic(path, data, 0o600) +} + +func (c *WeixinChannel) cdnBaseURL() string { + if base := strings.TrimSpace(c.config.CDNBaseURL); base != "" { + return strings.TrimRight(base, "/") + } + return weixinDefaultCDNBaseURL +} + +func isSessionExpiredStatus(ret, errcode int) bool { + return ret == weixinSessionExpiredCode || errcode == weixinSessionExpiredCode +} + +func (c *WeixinChannel) pauseSession(operation string, ret, errcode int, errmsg string) time.Duration { + c.pauseMu.Lock() + defer c.pauseMu.Unlock() + + until := time.Now().Add(weixinSessionPauseDuration) + if until.After(c.pauseUntil) { + c.pauseUntil = until + } + + remaining := time.Until(c.pauseUntil) + logger.ErrorCF("weixin", "Session expired; pausing Weixin channel", map[string]any{ + "operation": operation, + "ret": ret, + "errcode": errcode, + "errmsg": errmsg, + "until": c.pauseUntil.Format(time.RFC3339), + "minutes": int((remaining + time.Minute - 1) / time.Minute), + }) + return remaining +} + +func (c *WeixinChannel) remainingPause() time.Duration { + c.pauseMu.Lock() + defer c.pauseMu.Unlock() + + if c.pauseUntil.IsZero() { + return 0 + } + remaining := time.Until(c.pauseUntil) + if remaining <= 0 { + c.pauseUntil = time.Time{} + return 0 + } + return remaining +} + +func (c *WeixinChannel) waitWhileSessionPaused(ctx context.Context) error { + remaining := c.remainingPause() + if remaining <= 0 { + return nil + } + + timer := time.NewTimer(remaining) + defer timer.Stop() + + select { + case <-ctx.Done(): + return ctx.Err() + case <-timer.C: + return nil + } +} + +func (c *WeixinChannel) ensureSessionActive() error { + remaining := c.remainingPause() + if remaining <= 0 { + return nil + } + return fmt.Errorf( + "weixin session paused (%d min remaining): %w", + int((remaining+time.Minute-1)/time.Minute), + basechannels.ErrSendFailed, + ) +} + +func (c *WeixinChannel) getTypingTicket(ctx context.Context, userID string) (string, error) { + now := time.Now() + + c.typingMu.Lock() + entry, ok := c.typingCache[userID] + if ok && now.Before(entry.nextFetchAt) { + ticket := entry.ticket + c.typingMu.Unlock() + return ticket, nil + } + cachedTicket := entry.ticket + retryDelay := entry.retryDelay + c.typingMu.Unlock() + + contextToken := "" + if v, ok := c.contextTokens.Load(userID); ok { + contextToken, _ = v.(string) + } + + resp, err := c.api.GetConfig(ctx, GetConfigReq{ + IlinkUserID: userID, + ContextToken: contextToken, + }) + if err == nil && resp != nil && resp.Ret == 0 && resp.Errcode == 0 { + ticket := strings.TrimSpace(resp.TypingTicket) + c.typingMu.Lock() + c.typingCache[userID] = typingTicketCacheEntry{ + ticket: ticket, + nextFetchAt: now.Add(weixinConfigCacheTTL), + retryDelay: weixinConfigRetryInitial, + } + c.typingMu.Unlock() + return ticket, nil + } + + if resp != nil && isSessionExpiredStatus(resp.Ret, resp.Errcode) { + c.pauseSession("getconfig", resp.Ret, resp.Errcode, resp.Errmsg) + } + + if retryDelay <= 0 { + retryDelay = weixinConfigRetryInitial + } else { + retryDelay *= 2 + if retryDelay > weixinConfigRetryMax { + retryDelay = weixinConfigRetryMax + } + } + + c.typingMu.Lock() + c.typingCache[userID] = typingTicketCacheEntry{ + ticket: cachedTicket, + nextFetchAt: now.Add(retryDelay), + retryDelay: retryDelay, + } + c.typingMu.Unlock() + + if err != nil { + return cachedTicket, err + } + if resp == nil { + return cachedTicket, fmt.Errorf("getconfig returned nil response") + } + return cachedTicket, fmt.Errorf( + "getconfig failed: ret=%d errcode=%d errmsg=%s", + resp.Ret, + resp.Errcode, + resp.Errmsg, + ) +} diff --git a/pkg/channels/weixin/types.go b/pkg/channels/weixin/types.go new file mode 100644 index 00000000..74c6e63c --- /dev/null +++ b/pkg/channels/weixin/types.go @@ -0,0 +1,210 @@ +package weixin + +// BaseInfo is attached to every outgoing CGI request +type BaseInfo struct { + ChannelVersion string `json:"channel_version,omitempty"` +} + +type APIStatus struct { + Ret int `json:"ret,omitempty"` + Errcode int `json:"errcode,omitempty"` + Errmsg string `json:"errmsg,omitempty"` +} + +// UploadMediaType constants +const ( + UploadMediaTypeImage = 1 + UploadMediaTypeVideo = 2 + UploadMediaTypeFile = 3 + UploadMediaTypeVoice = 4 +) + +type GetUploadUrlReq struct { + Filekey string `json:"filekey,omitempty"` + MediaType int `json:"media_type,omitempty"` + ToUserID string `json:"to_user_id,omitempty"` + Rawsize int64 `json:"rawsize,omitempty"` + RawfileMD5 string `json:"rawfilemd5,omitempty"` + Filesize int64 `json:"filesize,omitempty"` + ThumbRawsize int64 `json:"thumb_rawsize,omitempty"` + ThumbRawfileMD5 string `json:"thumb_rawfilemd5,omitempty"` + ThumbFilesize int64 `json:"thumb_filesize,omitempty"` + NoNeedThumb bool `json:"no_need_thumb,omitempty"` + Aeskey string `json:"aeskey,omitempty"` // hex-encoded 16-byte AES key + BaseInfo BaseInfo `json:"base_info,omitempty"` +} + +type GetUploadUrlResp struct { + APIStatus + UploadParam string `json:"upload_param,omitempty"` + ThumbUploadParam string `json:"thumb_upload_param,omitempty"` +} + +const ( + MessageTypeNone = 0 + MessageTypeUser = 1 + MessageTypeBot = 2 +) + +const ( + MessageItemTypeNone = 0 + MessageItemTypeText = 1 + MessageItemTypeImage = 2 + MessageItemTypeVoice = 3 + MessageItemTypeFile = 4 + MessageItemTypeVideo = 5 +) + +const ( + MessageStateNew = 0 + MessageStateGenerating = 1 + MessageStateFinish = 2 +) + +type TextItem struct { + Text string `json:"text,omitempty"` +} + +type CDNMedia struct { + EncryptQueryParam string `json:"encrypt_query_param,omitempty"` + AesKey string `json:"aes_key,omitempty"` // base64 encoded + EncryptType int `json:"encrypt_type,omitempty"` +} + +type ImageItem struct { + Media *CDNMedia `json:"media,omitempty"` + ThumbMedia *CDNMedia `json:"thumb_media,omitempty"` + Aeskey string `json:"aeskey,omitempty"` + Url string `json:"url,omitempty"` + MidSize int64 `json:"mid_size,omitempty"` + ThumbSize int64 `json:"thumb_size,omitempty"` + ThumbHeight int `json:"thumb_height,omitempty"` + ThumbWidth int `json:"thumb_width,omitempty"` + HDSize int64 `json:"hd_size,omitempty"` +} + +type VoiceItem struct { + Media *CDNMedia `json:"media,omitempty"` + EncodeType int `json:"encode_type,omitempty"` + BitsPerSample int `json:"bits_per_sample,omitempty"` + SampleRate int `json:"sample_rate,omitempty"` + Playtime int `json:"playtime,omitempty"` + Text string `json:"text,omitempty"` +} + +type FileItem struct { + Media *CDNMedia `json:"media,omitempty"` + FileName string `json:"file_name,omitempty"` + MD5 string `json:"md5,omitempty"` + Len string `json:"len,omitempty"` +} + +type VideoItem struct { + Media *CDNMedia `json:"media,omitempty"` + VideoSize int64 `json:"video_size,omitempty"` + PlayLength int `json:"play_length,omitempty"` + VideoMD5 string `json:"video_md5,omitempty"` + ThumbMedia *CDNMedia `json:"thumb_media,omitempty"` + ThumbSize int64 `json:"thumb_size,omitempty"` + ThumbHeight int `json:"thumb_height,omitempty"` + ThumbWidth int `json:"thumb_width,omitempty"` +} + +type RefMessage struct { + MessageItem *MessageItem `json:"message_item,omitempty"` + Title string `json:"title,omitempty"` +} + +type MessageItem struct { + Type int `json:"type,omitempty"` + CreateTimeMs int64 `json:"create_time_ms,omitempty"` + UpdateTimeMs int64 `json:"update_time_ms,omitempty"` + IsCompleted bool `json:"is_completed,omitempty"` + MsgID string `json:"msg_id,omitempty"` + RefMsg *RefMessage `json:"ref_msg,omitempty"` + TextItem *TextItem `json:"text_item,omitempty"` + ImageItem *ImageItem `json:"image_item,omitempty"` + VoiceItem *VoiceItem `json:"voice_item,omitempty"` + FileItem *FileItem `json:"file_item,omitempty"` + VideoItem *VideoItem `json:"video_item,omitempty"` +} + +type WeixinMessage struct { + Seq int `json:"seq,omitempty"` + MessageID int64 `json:"message_id,omitempty"` + FromUserID string `json:"from_user_id,omitempty"` + ToUserID string `json:"to_user_id,omitempty"` + ClientID string `json:"client_id,omitempty"` + CreateTimeMs int64 `json:"create_time_ms,omitempty"` + UpdateTimeMs int64 `json:"update_time_ms,omitempty"` + DeleteTimeMs int64 `json:"delete_time_ms,omitempty"` + SessionID string `json:"session_id,omitempty"` + GroupID string `json:"group_id,omitempty"` + MessageType int `json:"message_type,omitempty"` + MessageState int `json:"message_state,omitempty"` + ItemList []MessageItem `json:"item_list,omitempty"` + ContextToken string `json:"context_token,omitempty"` +} + +type GetUpdatesReq struct { + SyncBuf string `json:"sync_buf,omitempty"` + GetUpdatesBuf string `json:"get_updates_buf,omitempty"` + BaseInfo BaseInfo `json:"base_info,omitempty"` +} + +type GetUpdatesResp struct { + APIStatus + Msgs []WeixinMessage `json:"msgs,omitempty"` + SyncBuf string `json:"sync_buf,omitempty"` + GetUpdatesBuf string `json:"get_updates_buf,omitempty"` + LongpollingTimeoutMs int `json:"longpolling_timeout_ms,omitempty"` +} + +type SendMessageReq struct { + Msg WeixinMessage `json:"msg,omitempty"` + BaseInfo BaseInfo `json:"base_info,omitempty"` +} + +type SendMessageResp struct { + APIStatus +} + +type GetConfigReq struct { + IlinkUserID string `json:"ilink_user_id,omitempty"` + ContextToken string `json:"context_token,omitempty"` + BaseInfo BaseInfo `json:"base_info,omitempty"` +} + +type GetConfigResp struct { + APIStatus + TypingTicket string `json:"typing_ticket,omitempty"` +} + +const ( + TypingStatusTyping = 1 + TypingStatusCancel = 2 +) + +type SendTypingReq struct { + IlinkUserID string `json:"ilink_user_id,omitempty"` + TypingTicket string `json:"typing_ticket,omitempty"` + Status int `json:"status,omitempty"` // 1=typing, 2=cancel + BaseInfo BaseInfo `json:"base_info,omitempty"` +} + +type SendTypingResp struct { + APIStatus +} + +type QRCodeResponse struct { + Qrcode string `json:"qrcode"` + QrcodeImgContent string `json:"qrcode_img_content"` +} + +type StatusResponse struct { + Status string `json:"status"` // "wait", "scaned", "confirmed", "expired" + BotToken string `json:"bot_token,omitempty"` + IlinkBotID string `json:"ilink_bot_id,omitempty"` + Baseurl string `json:"baseurl,omitempty"` + IlinkUserID string `json:"ilink_user_id,omitempty"` +} diff --git a/pkg/channels/weixin/weixin.go b/pkg/channels/weixin/weixin.go new file mode 100644 index 00000000..43c776f9 --- /dev/null +++ b/pkg/channels/weixin/weixin.go @@ -0,0 +1,359 @@ +package weixin + +import ( + "context" + "fmt" + "strings" + "sync" + "time" + + "github.com/google/uuid" + + "github.com/sipeed/picoclaw/pkg/bus" + "github.com/sipeed/picoclaw/pkg/channels" + "github.com/sipeed/picoclaw/pkg/config" + "github.com/sipeed/picoclaw/pkg/identity" + "github.com/sipeed/picoclaw/pkg/logger" +) + +// WeixinChannel is the Weixin channel implementation over Tencent iLink REST API. +type WeixinChannel struct { + *channels.BaseChannel + api *ApiClient + config config.WeixinConfig + ctx context.Context + cancel context.CancelFunc + bus *bus.MessageBus + // contextTokens stores the last context_token per user (from_user_id → context_token). + // This is required by the iLink API to associate replies with the right chat session. + contextTokens sync.Map + typingMu sync.Mutex + typingCache map[string]typingTicketCacheEntry + pauseMu sync.Mutex + pauseUntil time.Time + syncBufPath string +} + +func init() { + channels.RegisterFactory("weixin", func(cfg *config.Config, bus *bus.MessageBus) (channels.Channel, error) { + return NewWeixinChannel(cfg.Channels.Weixin, bus) + }) +} + +// NewWeixinChannel creates a new WeixinChannel from config. +func NewWeixinChannel(cfg config.WeixinConfig, messageBus *bus.MessageBus) (*WeixinChannel, error) { + api, err := NewApiClient(cfg.BaseURL, cfg.Token, cfg.Proxy) + if err != nil { + return nil, fmt.Errorf("weixin: failed to create API client: %w", err) + } + + base := channels.NewBaseChannel( + "weixin", + cfg, + messageBus, + cfg.AllowFrom, + channels.WithMaxMessageLength(4000), + channels.WithReasoningChannelID(cfg.ReasoningChannelID), + ) + + return &WeixinChannel{ + BaseChannel: base, + api: api, + config: cfg, + bus: messageBus, + typingCache: make(map[string]typingTicketCacheEntry), + syncBufPath: buildWeixinSyncBufPath(cfg), + }, nil +} + +func (c *WeixinChannel) Start(ctx context.Context) error { + logger.InfoC("weixin", "Starting Weixin channel") + c.ctx, c.cancel = context.WithCancel(ctx) + c.SetRunning(true) + go c.pollLoop(c.ctx) + logger.InfoC("weixin", "Weixin channel started") + return nil +} + +func (c *WeixinChannel) Stop(ctx context.Context) error { + logger.InfoC("weixin", "Stopping Weixin channel") + c.SetRunning(false) + if c.cancel != nil { + c.cancel() + } + return nil +} + +// pollLoop is the long-poll receive loop. It runs until ctx is canceled. +func (c *WeixinChannel) pollLoop(ctx context.Context) { + const ( + defaultPollTimeoutMs = 35_000 + retryDelay = 2 * time.Second + backoffDelay = 30 * time.Second + maxConsecutiveFails = 3 + ) + + consecutiveFails := 0 + getUpdatesBuf, err := loadGetUpdatesBuf(c.syncBufPath) + if err != nil { + logger.WarnCF("weixin", "Failed to load persisted get_updates_buf", map[string]any{ + "path": c.syncBufPath, + "error": err.Error(), + }) + getUpdatesBuf = "" + } else if getUpdatesBuf != "" { + logger.InfoCF("weixin", "Resuming persisted get_updates_buf", map[string]any{ + "path": c.syncBufPath, + "bytes": len(getUpdatesBuf), + "source": "disk", + }) + } + nextTimeoutMs := defaultPollTimeoutMs + + for { + select { + case <-ctx.Done(): + logger.InfoC("weixin", "Weixin poll loop stopped") + return + default: + } + + if err := c.waitWhileSessionPaused(ctx); err != nil { + if ctx.Err() != nil { + return + } + continue + } + + // Build a context with timeout slightly longer than the long-poll + pollCtx, pollCancel := context.WithTimeout(ctx, time.Duration(nextTimeoutMs+5000)*time.Millisecond) + + resp, err := c.api.GetUpdates(pollCtx, GetUpdatesReq{ + GetUpdatesBuf: getUpdatesBuf, + }) + pollCancel() + + if err != nil { + // Check if we're shutting down + if ctx.Err() != nil { + return + } + + consecutiveFails++ + logger.WarnCF("weixin", "getUpdates failed", map[string]any{ + "error": err.Error(), + "attempt": consecutiveFails, + }) + + if consecutiveFails >= maxConsecutiveFails { + logger.ErrorCF("weixin", "Too many consecutive failures, backing off", map[string]any{ + "duration": backoffDelay, + }) + consecutiveFails = 0 + select { + case <-ctx.Done(): + return + case <-time.After(backoffDelay): + } + } else { + select { + case <-ctx.Done(): + return + case <-time.After(retryDelay): + } + } + continue + } + + if isSessionExpiredStatus(resp.Ret, resp.Errcode) { + remaining := c.pauseSession("getupdates", resp.Ret, resp.Errcode, resp.Errmsg) + select { + case <-ctx.Done(): + return + case <-time.After(remaining): + } + continue + } + + if resp.Errcode != 0 || resp.Ret != 0 { + consecutiveFails++ + logger.ErrorCF("weixin", "getUpdates API error", map[string]any{ + "ret": resp.Ret, + "errcode": resp.Errcode, + "errmsg": resp.Errmsg, + }) + select { + case <-ctx.Done(): + return + case <-time.After(retryDelay): + } + continue + } + + consecutiveFails = 0 + + // Update the long-poll timeout from server hint + if resp.LongpollingTimeoutMs > 0 { + nextTimeoutMs = resp.LongpollingTimeoutMs + } + + // Advance cursor + if resp.GetUpdatesBuf != "" { + getUpdatesBuf = resp.GetUpdatesBuf + if err := saveGetUpdatesBuf(c.syncBufPath, getUpdatesBuf); err != nil { + logger.WarnCF("weixin", "Failed to persist get_updates_buf", map[string]any{ + "path": c.syncBufPath, + "error": err.Error(), + }) + } + } + + // Dispatch messages + for _, msg := range resp.Msgs { + c.handleInboundMessage(ctx, msg) + } + } +} + +// handleInboundMessage converts a WeixinMessage to a bus.InboundMessage. +func (c *WeixinChannel) handleInboundMessage(ctx context.Context, msg WeixinMessage) { + fromUserID := msg.FromUserID + if fromUserID == "" { + return + } + + messageID := msg.ClientID + if messageID == "" { + messageID = uuid.New().String() + } + + // Build text content from item_list + var parts []string + for _, item := range msg.ItemList { + switch item.Type { + case MessageItemTypeText: + if item.TextItem != nil && item.TextItem.Text != "" { + parts = append(parts, item.TextItem.Text) + } + case MessageItemTypeVoice: + if item.VoiceItem != nil && item.VoiceItem.Text != "" { + // Use voice → text transcription from server + parts = append(parts, item.VoiceItem.Text) + } else { + parts = append(parts, "[audio]") + } + case MessageItemTypeImage: + parts = append(parts, "[image]") + case MessageItemTypeFile: + if item.FileItem != nil && item.FileItem.FileName != "" { + parts = append(parts, fmt.Sprintf("[file: %s]", item.FileItem.FileName)) + } else { + parts = append(parts, "[file]") + } + case MessageItemTypeVideo: + parts = append(parts, "[video]") + } + } + + var mediaRefs []string + if mediaItem := selectInboundMediaItem(msg); mediaItem != nil { + ref, err := c.downloadMediaFromItem(ctx, fromUserID, messageID, mediaItem) + if err != nil { + logger.ErrorCF("weixin", "Failed to download inbound media", map[string]any{ + "from_user_id": fromUserID, + "message_id": messageID, + "type": mediaItem.Type, + "error": err.Error(), + }) + } else if ref != "" { + mediaRefs = append(mediaRefs, ref) + } + } + + content := strings.Join(parts, "\n") + if content == "" && len(mediaRefs) == 0 { + return + } + + sender := bus.SenderInfo{ + Platform: "weixin", + PlatformID: fromUserID, + CanonicalID: identity.BuildCanonicalID("weixin", fromUserID), + Username: fromUserID, + DisplayName: fromUserID, + } + + if !c.IsAllowedSender(sender) { + logger.DebugCF("weixin", "Message rejected by allowlist", map[string]any{ + "from_user_id": fromUserID, + }) + return + } + + peer := bus.Peer{Kind: "direct", ID: fromUserID} + + metadata := map[string]string{ + "from_user_id": fromUserID, + "context_token": msg.ContextToken, + "session_id": msg.SessionID, + } + + logger.DebugCF("weixin", "Received message", map[string]any{ + "from_user_id": fromUserID, + "content_len": len(content), + "media_count": len(mediaRefs), + }) + + // Store context_token for outbound reply association + if msg.ContextToken != "" { + c.contextTokens.Store(fromUserID, msg.ContextToken) + } + + c.HandleMessage(ctx, peer, messageID, fromUserID, fromUserID, content, mediaRefs, metadata, sender) +} + +// Send implements channels.Channel by sending a text message to the WeChat user. +func (c *WeixinChannel) Send(ctx context.Context, msg bus.OutboundMessage) error { + if !c.IsRunning() { + return channels.ErrNotRunning + } + if err := c.ensureSessionActive(); err != nil { + return err + } + + if msg.Content == "" { + return nil + } + + // We need a context_token to send a reply. It should be stored in the conversation metadata. + // The chat_id is the weixin user_id (from_user_id). + toUserID := msg.ChatID + + // Retrieve context_token from our per-user map (stored on last inbound) + contextToken := "" + if ct, ok := c.contextTokens.Load(toUserID); ok { + contextToken, _ = ct.(string) + } + + // If we don't have a context token for this user, we cannot send a valid reply. + // Treat this as a non-temporary error so the manager doesn't keep retrying. + if contextToken == "" { + logger.ErrorCF("weixin", "Missing context token, cannot send message", map[string]any{ + "to_user_id": toUserID, + }) + return fmt.Errorf("weixin send: %w: missing context token for chat %s", channels.ErrSendFailed, toUserID) + } + + if err := c.sendTextMessage(ctx, toUserID, contextToken, msg.Content); err != nil { + logger.ErrorCF("weixin", "Failed to send message", map[string]any{ + "to_user_id": toUserID, + "error": err.Error(), + }) + if c.remainingPause() > 0 { + return fmt.Errorf("weixin send: %w", channels.ErrSendFailed) + } + return fmt.Errorf("weixin send: %w", channels.ErrTemporary) + } + + return nil +} diff --git a/pkg/channels/weixin/weixin_test.go b/pkg/channels/weixin/weixin_test.go new file mode 100644 index 00000000..11567539 --- /dev/null +++ b/pkg/channels/weixin/weixin_test.go @@ -0,0 +1,210 @@ +package weixin + +import ( + "bytes" + "context" + "encoding/base64" + "errors" + "io" + "net/http" + "path/filepath" + "testing" + "time" + + basechannels "github.com/sipeed/picoclaw/pkg/channels" + "github.com/sipeed/picoclaw/pkg/config" +) + +type roundTripFunc func(*http.Request) (*http.Response, error) + +func (f roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) { + return f(req) +} + +func TestParseWeixinMediaAESKey(t *testing.T) { + raw := []byte("1234567890abcdef") + + got, err := parseWeixinMediaAESKey(base64.StdEncoding.EncodeToString(raw)) + if err != nil { + t.Fatalf("parseWeixinMediaAESKey(raw) error = %v", err) + } + if !bytes.Equal(got, raw) { + t.Fatalf("parseWeixinMediaAESKey(raw) = %x, want %x", got, raw) + } + + hexEncoded := base64.StdEncoding.EncodeToString([]byte("31323334353637383930616263646566")) + got, err = parseWeixinMediaAESKey(hexEncoded) + if err != nil { + t.Fatalf("parseWeixinMediaAESKey(hex-string) error = %v", err) + } + if !bytes.Equal(got, raw) { + t.Fatalf("parseWeixinMediaAESKey(hex-string) = %x, want %x", got, raw) + } +} + +func TestDownloadAndDecryptCDNBuffer(t *testing.T) { + key := []byte("1234567890abcdef") + plaintext := []byte("hello weixin") + ciphertext, err := encryptAESECB(plaintext, key) + if err != nil { + t.Fatalf("encryptAESECB() error = %v", err) + } + + ch := &WeixinChannel{ + api: &ApiClient{ + HttpClient: &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) { + if r.URL.Path != "/download" { + t.Fatalf("download path = %q, want /download", r.URL.Path) + } + if r.URL.Query().Get("encrypted_query_param") != "token" { + t.Fatalf("encrypted_query_param = %q, want token", r.URL.Query().Get("encrypted_query_param")) + } + return &http.Response{ + StatusCode: http.StatusOK, + Body: io.NopCloser(bytes.NewReader(ciphertext)), + Header: make(http.Header), + }, nil + })}, + }, + config: config.WeixinConfig{ + CDNBaseURL: "https://cdn.example.com", + }, + typingCache: make(map[string]typingTicketCacheEntry), + } + + got, err := ch.downloadAndDecryptCDNBuffer(context.Background(), "token", key) + if err != nil { + t.Fatalf("downloadAndDecryptCDNBuffer() error = %v", err) + } + if !bytes.Equal(got, plaintext) { + t.Fatalf("downloadAndDecryptCDNBuffer() = %q, want %q", got, plaintext) + } +} + +func TestUploadBufferToCDN(t *testing.T) { + key := []byte("1234567890abcdef") + plaintext := []byte("upload me") + wantCipher, err := encryptAESECB(plaintext, key) + if err != nil { + t.Fatalf("encryptAESECB() error = %v", err) + } + + ch := &WeixinChannel{ + api: &ApiClient{ + HttpClient: &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) { + if r.URL.Path != "/upload" { + t.Fatalf("upload path = %q, want /upload", r.URL.Path) + } + if got := r.URL.Query().Get("encrypted_query_param"); got != "upload-param" { + t.Fatalf("encrypted_query_param = %q, want upload-param", got) + } + if got := r.URL.Query().Get("filekey"); got != "file-key" { + t.Fatalf("filekey = %q, want file-key", got) + } + body, _ := io.ReadAll(r.Body) + if !bytes.Equal(body, wantCipher) { + t.Fatalf("upload body = %x, want %x", body, wantCipher) + } + return &http.Response{ + StatusCode: http.StatusOK, + Body: io.NopCloser(bytes.NewReader(nil)), + Header: http.Header{ + "X-Encrypted-Param": []string{"download-param"}, + }, + }, nil + })}, + }, + config: config.WeixinConfig{ + CDNBaseURL: "https://cdn.example.com", + }, + typingCache: make(map[string]typingTicketCacheEntry), + } + + got, err := ch.uploadBufferToCDN(context.Background(), plaintext, "upload-param", "file-key", key) + if err != nil { + t.Fatalf("uploadBufferToCDN() error = %v", err) + } + if got != "download-param" { + t.Fatalf("uploadBufferToCDN() = %q, want download-param", got) + } +} + +func TestLoadSaveGetUpdatesBuf(t *testing.T) { + path := filepath.Join(t.TempDir(), "sync.json") + + if err := saveGetUpdatesBuf(path, "cursor-123"); err != nil { + t.Fatalf("saveGetUpdatesBuf() error = %v", err) + } + + got, err := loadGetUpdatesBuf(path) + if err != nil { + t.Fatalf("loadGetUpdatesBuf() error = %v", err) + } + if got != "cursor-123" { + t.Fatalf("loadGetUpdatesBuf() = %q, want cursor-123", got) + } +} + +func TestBuildWeixinSyncBufPathUsesPicoclawHome(t *testing.T) { + home := t.TempDir() + t.Setenv(config.EnvHome, home) + + got := buildWeixinSyncBufPath(config.WeixinConfig{ + BaseURL: "https://ilinkai.weixin.qq.com/", + Token: "token-123", + }) + if filepath.Dir(got) != filepath.Join(home, "channels", "weixin", "sync") { + t.Fatalf("sync path dir = %q", filepath.Dir(got)) + } +} + +func TestSessionPauseGuard(t *testing.T) { + ch := &WeixinChannel{ + typingCache: make(map[string]typingTicketCacheEntry), + } + + ch.pauseSession("getupdates", 0, weixinSessionExpiredCode, "expired") + + if err := ch.ensureSessionActive(); !errors.Is(err, basechannels.ErrSendFailed) { + t.Fatalf("ensureSessionActive() error = %v, want ErrSendFailed", err) + } + + ch.pauseMu.Lock() + ch.pauseUntil = time.Now().Add(-time.Second) + ch.pauseMu.Unlock() + + if err := ch.ensureSessionActive(); err != nil { + t.Fatalf("ensureSessionActive() after expiry error = %v, want nil", err) + } +} + +func TestSelectInboundMediaItemFallsBackToRefMessage(t *testing.T) { + msg := WeixinMessage{ + ItemList: []MessageItem{ + { + Type: MessageItemTypeText, + TextItem: &TextItem{ + Text: "look", + }, + RefMsg: &RefMessage{ + MessageItem: &MessageItem{ + Type: MessageItemTypeImage, + ImageItem: &ImageItem{ + Media: &CDNMedia{ + EncryptQueryParam: "abc", + }, + }, + }, + }, + }, + }, + } + + item := selectInboundMediaItem(msg) + if item == nil { + t.Fatal("selectInboundMediaItem() = nil, want ref media item") + } + if item.Type != MessageItemTypeImage { + t.Fatalf("selectInboundMediaItem().Type = %d, want %d", item.Type, MessageItemTypeImage) + } +} diff --git a/pkg/commands/builtin.go b/pkg/commands/builtin.go index 6d9ece82..7bd36b65 100644 --- a/pkg/commands/builtin.go +++ b/pkg/commands/builtin.go @@ -13,6 +13,7 @@ func BuiltinDefinitions() []Definition { switchCommand(), checkCommand(), clearCommand(), + subagentsCommand(), reloadCommand(), } } diff --git a/pkg/commands/cmd_subagents.go b/pkg/commands/cmd_subagents.go new file mode 100644 index 00000000..29321823 --- /dev/null +++ b/pkg/commands/cmd_subagents.go @@ -0,0 +1,42 @@ +package commands + +import ( + "context" + "fmt" +) + +// TurnInfo is a mirrored struct from agent.TurnInfo to avoid circular dependencies. +type TurnInfo struct { + TurnID string + ParentTurnID string + Depth int + ChildTurnIDs []string + IsFinished bool +} + +func subagentsCommand() Definition { + return Definition{ + Name: "subagents", + Description: "Show running subagents and task tree", + Handler: func(ctx context.Context, req Request, rt *Runtime) error { + getTurnFn := rt.GetActiveTurn + if getTurnFn == nil { + return req.Reply("Runtime does not support querying active turns.") + } + + turnRaw := getTurnFn() + if turnRaw == nil { + return req.Reply("No active tasks running in this session.") + } + + if treeStr, ok := turnRaw.(string); ok { + if treeStr == "" { + return req.Reply("No active tasks running in this session.") + } + return req.Reply(fmt.Sprintf("🤖 **Active Subagents Tree**\n```text\n%s\n```", treeStr)) + } + + return req.Reply(fmt.Sprintf("🤖 **Active Subagents List**\n```text\n%+v\n```", turnRaw)) + }, + } +} diff --git a/pkg/commands/runtime.go b/pkg/commands/runtime.go index 84f77580..f714e1ca 100644 --- a/pkg/commands/runtime.go +++ b/pkg/commands/runtime.go @@ -11,6 +11,7 @@ type Runtime struct { ListAgentIDs func() []string ListDefinitions func() []Definition GetEnabledChannels func() []string + GetActiveTurn func() any // Returning any to avoid circular dependency with agent package SwitchModel func(value string) (oldModel string, err error) SwitchChannel func(value string) error ClearHistory func() error diff --git a/pkg/config/config.go b/pkg/config/config.go index 235cb064..7c7b7995 100644 --- a/pkg/config/config.go +++ b/pkg/config/config.go @@ -84,6 +84,7 @@ type Config struct { Providers ProvidersConfig `json:"providers,omitempty"` ModelList []ModelConfig `json:"model_list"` // New model-centric provider configuration Gateway GatewayConfig `json:"gateway"` + Hooks HooksConfig `json:"hooks,omitempty"` Tools ToolsConfig `json:"tools"` Heartbeat HeartbeatConfig `json:"heartbeat"` Devices DevicesConfig `json:"devices"` @@ -92,6 +93,36 @@ type Config struct { BuildInfo BuildInfo `json:"build_info,omitempty"` } +type HooksConfig struct { + Enabled bool `json:"enabled"` + Defaults HookDefaultsConfig `json:"defaults,omitempty"` + Builtins map[string]BuiltinHookConfig `json:"builtins,omitempty"` + Processes map[string]ProcessHookConfig `json:"processes,omitempty"` +} + +type HookDefaultsConfig struct { + ObserverTimeoutMS int `json:"observer_timeout_ms,omitempty"` + InterceptorTimeoutMS int `json:"interceptor_timeout_ms,omitempty"` + ApprovalTimeoutMS int `json:"approval_timeout_ms,omitempty"` +} + +type BuiltinHookConfig struct { + Enabled bool `json:"enabled"` + Priority int `json:"priority,omitempty"` + Config json.RawMessage `json:"config,omitempty"` +} + +type ProcessHookConfig struct { + Enabled bool `json:"enabled"` + Priority int `json:"priority,omitempty"` + Transport string `json:"transport,omitempty"` + Command []string `json:"command,omitempty"` + Dir string `json:"dir,omitempty"` + Env map[string]string `json:"env,omitempty"` + Observe []string `json:"observe,omitempty"` + Intercept []string `json:"intercept,omitempty"` +} + // BuildInfo contains build-time version information type BuildInfo struct { Version string `json:"version"` @@ -219,9 +250,15 @@ type RoutingConfig struct { Threshold float64 `json:"threshold"` // complexity score in [0,1]; score >= threshold → primary model } -// ToolFeedbackConfig controls whether tool execution details are sent to the -// chat channel as real-time feedback messages. When enabled, every tool call -// produces a short notification with the tool name and its parameters. +// SubTurnConfig configures the SubTurn execution system. +type SubTurnConfig struct { + MaxDepth int `json:"max_depth" env:"PICOCLAW_AGENTS_DEFAULTS_SUBTURN_MAX_DEPTH"` + MaxConcurrent int `json:"max_concurrent" env:"PICOCLAW_AGENTS_DEFAULTS_SUBTURN_MAX_CONCURRENT"` + DefaultTimeoutMinutes int `json:"default_timeout_minutes" env:"PICOCLAW_AGENTS_DEFAULTS_SUBTURN_DEFAULT_TIMEOUT_MINUTES"` + DefaultTokenBudget int `json:"default_token_budget" env:"PICOCLAW_AGENTS_DEFAULTS_SUBTURN_DEFAULT_TOKEN_BUDGET"` + ConcurrencyTimeoutSec int `json:"concurrency_timeout_sec" env:"PICOCLAW_AGENTS_DEFAULTS_SUBTURN_CONCURRENCY_TIMEOUT_SEC"` +} + type ToolFeedbackConfig struct { Enabled bool `json:"enabled" env:"PICOCLAW_AGENTS_DEFAULTS_TOOL_FEEDBACK_ENABLED"` MaxArgsLength int `json:"max_args_length" env:"PICOCLAW_AGENTS_DEFAULTS_TOOL_FEEDBACK_MAX_ARGS_LENGTH"` @@ -238,13 +275,17 @@ type AgentDefaults struct { ImageModel string `json:"image_model,omitempty" env:"PICOCLAW_AGENTS_DEFAULTS_IMAGE_MODEL"` ImageModelFallbacks []string `json:"image_model_fallbacks,omitempty"` MaxTokens int `json:"max_tokens" env:"PICOCLAW_AGENTS_DEFAULTS_MAX_TOKENS"` + ContextWindow int `json:"context_window,omitempty" env:"PICOCLAW_AGENTS_DEFAULTS_CONTEXT_WINDOW"` Temperature *float64 `json:"temperature,omitempty" env:"PICOCLAW_AGENTS_DEFAULTS_TEMPERATURE"` MaxToolIterations int `json:"max_tool_iterations" env:"PICOCLAW_AGENTS_DEFAULTS_MAX_TOOL_ITERATIONS"` SummarizeMessageThreshold int `json:"summarize_message_threshold" env:"PICOCLAW_AGENTS_DEFAULTS_SUMMARIZE_MESSAGE_THRESHOLD"` SummarizeTokenPercent int `json:"summarize_token_percent" env:"PICOCLAW_AGENTS_DEFAULTS_SUMMARIZE_TOKEN_PERCENT"` MaxMediaSize int `json:"max_media_size,omitempty" env:"PICOCLAW_AGENTS_DEFAULTS_MAX_MEDIA_SIZE"` Routing *RoutingConfig `json:"routing,omitempty"` + SteeringMode string `json:"steering_mode,omitempty" env:"PICOCLAW_AGENTS_DEFAULTS_STEERING_MODE"` // "one-at-a-time" (default) or "all" + SubTurn SubTurnConfig `json:"subturn" envPrefix:"PICOCLAW_AGENTS_DEFAULTS_SUBTURN_"` ToolFeedback ToolFeedbackConfig `json:"tool_feedback,omitempty"` + LogLevel string `json:"log_level,omitempty" env:"PICOCLAW_LOG_LEVEL"` } const ( @@ -296,6 +337,7 @@ type ChannelsConfig struct { WeCom WeComConfig `json:"wecom"` WeComApp WeComAppConfig `json:"wecom_app"` WeComAIBot WeComAIBotConfig `json:"wecom_aibot"` + Weixin WeixinConfig `json:"weixin"` Pico PicoConfig `json:"pico"` PicoClient PicoClientConfig `json:"pico_client"` IRC IRCConfig `json:"irc"` @@ -499,6 +541,16 @@ type WeComAIBotConfig struct { ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_REASONING_CHANNEL_ID"` } +type WeixinConfig struct { + Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_WEIXIN_ENABLED"` + Token string `json:"token" env:"PICOCLAW_CHANNELS_WEIXIN_TOKEN"` + BaseURL string `json:"base_url" env:"PICOCLAW_CHANNELS_WEIXIN_BASE_URL"` + CDNBaseURL string `json:"cdn_base_url" env:"PICOCLAW_CHANNELS_WEIXIN_CDN_BASE_URL"` + Proxy string `json:"proxy" env:"PICOCLAW_CHANNELS_WEIXIN_PROXY"` + AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_WEIXIN_ALLOW_FROM"` + ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_WEIXIN_REASONING_CHANNEL_ID"` +} + type PicoConfig struct { Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_PICO_ENABLED"` Token string `json:"token" env:"PICOCLAW_CHANNELS_PICO_TOKEN"` @@ -911,10 +963,13 @@ func LoadConfig(path string) (*Config, error) { if passphrase := credential.PassphraseProvider(); passphrase != "" { for _, m := range cfg.ModelList { - if m.APIKey != "" && !strings.HasPrefix(m.APIKey, "enc://") && !strings.HasPrefix(m.APIKey, "file://") { - fmt.Fprintf(os.Stderr, + if m.APIKey != "" && !strings.HasPrefix(m.APIKey, "enc://") && + !strings.HasPrefix(m.APIKey, "file://") { + fmt.Fprintf( + os.Stderr, "picoclaw: warning: model %q has a plaintext api_key; call SaveConfig to encrypt it\n", - m.ModelName) + m.ModelName, + ) } } } @@ -967,7 +1022,8 @@ func encryptPlaintextAPIKeys(models []ModelConfig, passphrase string) ([]ModelCo changed := false for i := range sealed { m := &sealed[i] - if m.APIKey == "" || strings.HasPrefix(m.APIKey, "enc://") || strings.HasPrefix(m.APIKey, "file://") { + if m.APIKey == "" || strings.HasPrefix(m.APIKey, "enc://") || + strings.HasPrefix(m.APIKey, "file://") { continue } encrypted, err := credential.Encrypt(passphrase, "", m.APIKey) @@ -1000,7 +1056,13 @@ func resolveAPIKeys(models []ModelConfig, configDir string) error { for j, key := range models[i].APIKeys { resolved, err := cr.Resolve(key) if err != nil { - return fmt.Errorf("model_list[%d] (%s): api_keys[%d]: %w", i, models[i].ModelName, j, err) + return fmt.Errorf( + "model_list[%d] (%s): api_keys[%d]: %w", + i, + models[i].ModelName, + j, + err, + ) } models[i].APIKeys[j] = resolved } diff --git a/pkg/config/config_test.go b/pkg/config/config_test.go index 588c0464..88ab1ed5 100644 --- a/pkg/config/config_test.go +++ b/pkg/config/config_test.go @@ -470,6 +470,29 @@ func TestDefaultConfig_CronAllowCommandEnabled(t *testing.T) { } } +func TestDefaultConfig_HooksDefaults(t *testing.T) { + cfg := DefaultConfig() + if !cfg.Hooks.Enabled { + t.Fatal("DefaultConfig().Hooks.Enabled should be true") + } + if cfg.Hooks.Defaults.ObserverTimeoutMS != 500 { + t.Fatalf("ObserverTimeoutMS = %d, want 500", cfg.Hooks.Defaults.ObserverTimeoutMS) + } + if cfg.Hooks.Defaults.InterceptorTimeoutMS != 5000 { + t.Fatalf("InterceptorTimeoutMS = %d, want 5000", cfg.Hooks.Defaults.InterceptorTimeoutMS) + } + if cfg.Hooks.Defaults.ApprovalTimeoutMS != 60000 { + t.Fatalf("ApprovalTimeoutMS = %d, want 60000", cfg.Hooks.Defaults.ApprovalTimeoutMS) + } +} + +func TestDefaultConfig_LogLevel(t *testing.T) { + cfg := DefaultConfig() + if cfg.Agents.Defaults.LogLevel != "fatal" { + t.Errorf("LogLevel = %q, want \"fatal\"", cfg.Agents.Defaults.LogLevel) + } +} + func TestLoadConfig_OpenAIWebSearchDefaultsTrueWhenUnset(t *testing.T) { dir := t.TempDir() configPath := filepath.Join(dir, "config.json") @@ -555,6 +578,88 @@ func TestLoadConfig_WebToolsProxy(t *testing.T) { } } +func TestLoadConfig_HooksProcessConfig(t *testing.T) { + tmpDir := t.TempDir() + configPath := filepath.Join(tmpDir, "config.json") + configJSON := `{ + "hooks": { + "processes": { + "review-gate": { + "enabled": true, + "transport": "stdio", + "command": ["uvx", "picoclaw-hook-reviewer"], + "dir": "/tmp/hooks", + "env": { + "HOOK_MODE": "rewrite" + }, + "observe": ["turn_start", "turn_end"], + "intercept": ["before_tool", "approve_tool"] + } + }, + "builtins": { + "audit": { + "enabled": true, + "priority": 5, + "config": { + "label": "audit" + } + } + } + } +}` + if err := os.WriteFile(configPath, []byte(configJSON), 0o600); err != nil { + t.Fatalf("os.WriteFile() error: %v", err) + } + + cfg, err := LoadConfig(configPath) + if err != nil { + t.Fatalf("LoadConfig() error: %v", err) + } + + processCfg, ok := cfg.Hooks.Processes["review-gate"] + if !ok { + t.Fatal("expected review-gate process hook") + } + if !processCfg.Enabled { + t.Fatal("expected review-gate process hook to be enabled") + } + if processCfg.Transport != "stdio" { + t.Fatalf("Transport = %q, want stdio", processCfg.Transport) + } + if len(processCfg.Command) != 2 || processCfg.Command[0] != "uvx" { + t.Fatalf("Command = %v", processCfg.Command) + } + if processCfg.Dir != "/tmp/hooks" { + t.Fatalf("Dir = %q, want /tmp/hooks", processCfg.Dir) + } + if processCfg.Env["HOOK_MODE"] != "rewrite" { + t.Fatalf("HOOK_MODE = %q, want rewrite", processCfg.Env["HOOK_MODE"]) + } + if len(processCfg.Observe) != 2 || processCfg.Observe[1] != "turn_end" { + t.Fatalf("Observe = %v", processCfg.Observe) + } + if len(processCfg.Intercept) != 2 || processCfg.Intercept[1] != "approve_tool" { + t.Fatalf("Intercept = %v", processCfg.Intercept) + } + + builtinCfg, ok := cfg.Hooks.Builtins["audit"] + if !ok { + t.Fatal("expected audit builtin hook") + } + if !builtinCfg.Enabled { + t.Fatal("expected audit builtin hook to be enabled") + } + if builtinCfg.Priority != 5 { + t.Fatalf("Priority = %d, want 5", builtinCfg.Priority) + } + if !strings.Contains(string(builtinCfg.Config), `"audit"`) { + t.Fatalf("Config = %s", string(builtinCfg.Config)) + } + if cfg.Hooks.Defaults.ApprovalTimeoutMS != 60000 { + t.Fatalf("ApprovalTimeoutMS = %d, want 60000", cfg.Hooks.Defaults.ApprovalTimeoutMS) + } +} + // TestDefaultConfig_DMScope verifies the default dm_scope value // TestDefaultConfig_SummarizationThresholds verifies summarization defaults func TestDefaultConfig_SummarizationThresholds(t *testing.T) { @@ -1057,3 +1162,38 @@ func TestLoadConfig_UsesPassphraseProvider(t *testing.T) { t.Errorf("api_key = %q, want %q", cfg.ModelList[0].APIKey, plainKey) } } + +func TestConfigParsesLogLevel(t *testing.T) { + dir := t.TempDir() + cfgPath := filepath.Join(dir, "config.json") + data := `{"agents":{"defaults":{"log_level":"debug"}}}` + if err := os.WriteFile(cfgPath, []byte(data), 0o600); err != nil { + t.Fatalf("setup: %v", err) + } + + cfg, err := LoadConfig(cfgPath) + if err != nil { + t.Fatalf("LoadConfig: %v", err) + } + if cfg.Agents.Defaults.LogLevel != "debug" { + t.Errorf("LogLevel = %q, want \"debug\"", cfg.Agents.Defaults.LogLevel) + } +} + +func TestConfigLogLevelEmpty(t *testing.T) { + dir := t.TempDir() + cfgPath := filepath.Join(dir, "config.json") + data := `{}` + if err := os.WriteFile(cfgPath, []byte(data), 0o600); err != nil { + t.Fatalf("setup: %v", err) + } + + cfg, err := LoadConfig(cfgPath) + if err != nil { + t.Fatalf("LoadConfig: %v", err) + } + // When config omits log_level, the DefaultConfig value ("fatal") is preserved. + if cfg.Agents.Defaults.LogLevel != "fatal" { + t.Errorf("LogLevel = %q, want \"fatal\"", cfg.Agents.Defaults.LogLevel) + } +} diff --git a/pkg/config/defaults.go b/pkg/config/defaults.go index 0d2141ae..3397eb91 100644 --- a/pkg/config/defaults.go +++ b/pkg/config/defaults.go @@ -26,6 +26,7 @@ func DefaultConfig() *Config { return &Config{ Agents: AgentsConfig{ Defaults: AgentDefaults{ + LogLevel: "fatal", Workspace: workspacePath, RestrictToWorkspace: true, Provider: "", @@ -35,6 +36,7 @@ func DefaultConfig() *Config { MaxToolIterations: 50, SummarizeMessageThreshold: 20, SummarizeTokenPercent: 75, + SteeringMode: "one-at-a-time", ToolFeedback: ToolFeedbackConfig{ Enabled: true, MaxArgsLength: 300, @@ -174,6 +176,14 @@ func DefaultConfig() *Config { WelcomeMessage: "Hello! I'm your AI assistant. How can I help you today?", ProcessingMessage: DefaultWeComAIBotProcessingMessage, }, + Weixin: WeixinConfig{ + Enabled: false, + Token: "", + BaseURL: "https://ilinkai.weixin.qq.com/", + CDNBaseURL: "https://novac2c.cdn.weixin.qq.com/c2c", + AllowFrom: FlexibleStringSlice{}, + Proxy: "", + }, Pico: PicoConfig{ Enabled: false, Token: "", @@ -184,6 +194,14 @@ func DefaultConfig() *Config { AllowFrom: FlexibleStringSlice{}, }, }, + Hooks: HooksConfig{ + Enabled: true, + Defaults: HookDefaultsConfig{ + ObserverTimeoutMS: 500, + InterceptorTimeoutMS: 5000, + ApprovalTimeoutMS: 60000, + }, + }, Providers: ProvidersConfig{ OpenAI: OpenAIProviderConfig{WebSearch: true}, }, diff --git a/pkg/gateway/gateway.go b/pkg/gateway/gateway.go index 9a2706b3..92bef6c1 100644 --- a/pkg/gateway/gateway.go +++ b/pkg/gateway/gateway.go @@ -27,6 +27,7 @@ import ( _ "github.com/sipeed/picoclaw/pkg/channels/slack" _ "github.com/sipeed/picoclaw/pkg/channels/telegram" _ "github.com/sipeed/picoclaw/pkg/channels/wecom" + _ "github.com/sipeed/picoclaw/pkg/channels/weixin" _ "github.com/sipeed/picoclaw/pkg/channels/whatsapp" _ "github.com/sipeed/picoclaw/pkg/channels/whatsapp_native" "github.com/sipeed/picoclaw/pkg/config" @@ -79,16 +80,18 @@ func (p *startupBlockedProvider) GetDefaultModel() string { // Run starts the gateway runtime using the configuration loaded from configPath. func Run(debug bool, configPath string, allowEmptyStartup bool) error { - if debug { - logger.SetLevel(logger.DEBUG) - fmt.Println("🔍 Debug mode enabled") - } - cfg, err := config.LoadConfig(configPath) if err != nil { return fmt.Errorf("error loading config: %w", err) } + logger.SetLevelFromString(cfg.Agents.Defaults.LogLevel) + + if debug { + logger.SetLevel(logger.DEBUG) + fmt.Println("🔍 Debug mode enabled") + } + provider, modelID, err := createStartupProvider(cfg, allowEmptyStartup) if err != nil { return fmt.Errorf("error creating provider: %w", err) diff --git a/pkg/logger/logger.go b/pkg/logger/logger.go index c5a1f895..17980460 100644 --- a/pkg/logger/logger.go +++ b/pkg/logger/logger.go @@ -106,6 +106,36 @@ func GetLevel() LogLevel { return currentLevel } +// ParseLevel converts a case-insensitive level name to a LogLevel. +// Returns the level and true if valid, or (INFO, false) if unrecognized. +func ParseLevel(s string) (LogLevel, bool) { + switch strings.ToLower(strings.TrimSpace(s)) { + case "debug": + return DEBUG, true + case "info": + return INFO, true + case "warn", "warning": + return WARN, true + case "error": + return ERROR, true + case "fatal": + return FATAL, true + default: + return INFO, false + } +} + +// SetLevelFromString sets the log level from a string value. +// If the string is empty or not a recognized level name, the current level is kept. +func SetLevelFromString(s string) { + if s == "" { + return + } + if level, ok := ParseLevel(s); ok { + SetLevel(level) + } +} + func EnableFileLogging(filePath string) error { mu.Lock() defer mu.Unlock() diff --git a/pkg/logger/logger_test.go b/pkg/logger/logger_test.go index 31b40484..e551db58 100644 --- a/pkg/logger/logger_test.go +++ b/pkg/logger/logger_test.go @@ -252,3 +252,88 @@ func TestFormatFieldValue(t *testing.T) { }) } } + +func TestDefaultLevelIsInfo(t *testing.T) { + // The package-level default (before any SetLevel call) should be INFO. + // Because earlier tests may have changed it, we just verify the constant is wired correctly. + if logLevelNames[INFO] != "INFO" { + t.Errorf("INFO constant mapped to %q, want \"INFO\"", logLevelNames[INFO]) + } +} + +func TestParseLevelValid(t *testing.T) { + tests := []struct { + input string + want LogLevel + }{ + {"debug", DEBUG}, + {"DEBUG", DEBUG}, + {"Debug", DEBUG}, + {"info", INFO}, + {"INFO", INFO}, + {"warn", WARN}, + {"WARN", WARN}, + {"warning", WARN}, + {"WARNING", WARN}, + {"error", ERROR}, + {"ERROR", ERROR}, + {"fatal", FATAL}, + {"FATAL", FATAL}, + {" info ", INFO}, + } + + for _, tt := range tests { + t.Run(tt.input, func(t *testing.T) { + got, ok := ParseLevel(tt.input) + if !ok { + t.Fatalf("ParseLevel(%q) returned ok=false, want true", tt.input) + } + if got != tt.want { + t.Errorf("ParseLevel(%q) = %v, want %v", tt.input, got, tt.want) + } + }) + } +} + +func TestParseLevelInvalid(t *testing.T) { + tests := []string{"", "garbage", "verbose", "trace", "critical"} + + for _, input := range tests { + t.Run(input, func(t *testing.T) { + _, ok := ParseLevel(input) + if ok { + t.Errorf("ParseLevel(%q) returned ok=true, want false", input) + } + }) + } +} + +func TestSetLevelFromString(t *testing.T) { + initialLevel := GetLevel() + defer SetLevel(initialLevel) + + // Valid string changes the level + SetLevel(INFO) + SetLevelFromString("error") + if got := GetLevel(); got != ERROR { + t.Errorf("after SetLevelFromString(\"error\"): GetLevel() = %v, want ERROR", got) + } + + // Empty string is a no-op + SetLevelFromString("") + if got := GetLevel(); got != ERROR { + t.Errorf("after SetLevelFromString(\"\"): GetLevel() = %v, want ERROR (unchanged)", got) + } + + // Invalid string is a no-op + SetLevelFromString("garbage") + if got := GetLevel(); got != ERROR { + t.Errorf("after SetLevelFromString(\"garbage\"): GetLevel() = %v, want ERROR (unchanged)", got) + } + + // Case-insensitive + SetLevelFromString("FATAL") + if got := GetLevel(); got != FATAL { + t.Errorf("after SetLevelFromString(\"FATAL\"): GetLevel() = %v, want FATAL", got) + } +} diff --git a/pkg/providers/common/common.go b/pkg/providers/common/common.go index 23680a1b..9dfd7dc1 100644 --- a/pkg/providers/common/common.go +++ b/pkg/providers/common/common.go @@ -214,11 +214,20 @@ func ParseResponse(body io.Reader) (*LLMResponse, error) { Reasoning: choice.Message.Reasoning, ReasoningDetails: choice.Message.ReasoningDetails, ToolCalls: toolCalls, - FinishReason: choice.FinishReason, + FinishReason: normalizeFinishReason(choice.FinishReason), Usage: apiResponse.Usage, }, nil } +// normalizeFinishReason normalizes finish_reason values across providers. +// Converts "length" to "truncated" for consistent handling. +func normalizeFinishReason(reason string) string { + if reason == "length" { + return "truncated" + } + return reason +} + // DecodeToolCallArguments decodes a tool call's arguments from raw JSON. func DecodeToolCallArguments(raw json.RawMessage, name string) map[string]any { arguments := make(map[string]any) diff --git a/pkg/tools/registry.go b/pkg/tools/registry.go index 902eb442..94fea278 100644 --- a/pkg/tools/registry.go +++ b/pkg/tools/registry.go @@ -413,3 +413,22 @@ func (r *ToolRegistry) GetSummaries() []string { } return summaries } + +// GetAll returns all registered tools (both core and non-core with TTL > 0). +// Used by SubTurn to inherit parent's tool set. +func (r *ToolRegistry) GetAll() []Tool { + r.mu.RLock() + defer r.mu.RUnlock() + + sorted := r.sortedToolNames() + tools := make([]Tool, 0, len(sorted)) + for _, name := range sorted { + entry := r.tools[name] + + // Include core tools and non-core tools with active TTL + if entry.IsCore || entry.TTL > 0 { + tools = append(tools, entry.Tool) + } + } + return tools +} diff --git a/pkg/tools/result.go b/pkg/tools/result.go index f75ce6d4..c8121312 100644 --- a/pkg/tools/result.go +++ b/pkg/tools/result.go @@ -3,6 +3,8 @@ package tools import ( "encoding/json" "strings" + + "github.com/sipeed/picoclaw/pkg/providers" ) const ( @@ -43,6 +45,11 @@ type ToolResult struct { // When non-empty, the agent will publish these as OutboundMediaMessage. Media []string `json:"media,omitempty"` + // Messages holds the ephemeral session history after execution. + // Only populated by SubTurn executions; used by evaluator_optimizer + // to carry stateful worker context across evaluation iterations. + Messages []providers.Message `json:"-"` + // ArtifactTags exposes local artifact paths back to the LLM in a structured // form, e.g. "[file:/tmp/example.png]". This is used when a tool produced a // reusable local artifact but did not deliver it to the user yet. diff --git a/pkg/tools/spawn.go b/pkg/tools/spawn.go index be40ffda..d019d511 100644 --- a/pkg/tools/spawn.go +++ b/pkg/tools/spawn.go @@ -7,7 +7,10 @@ import ( ) type SpawnTool struct { - manager *SubagentManager + spawner SubTurnSpawner + defaultModel string + maxTokens int + temperature float64 allowlistCheck func(targetAgentID string) bool } @@ -15,9 +18,19 @@ type SpawnTool struct { var _ AsyncExecutor = (*SpawnTool)(nil) func NewSpawnTool(manager *SubagentManager) *SpawnTool { - return &SpawnTool{ - manager: manager, + if manager == nil { + return &SpawnTool{} } + return &SpawnTool{ + defaultModel: manager.defaultModel, + maxTokens: manager.maxTokens, + temperature: manager.temperature, + } +} + +// SetSpawner sets the SubTurnSpawner for direct sub-turn execution. +func (t *SpawnTool) SetSpawner(spawner SubTurnSpawner) { + t.spawner = spawner } func (t *SpawnTool) Name() string { @@ -59,11 +72,19 @@ func (t *SpawnTool) Execute(ctx context.Context, args map[string]any) *ToolResul // ExecuteAsync implements AsyncExecutor. The callback is passed through to the // subagent manager as a call parameter — never stored on the SpawnTool instance. -func (t *SpawnTool) ExecuteAsync(ctx context.Context, args map[string]any, cb AsyncCallback) *ToolResult { +func (t *SpawnTool) ExecuteAsync( + ctx context.Context, + args map[string]any, + cb AsyncCallback, +) *ToolResult { return t.execute(ctx, args, cb) } -func (t *SpawnTool) execute(ctx context.Context, args map[string]any, cb AsyncCallback) *ToolResult { +func (t *SpawnTool) execute( + ctx context.Context, + args map[string]any, + cb AsyncCallback, +) *ToolResult { task, ok := args["task"].(string) if !ok || strings.TrimSpace(task) == "" { return ErrorResult("task is required and must be a non-empty string") @@ -79,28 +100,53 @@ func (t *SpawnTool) execute(ctx context.Context, args map[string]any, cb AsyncCa } } - if t.manager == nil { - return ErrorResult("Subagent manager not configured") + // Build system prompt for spawned subagent + systemPrompt := fmt.Sprintf( + `You are a spawned subagent running in the background. Complete the given task independently and report back when done. + +Task: %s`, + task, + ) + + if label != "" { + systemPrompt = fmt.Sprintf( + `You are a spawned subagent labeled "%s" running in the background. Complete the given task independently and report back when done. + +Task: %s`, + label, + task, + ) } - // Read channel/chatID from context (injected by registry). - // Fall back to "cli"/"direct" for non-conversation callers (e.g., CLI, tests) - // to preserve the same defaults as the original NewSpawnTool constructor. - channel := ToolChannel(ctx) - if channel == "" { - channel = "cli" - } - chatID := ToolChatID(ctx) - if chatID == "" { - chatID = "direct" + // Use spawner if available (direct SpawnSubTurn call) + if t.spawner != nil { + // Launch async sub-turn in goroutine + go func() { + result, err := t.spawner.SpawnSubTurn(ctx, SubTurnConfig{ + Model: t.defaultModel, + Tools: nil, // Will inherit from parent via context + SystemPrompt: systemPrompt, + MaxTokens: t.maxTokens, + Temperature: t.temperature, + Async: true, // Async execution + }) + if err != nil { + result = ErrorResult(fmt.Sprintf("Spawn failed: %v", err)).WithError(err) + } + + // Call callback if provided + if cb != nil { + cb(ctx, result) + } + }() + + // Return immediate acknowledgment + if label != "" { + return AsyncResult(fmt.Sprintf("Spawned subagent '%s' for task: %s", label, task)) + } + return AsyncResult(fmt.Sprintf("Spawned subagent for task: %s", task)) } - // Pass callback to manager for async completion notification - result, err := t.manager.Spawn(ctx, task, label, agentID, channel, chatID, cb) - if err != nil { - return ErrorResult(fmt.Sprintf("failed to spawn subagent: %v", err)) - } - - // Return AsyncResult since the task runs in background - return AsyncResult(result) + // Fallback: spawner not configured + return ErrorResult("Subagent manager not configured") } diff --git a/pkg/tools/spawn_test.go b/pkg/tools/spawn_test.go index 43223b8d..fda6bbd8 100644 --- a/pkg/tools/spawn_test.go +++ b/pkg/tools/spawn_test.go @@ -6,6 +6,24 @@ import ( "testing" ) +// mockSpawner implements SubTurnSpawner for testing +type mockSpawner struct{} + +func (m *mockSpawner) SpawnSubTurn(ctx context.Context, cfg SubTurnConfig) (*ToolResult, error) { + // Extract task from system prompt for response + task := cfg.SystemPrompt + if strings.Contains(task, "Task: ") { + parts := strings.Split(task, "Task: ") + if len(parts) > 1 { + task = parts[1] + } + } + return &ToolResult{ + ForLLM: "Task completed: " + task, + ForUser: "Task completed", + }, nil +} + func TestSpawnTool_Execute_EmptyTask(t *testing.T) { provider := &MockLLMProvider{} manager := NewSubagentManager(provider, "test-model", "/tmp/test") @@ -44,6 +62,7 @@ func TestSpawnTool_Execute_ValidTask(t *testing.T) { provider := &MockLLMProvider{} manager := NewSubagentManager(provider, "test-model", "/tmp/test") tool := NewSpawnTool(manager) + tool.SetSpawner(&mockSpawner{}) ctx := context.Background() args := map[string]any{ diff --git a/pkg/tools/subagent.go b/pkg/tools/subagent.go index c37a5ee0..9a1a8b80 100644 --- a/pkg/tools/subagent.go +++ b/pkg/tools/subagent.go @@ -4,11 +4,34 @@ import ( "context" "fmt" "sync" + "sync/atomic" "time" "github.com/sipeed/picoclaw/pkg/providers" ) +// SubTurnSpawner is an interface for spawning sub-turns. +// This avoids circular dependency between tools and agent packages. +type SubTurnSpawner interface { + SpawnSubTurn(ctx context.Context, cfg SubTurnConfig) (*ToolResult, error) +} + +// SubTurnConfig holds configuration for spawning a sub-turn. +type SubTurnConfig struct { + Model string + Tools []Tool + SystemPrompt string + MaxTokens int + Temperature float64 + Async bool // true for async (spawn), false for sync (subagent) + Critical bool // continue running after parent finishes gracefully + Timeout time.Duration // 0 = use default (5 minutes) + MaxContextRunes int // 0 = auto, -1 = no limit, >0 = explicit limit + ActualSystemPrompt string + InitialMessages []providers.Message + InitialTokenBudget *atomic.Int64 // Shared token budget for team members; nil if no budget +} + type SubagentTask struct { ID string Task string @@ -21,6 +44,15 @@ type SubagentTask struct { Created int64 } +type SpawnSubTurnFunc func( + ctx context.Context, + task, label, agentID string, + tools *ToolRegistry, + maxTokens int, + temperature float64, + hasMaxTokens, hasTemperature bool, +) (*ToolResult, error) + type SubagentManager struct { tasks map[string]*SubagentTask mu sync.RWMutex @@ -34,6 +66,7 @@ type SubagentManager struct { hasMaxTokens bool hasTemperature bool nextID int + spawner SpawnSubTurnFunc } func NewSubagentManager( @@ -51,6 +84,12 @@ func NewSubagentManager( } } +func (sm *SubagentManager) SetSpawner(spawner SpawnSubTurnFunc) { + sm.mu.Lock() + defer sm.mu.Unlock() + sm.spawner = spawner +} + // SetLLMOptions sets max tokens and temperature for subagent LLM calls. func (sm *SubagentManager) SetLLMOptions(maxTokens int, temperature float64) { sm.mu.Lock() @@ -108,22 +147,16 @@ func (sm *SubagentManager) Spawn( return fmt.Sprintf("Spawned subagent for task: %s", task), nil } -func (sm *SubagentManager) runTask(ctx context.Context, task *SubagentTask, callback AsyncCallback) { - // Build system prompt for subagent - systemPrompt := `You are a subagent. Complete the given task independently and report the result. -You have access to tools - use them as needed to complete your task. -After completing the task, provide a clear summary of what was done.` - - messages := []providers.Message{ - { - Role: "system", - Content: systemPrompt, - }, - { - Role: "user", - Content: task.Task, - }, - } +func (sm *SubagentManager) runTask( + ctx context.Context, + task *SubagentTask, + callback AsyncCallback, +) { + task.Status = "running" + task.Created = time.Now().UnixMilli() + // TODO(eventbus): once subagents are modeled as child turns inside + // pkg/agent, emit SubTurnEnd and SubTurnResultDelivered from the parent + // AgentLoop instead of this legacy manager. // Check if context is already canceled before starting select { @@ -136,8 +169,8 @@ After completing the task, provide a clear summary of what was done.` default: } - // Run tool loop with access to tools sm.mu.RLock() + spawner := sm.spawner tools := sm.tools maxIter := sm.maxIterations maxTokens := sm.maxTokens @@ -146,27 +179,69 @@ After completing the task, provide a clear summary of what was done.` hasTemperature := sm.hasTemperature sm.mu.RUnlock() - var llmOptions map[string]any - if hasMaxTokens || hasTemperature { - llmOptions = map[string]any{} - if hasMaxTokens { - llmOptions["max_tokens"] = maxTokens + var result *ToolResult + var err error + + if spawner != nil { + result, err = spawner( + ctx, + task.Task, + task.Label, + task.AgentID, + tools, + maxTokens, + temperature, + hasMaxTokens, + hasTemperature, + ) + } else { + // Fallback to legacy RunToolLoop + systemPrompt := `You are a subagent. Complete the given task independently and report the result. +You have access to tools - use them as needed to complete your task. +After completing the task, provide a clear summary of what was done.` + + messages := []providers.Message{ + {Role: "system", Content: systemPrompt}, + {Role: "user", Content: task.Task}, } - if hasTemperature { - llmOptions["temperature"] = temperature + + var llmOptions map[string]any + if hasMaxTokens || hasTemperature { + llmOptions = map[string]any{} + if hasMaxTokens { + llmOptions["max_tokens"] = maxTokens + } + if hasTemperature { + llmOptions["temperature"] = temperature + } + } + + var loopResult *ToolLoopResult + loopResult, err = RunToolLoop(ctx, ToolLoopConfig{ + Provider: sm.provider, + Model: sm.defaultModel, + Tools: tools, + MaxIterations: maxIter, + LLMOptions: llmOptions, + }, messages, task.OriginChannel, task.OriginChatID) + + if err == nil { + result = &ToolResult{ + ForLLM: fmt.Sprintf( + "Subagent '%s' completed (iterations: %d): %s", + task.Label, + loopResult.Iterations, + loopResult.Content, + ), + ForUser: loopResult.Content, + Silent: false, + IsError: false, + Async: false, + } } } - loopResult, err := RunToolLoop(ctx, ToolLoopConfig{ - Provider: sm.provider, - Model: sm.defaultModel, - Tools: tools, - MaxIterations: maxIter, - LLMOptions: llmOptions, - }, messages, task.OriginChannel, task.OriginChatID) - sm.mu.Lock() - var result *ToolResult defer func() { sm.mu.Unlock() // Call callback if provided and result is set @@ -193,19 +268,7 @@ After completing the task, provide a clear summary of what was done.` } } else { task.Status = "completed" - task.Result = loopResult.Content - result = &ToolResult{ - ForLLM: fmt.Sprintf( - "Subagent '%s' completed (iterations: %d): %s", - task.Label, - loopResult.Iterations, - loopResult.Content, - ), - ForUser: loopResult.Content, - Silent: false, - IsError: false, - Async: false, - } + task.Result = result.ForLLM } } @@ -253,16 +316,28 @@ func (sm *SubagentManager) ListTaskCopies() []SubagentTask { } // SubagentTool executes a subagent task synchronously and returns the result. -// Unlike SpawnTool which runs tasks asynchronously, SubagentTool waits for completion -// and returns the result directly in the ToolResult. +// It directly calls SubTurnSpawner with Async=false for synchronous execution. type SubagentTool struct { - manager *SubagentManager + spawner SubTurnSpawner + defaultModel string + maxTokens int + temperature float64 } func NewSubagentTool(manager *SubagentManager) *SubagentTool { - return &SubagentTool{ - manager: manager, + if manager == nil { + return &SubagentTool{} } + return &SubagentTool{ + defaultModel: manager.defaultModel, + maxTokens: manager.maxTokens, + temperature: manager.temperature, + } +} + +// SetSpawner sets the SubTurnSpawner for direct sub-turn execution. +func (t *SubagentTool) SetSpawner(spawner SubTurnSpawner) { + t.spawner = spawner } func (t *SubagentTool) Name() string { @@ -298,86 +373,64 @@ func (t *SubagentTool) Execute(ctx context.Context, args map[string]any) *ToolRe label, _ := args["label"].(string) - if t.manager == nil { - return ErrorResult("Subagent manager not configured").WithError(fmt.Errorf("manager is nil")) + // Build system prompt for subagent + systemPrompt := fmt.Sprintf( + `You are a subagent. Complete the given task independently and provide a clear, concise result. + +Task: %s`, + task, + ) + + if label != "" { + systemPrompt = fmt.Sprintf( + `You are a subagent labeled "%s". Complete the given task independently and provide a clear, concise result. + +Task: %s`, + label, + task, + ) } - // Build messages for subagent - messages := []providers.Message{ - { - Role: "system", - Content: "You are a subagent. Complete the given task independently and provide a clear, concise result.", - }, - { - Role: "user", - Content: task, - }, - } - - // Use RunToolLoop to execute with tools (same as async SpawnTool) - sm := t.manager - sm.mu.RLock() - tools := sm.tools - maxIter := sm.maxIterations - maxTokens := sm.maxTokens - temperature := sm.temperature - hasMaxTokens := sm.hasMaxTokens - hasTemperature := sm.hasTemperature - sm.mu.RUnlock() - - var llmOptions map[string]any - if hasMaxTokens || hasTemperature { - llmOptions = map[string]any{} - if hasMaxTokens { - llmOptions["max_tokens"] = maxTokens + // Use spawner if available (direct SpawnSubTurn call) + if t.spawner != nil { + result, err := t.spawner.SpawnSubTurn(ctx, SubTurnConfig{ + Model: t.defaultModel, + Tools: nil, // Will inherit from parent via context + SystemPrompt: systemPrompt, + MaxTokens: t.maxTokens, + Temperature: t.temperature, + Async: false, // Synchronous execution + }) + if err != nil { + return ErrorResult(fmt.Sprintf("Subagent execution failed: %v", err)).WithError(err) } - if hasTemperature { - llmOptions["temperature"] = temperature + + // Format result for display + userContent := result.ForLLM + if result.ForUser != "" { + userContent = result.ForUser + } + maxUserLen := 500 + if len(userContent) > maxUserLen { + userContent = userContent[:maxUserLen] + "..." + } + + labelStr := label + if labelStr == "" { + labelStr = "(unnamed)" + } + llmContent := fmt.Sprintf("Subagent task completed:\nLabel: %s\nResult: %s", + labelStr, result.ForLLM) + + return &ToolResult{ + ForLLM: llmContent, + ForUser: userContent, + Silent: false, + IsError: result.IsError, + Async: false, } } - // Fall back to "cli"/"direct" for non-conversation callers (e.g., CLI, tests) - // to preserve the same defaults as the original NewSubagentTool constructor. - channel := ToolChannel(ctx) - if channel == "" { - channel = "cli" - } - chatID := ToolChatID(ctx) - if chatID == "" { - chatID = "direct" - } - - loopResult, err := RunToolLoop(ctx, ToolLoopConfig{ - Provider: sm.provider, - Model: sm.defaultModel, - Tools: tools, - MaxIterations: maxIter, - LLMOptions: llmOptions, - }, messages, channel, chatID) - if err != nil { - return ErrorResult(fmt.Sprintf("Subagent execution failed: %v", err)).WithError(err) - } - - // ForUser: Brief summary for user (truncated if too long) - userContent := loopResult.Content - maxUserLen := 500 - if len(userContent) > maxUserLen { - userContent = userContent[:maxUserLen] + "..." - } - - // ForLLM: Full execution details - labelStr := label - if labelStr == "" { - labelStr = "(unnamed)" - } - llmContent := fmt.Sprintf("Subagent task completed:\nLabel: %s\nIterations: %d\nResult: %s", - labelStr, loopResult.Iterations, loopResult.Content) - - return &ToolResult{ - ForLLM: llmContent, - ForUser: userContent, - Silent: false, - IsError: false, - Async: false, - } + // Fallback: spawner not configured + return ErrorResult("Subagent manager not configured").WithError(fmt.Errorf("spawner not set")) } diff --git a/pkg/tools/subagent_tool_test.go b/pkg/tools/subagent_tool_test.go index 4b6f130a..89ac7d4b 100644 --- a/pkg/tools/subagent_tool_test.go +++ b/pkg/tools/subagent_tool_test.go @@ -48,24 +48,19 @@ func TestSubagentManager_SetLLMOptions_AppliesToRunToolLoop(t *testing.T) { provider := &MockLLMProvider{} manager := NewSubagentManager(provider, "test-model", "/tmp/test") manager.SetLLMOptions(2048, 0.6) - tool := NewSubagentTool(manager) - ctx := WithToolContext(context.Background(), "cli", "direct") - args := map[string]any{"task": "Do something"} - result := tool.Execute(ctx, args) - - if result == nil || result.IsError { - t.Fatalf("Expected successful result, got: %+v", result) + // Verify options are set on manager + if manager.maxTokens != 2048 { + t.Errorf("manager.maxTokens = %d, want 2048", manager.maxTokens) } - - if provider.lastOptions == nil { - t.Fatal("Expected LLM options to be passed, got nil") + if manager.temperature != 0.6 { + t.Errorf("manager.temperature = %f, want 0.6", manager.temperature) } - if provider.lastOptions["max_tokens"] != 2048 { - t.Fatalf("max_tokens = %v, want %d", provider.lastOptions["max_tokens"], 2048) + if !manager.hasMaxTokens { + t.Error("manager.hasMaxTokens should be true") } - if provider.lastOptions["temperature"] != 0.6 { - t.Fatalf("temperature = %v, want %v", provider.lastOptions["temperature"], 0.6) + if !manager.hasTemperature { + t.Error("manager.hasTemperature should be true") } } @@ -150,6 +145,7 @@ func TestSubagentTool_Execute_Success(t *testing.T) { provider := &MockLLMProvider{} manager := NewSubagentManager(provider, "test-model", "/tmp/test") tool := NewSubagentTool(manager) + tool.SetSpawner(&mockSpawner{}) ctx := WithToolContext(context.Background(), "telegram", "chat-123") args := map[string]any{ @@ -204,6 +200,7 @@ func TestSubagentTool_Execute_NoLabel(t *testing.T) { provider := &MockLLMProvider{} manager := NewSubagentManager(provider, "test-model", "/tmp/test") tool := NewSubagentTool(manager) + tool.SetSpawner(&mockSpawner{}) ctx := context.Background() args := map[string]any{ @@ -277,6 +274,7 @@ func TestSubagentTool_Execute_ContextPassing(t *testing.T) { provider := &MockLLMProvider{} manager := NewSubagentManager(provider, "test-model", "/tmp/test") tool := NewSubagentTool(manager) + tool.SetSpawner(&mockSpawner{}) channel := "test-channel" chatID := "test-chat" @@ -302,6 +300,7 @@ func TestSubagentTool_ForUserTruncation(t *testing.T) { provider := &MockLLMProvider{} manager := NewSubagentManager(provider, "test-model", "/tmp/test") tool := NewSubagentTool(manager) + tool.SetSpawner(&mockSpawner{}) ctx := context.Background() diff --git a/pkg/utils/context.go b/pkg/utils/context.go new file mode 100644 index 00000000..2007de9a --- /dev/null +++ b/pkg/utils/context.go @@ -0,0 +1,173 @@ +// PicoClaw - Ultra-lightweight personal AI agent +// Inspired by and based on nanobot: https://github.com/HKUDS/nanobot +// License: MIT +// +// Copyright (c) 2026 PicoClaw contributors + +package utils + +import ( + "encoding/json" + "fmt" + "unicode/utf8" + + "github.com/sipeed/picoclaw/pkg/providers" +) + +// CalculateDefaultMaxContextRunes computes a default context limit based on the model's context window. +// Strategy: Use 75% of the context window and convert to rune estimate. +// +// Token-to-rune conversion ratios (conservative estimates): +// - English: ~4 chars per token +// - Chinese: ~1.5-2 chars per token +// - Mixed: ~3 chars per token (used here for safety) +func CalculateDefaultMaxContextRunes(contextWindow int) int { + if contextWindow <= 0 { + // Conservative fallback when context window is unknown + return 8000 // ~2000 tokens + } + + // Use 75% of context window to leave headroom + targetTokens := int(float64(contextWindow) * 0.75) + + // Convert tokens to runes using conservative ratio + const avgCharsPerToken = 3 + return targetTokens * avgCharsPerToken +} + +// ResolveMaxContextRunes determines the final MaxContextRunes value to use. +// Priority: explicit config > auto-calculate > conservative default +func ResolveMaxContextRunes(configValue, contextWindow int) int { + switch { + case configValue > 0: + // Explicitly configured, use as-is + return configValue + case configValue == -1: + // Explicitly disabled + return -1 + default: + // 0 or unset: auto-calculate + return CalculateDefaultMaxContextRunes(contextWindow) + } +} + +// MeasureContextRunes calculates the total rune count of a message list. +// Includes content, reasoning content, and estimates for tool calls. +func MeasureContextRunes(messages []providers.Message) int { + totalRunes := 0 + for _, msg := range messages { + totalRunes += utf8.RuneCountInString(msg.Content) + totalRunes += utf8.RuneCountInString(msg.ReasoningContent) + + // Tool calls: serialize to JSON and count + if len(msg.ToolCalls) > 0 { + for _, tc := range msg.ToolCalls { + totalRunes += utf8.RuneCountInString(tc.Name) + // Arguments: serialize and count + if argsJSON, err := json.Marshal(tc.Arguments); err == nil { + totalRunes += utf8.RuneCount(argsJSON) + } else { + // Fallback estimate if serialization fails + totalRunes += 100 + } + } + } + + // ToolCallID + totalRunes += utf8.RuneCountInString(msg.ToolCallID) + } + return totalRunes +} + +// TruncateContextSmart intelligently truncates message history to fit within maxRunes. +// +// Strategy: +// 1. Always preserve system messages (they define the agent's behavior) +// 2. Keep the most recent messages (they contain current context) +// 3. Drop older middle messages when necessary +// 4. Insert a truncation notice to inform the LLM +// +// Returns the truncated message list. +func TruncateContextSmart(messages []providers.Message, maxRunes int) []providers.Message { + if len(messages) == 0 { + return messages + } + + // Separate system messages from others + var systemMsgs []providers.Message + var otherMsgs []providers.Message + + for _, msg := range messages { + if msg.Role == "system" { + systemMsgs = append(systemMsgs, msg) + } else { + otherMsgs = append(otherMsgs, msg) + } + } + + // Calculate system message size + systemRunes := 0 + for _, msg := range systemMsgs { + systemRunes += utf8.RuneCountInString(msg.Content) + systemRunes += utf8.RuneCountInString(msg.ReasoningContent) + } + + // Reserve space for truncation notice (estimate ~80 runes) + const truncationNoticeEstimate = 80 + + // Allocate remaining space for other messages + remainingRunes := maxRunes - systemRunes - truncationNoticeEstimate + if remainingRunes <= 0 { + // System messages already exceed limit - return only system messages + return systemMsgs + } + + // Collect recent messages in reverse order until we hit the limit + var keptMsgs []providers.Message + currentRunes := 0 + + for i := len(otherMsgs) - 1; i >= 0; i-- { + msg := otherMsgs[i] + msgRunes := utf8.RuneCountInString(msg.Content) + + utf8.RuneCountInString(msg.ReasoningContent) + + // Estimate tool call size + if len(msg.ToolCalls) > 0 { + for _, tc := range msg.ToolCalls { + msgRunes += utf8.RuneCountInString(tc.Name) + if argsJSON, err := json.Marshal(tc.Arguments); err == nil { + msgRunes += utf8.RuneCount(argsJSON) + } else { + msgRunes += 100 + } + } + } + msgRunes += utf8.RuneCountInString(msg.ToolCallID) + + if currentRunes+msgRunes > remainingRunes { + // Would exceed limit, stop collecting + break + } + + // Prepend to maintain chronological order + keptMsgs = append([]providers.Message{msg}, keptMsgs...) + currentRunes += msgRunes + } + + // If we dropped messages, add a truncation notice + result := systemMsgs + if len(keptMsgs) < len(otherMsgs) { + droppedCount := len(otherMsgs) - len(keptMsgs) + truncationNotice := providers.Message{ + Role: "system", + Content: fmt.Sprintf( + "[Context truncated: %d earlier messages omitted to stay within context limits]", + droppedCount, + ), + } + result = append(result, truncationNotice) + } + + result = append(result, keptMsgs...) + return result +} diff --git a/pkg/utils/context_test.go b/pkg/utils/context_test.go new file mode 100644 index 00000000..450a2924 --- /dev/null +++ b/pkg/utils/context_test.go @@ -0,0 +1,450 @@ +// PicoClaw - Ultra-lightweight personal AI agent +// License: MIT +// +// Copyright (c) 2026 PicoClaw contributors + +package utils + +import ( + "testing" + + "github.com/sipeed/picoclaw/pkg/providers" +) + +func TestCalculateDefaultMaxContextRunes(t *testing.T) { + tests := []struct { + name string + contextWindow int + want int + }{ + { + name: "zero context window uses fallback", + contextWindow: 0, + want: 8000, + }, + { + name: "negative context window uses fallback", + contextWindow: -1, + want: 8000, + }, + { + name: "small context window (4k tokens)", + contextWindow: 4000, + want: 9000, // 4000 * 0.75 * 3 = 9000 + }, + { + name: "medium context window (128k tokens)", + contextWindow: 128000, + want: 288000, // 128000 * 0.75 * 3 = 288000 + }, + { + name: "large context window (1M tokens)", + contextWindow: 1000000, + want: 2250000, // 1000000 * 0.75 * 3 = 2250000 + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := CalculateDefaultMaxContextRunes(tt.contextWindow) + if got != tt.want { + t.Errorf("CalculateDefaultMaxContextRunes(%d) = %d, want %d", + tt.contextWindow, got, tt.want) + } + }) + } +} + +func TestResolveMaxContextRunes(t *testing.T) { + tests := []struct { + name string + configValue int + contextWindow int + want int + }{ + { + name: "explicit positive value", + configValue: 12000, + contextWindow: 4000, + want: 12000, + }, + { + name: "explicit disable (-1)", + configValue: -1, + contextWindow: 4000, + want: -1, + }, + { + name: "zero uses auto-calculate", + configValue: 0, + contextWindow: 4000, + want: 9000, // 4000 * 0.75 * 3 + }, + { + name: "unset (0) with unknown context window", + configValue: 0, + contextWindow: 0, + want: 8000, // fallback + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := ResolveMaxContextRunes(tt.configValue, tt.contextWindow) + if got != tt.want { + t.Errorf("ResolveMaxContextRunes(%d, %d) = %d, want %d", + tt.configValue, tt.contextWindow, got, tt.want) + } + }) + } +} + +func TestMeasureContextRunes(t *testing.T) { + tests := []struct { + name string + messages []providers.Message + want int + }{ + { + name: "empty messages", + messages: []providers.Message{}, + want: 0, + }, + { + name: "single simple message", + messages: []providers.Message{ + {Role: "user", Content: "Hello"}, + }, + want: 5, // "Hello" = 5 runes + }, + { + name: "message with reasoning", + messages: []providers.Message{ + { + Role: "assistant", + Content: "Answer", + ReasoningContent: "Thinking", + }, + }, + want: 14, // "Answer" (6) + "Thinking" (8) = 14 + }, + { + name: "message with tool call", + messages: []providers.Message{ + { + Role: "assistant", + Content: "Using tool", + ToolCalls: []providers.ToolCall{ + { + Name: "test_tool", + Arguments: map[string]any{"key": "value"}, + }, + }, + }, + }, + want: 10 + 9 + 15, // "Using tool" + "test_tool" + {"key":"value"} + }, + { + name: "multiple messages", + messages: []providers.Message{ + {Role: "system", Content: "You are helpful"}, + {Role: "user", Content: "Hi"}, + {Role: "assistant", Content: "Hello!"}, + }, + want: 15 + 2 + 6, // 15 + 2 + 6 = 23 + }, + { + name: "unicode characters", + messages: []providers.Message{ + {Role: "user", Content: "\u4f60\u597d\u4e16\u754c"}, // 4 Chinese characters + }, + want: 4, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := MeasureContextRunes(tt.messages) + if got != tt.want { + t.Errorf("MeasureContextRunes() = %d, want %d", got, tt.want) + } + }) + } +} + +func TestTruncateContextSmart(t *testing.T) { + tests := []struct { + name string + messages []providers.Message + maxRunes int + wantLen int + wantHas []string // Content strings that should be present + wantNot []string // Content strings that should be absent + }{ + { + name: "empty messages", + messages: []providers.Message{}, + maxRunes: 100, + wantLen: 0, + }, + { + name: "no truncation needed", + messages: []providers.Message{ + {Role: "system", Content: "System"}, + {Role: "user", Content: "Hello"}, + }, + maxRunes: 100, + wantLen: 2, + wantHas: []string{"System", "Hello"}, + }, + { + name: "truncate when limit is tight", + messages: []providers.Message{ + {Role: "system", Content: "System"}, + {Role: "user", Content: "Message 1 with some content here"}, + {Role: "assistant", Content: "Response 1 with some content here"}, + {Role: "user", Content: "Message 2 with some content here"}, + {Role: "assistant", Content: "Response 2 with some content here"}, + {Role: "user", Content: "Latest"}, + }, + maxRunes: 120, // Tight limit to force truncation + wantLen: -1, // Don't check exact length, just verify truncation occurred + wantHas: []string{"System", "Latest"}, + wantNot: []string{"Message 1", "Response 1"}, + }, + { + name: "system messages exceed limit", + messages: []providers.Message{ + {Role: "system", Content: "Very long system message"}, + {Role: "user", Content: "User message"}, + }, + maxRunes: 10, // Less than system message + wantLen: 1, // Only system message + wantHas: []string{"Very long system message"}, + wantNot: []string{"User message"}, + }, + { + name: "preserve multiple system messages", + messages: []providers.Message{ + {Role: "system", Content: "Sys1"}, + {Role: "system", Content: "Sys2"}, + {Role: "user", Content: "Old"}, + {Role: "user", Content: "New"}, + }, + maxRunes: 200, // Generous limit + wantLen: 4, // Both system + truncation notice + new + wantHas: []string{"Sys1", "Sys2", "New"}, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := TruncateContextSmart(tt.messages, tt.maxRunes) + + if tt.wantLen >= 0 && len(got) != tt.wantLen { + t.Errorf("TruncateContextSmart() returned %d messages, want %d", + len(got), tt.wantLen) + } + + // Check for expected content + allContent := "" + for _, msg := range got { + allContent += msg.Content + " " + } + + for _, want := range tt.wantHas { + found := false + for _, msg := range got { + if msg.Content == want || containsSubstring(msg.Content, want) { + found = true + break + } + } + if !found { + t.Errorf("Expected content %q not found in truncated messages", want) + } + } + + for _, notWant := range tt.wantNot { + for _, msg := range got { + if containsSubstring(msg.Content, notWant) { + t.Errorf("Unexpected content %q found in truncated messages", notWant) + } + } + } + }) + } +} + +func containsSubstring(s, substr string) bool { + return len(s) >= len(substr) && findSubstring(s, substr) +} + +func findSubstring(s, substr string) bool { + for i := 0; i <= len(s)-len(substr); i++ { + if s[i:i+len(substr)] == substr { + return true + } + } + return false +} + +// TestSubTurnConfigMaxContextRunes verifies that MaxContextRunes configuration +// is properly integrated into the SubTurn execution flow. +func TestSubTurnConfigMaxContextRunes(t *testing.T) { + tests := []struct { + name string + maxContextRunes int + contextWindow int + wantResolved int + }{ + { + name: "default (0) auto-calculates from context window", + maxContextRunes: 0, + contextWindow: 4000, + wantResolved: 9000, // 4000 * 0.75 * 3 + }, + { + name: "explicit value is used", + maxContextRunes: 12000, + contextWindow: 4000, + wantResolved: 12000, + }, + { + name: "disabled (-1) returns -1", + maxContextRunes: -1, + contextWindow: 4000, + wantResolved: -1, + }, + { + name: "fallback when context window unknown", + maxContextRunes: 0, + contextWindow: 0, + wantResolved: 8000, // conservative fallback + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := ResolveMaxContextRunes(tt.maxContextRunes, tt.contextWindow) + if got != tt.wantResolved { + t.Errorf("utils.ResolveMaxContextRunes(%d, %d) = %d, want %d", + tt.maxContextRunes, tt.contextWindow, got, tt.wantResolved) + } + }) + } +} + +// TestContextTruncationFlow verifies the complete context truncation flow: +// 1. Messages accumulate beyond soft limit +// 2. Truncation is triggered +// 3. System messages are preserved +// 4. Recent messages are kept +func TestContextTruncationFlow(t *testing.T) { + // Build a message history that exceeds the limit + messages := []providers.Message{ + {Role: "system", Content: "You are a helpful assistant"}, // ~27 runes + {Role: "user", Content: "First question"}, // ~14 runes + {Role: "assistant", Content: "First answer"}, // ~12 runes + {Role: "user", Content: "Second question"}, // ~15 runes + {Role: "assistant", Content: "Second answer"}, // ~13 runes + {Role: "user", Content: "Third question"}, // ~14 runes + {Role: "assistant", Content: "Third answer"}, // ~12 runes + {Role: "user", Content: "Latest question"}, // ~15 runes + } + + // Total: ~122 runes + totalRunes := MeasureContextRunes(messages) + if totalRunes < 100 { + t.Errorf("Expected total runes > 100, got %d", totalRunes) + } + + // Set limit to 150 runes - should force truncation of old messages + // but preserve system + truncation notice + recent messages + maxRunes := 150 + truncated := TruncateContextSmart(messages, maxRunes) + + // Verify truncation occurred + if len(truncated) >= len(messages) { + t.Errorf("Expected truncation, but got %d messages (original: %d)", + len(truncated), len(messages)) + } + + // Verify system message is preserved + foundSystem := false + for _, msg := range truncated { + if msg.Role == "system" && msg.Content == "You are a helpful assistant" { + foundSystem = true + break + } + } + if !foundSystem { + t.Error("System message was not preserved after truncation") + } + + // Verify latest message is preserved + foundLatest := false + for _, msg := range truncated { + if msg.Content == "Latest question" { + foundLatest = true + break + } + } + if !foundLatest { + t.Error("Latest message was not preserved after truncation") + } + + // Verify truncation notice is present + foundNotice := false + for _, msg := range truncated { + if msg.Role == "system" && containsSubstring(msg.Content, "truncated") { + foundNotice = true + break + } + } + if !foundNotice { + t.Error("Truncation notice was not added") + } + + // Verify result is within limit (with some tolerance for estimation) + resultRunes := MeasureContextRunes(truncated) + if resultRunes > maxRunes+20 { // Allow 20 rune tolerance + t.Errorf("Truncated context (%d runes) significantly exceeds limit (%d runes)", + resultRunes, maxRunes) + } +} + +// TestContextTruncationPreservesToolCalls verifies that tool calls are +// properly handled during context truncation. +func TestContextTruncationPreservesToolCalls(t *testing.T) { + messages := []providers.Message{ + {Role: "system", Content: "System"}, + {Role: "user", Content: "Old message that should be dropped"}, + { + Role: "assistant", + Content: "Recent tool use", + ToolCalls: []providers.ToolCall{ + { + Name: "important_tool", + Arguments: map[string]any{"key": "value"}, + }, + }, + }, + } + + // Set a generous limit that should keep the tool call message + maxRunes := 200 + truncated := TruncateContextSmart(messages, maxRunes) + + // Verify tool call message is preserved + foundToolCall := false + for _, msg := range truncated { + if len(msg.ToolCalls) > 0 && msg.ToolCalls[0].Name == "important_tool" { + foundToolCall = true + break + } + } + if !foundToolCall { + t.Error("Tool call message was not preserved during truncation") + } +} diff --git a/web/backend/api/gateway_test.go b/web/backend/api/gateway_test.go index 5c94f0b8..504d091a 100644 --- a/web/backend/api/gateway_test.go +++ b/web/backend/api/gateway_test.go @@ -596,6 +596,11 @@ func TestGatewayStatusReturnsErrorAfterStartupWindowExpires(t *testing.T) { func TestGatewayStatusReturnsRestartingDuringRestartGap(t *testing.T) { resetGatewayTestState(t) + // Mock health check to return error, so it won't override our "restarting" status + gatewayHealthGet = func(url string, timeout time.Duration) (*http.Response, error) { + return nil, errors.New("mock health check error") + } + configPath := filepath.Join(t.TempDir(), "config.json") h := NewHandler(configPath) mux := http.NewServeMux() @@ -738,6 +743,11 @@ func TestGatewayRestartKeepsOldProcessWhenItDoesNotExitInTime(t *testing.T) { func TestGatewayRestartReturnsErrorStatusWhenReplacementFailsToStart(t *testing.T) { resetGatewayTestState(t) + // Mock health check to return error, so it won't override our "error" status + gatewayHealthGet = func(url string, timeout time.Duration) (*http.Response, error) { + return nil, errors.New("mock health check error") + } + configPath := filepath.Join(t.TempDir(), "config.json") cfg := config.DefaultConfig() cfg.Agents.Defaults.ModelName = cfg.ModelList[0].ModelName diff --git a/web/frontend/src/components/chat/user-message.tsx b/web/frontend/src/components/chat/user-message.tsx index b47806f4..84978e90 100644 --- a/web/frontend/src/components/chat/user-message.tsx +++ b/web/frontend/src/components/chat/user-message.tsx @@ -5,7 +5,7 @@ interface UserMessageProps { export function UserMessage({ content }: UserMessageProps) { return (
-
+ onFieldChange("contextWindow", e.target.value)}
+ placeholder="131072"
+ />
+
+
+ The default general-purpose assistant for everyday conversation, problem
+ solving, and workspace help.
+---
+
+You are Pico, the default assistant for this workspace.
+Your name is PicoClaw 🦞.
+## Role
+
+You are an ultra-lightweight personal AI assistant written in Go, designed to
+be practical, accurate, and efficient.
+
+## Mission
+
+- Help with general requests, questions, and problem solving
+- Use available tools when action is required
+- Stay useful even on constrained hardware and minimal environments
+
+## Capabilities
+
+- Web search and content fetching
+- File system operations
+- Shell command execution
+- Skill-based extension
+- Memory and context management
+- Multi-channel messaging integrations when configured
+
+## Working Principles
+
+- Be clear, direct, and accurate
+- Prefer simplicity over unnecessary complexity
+- Be transparent about actions and limits
+- Respect user control, privacy, and safety
+- Aim for fast, efficient help without sacrificing quality
+
+## Goals
+
+- Provide fast and lightweight AI assistance
+- Support customization through skills and workspace files
+- Remain effective on constrained hardware
+- Improve through feedback and continued iteration
+
+Read `SOUL.md` as part of your identity and communication style.
diff --git a/workspace/AGENTS.md b/workspace/AGENTS.md
deleted file mode 100644
index 5f5fa648..00000000
--- a/workspace/AGENTS.md
+++ /dev/null
@@ -1,12 +0,0 @@
-# Agent Instructions
-
-You are a helpful AI assistant. Be concise, accurate, and friendly.
-
-## Guidelines
-
-- Always explain what you're doing before taking actions
-- Ask for clarification when request is ambiguous
-- Use tools to help accomplish tasks
-- Remember important information in your memory files
-- Be proactive and helpful
-- Learn from user feedback
\ No newline at end of file
diff --git a/workspace/IDENTITY.md b/workspace/IDENTITY.md
deleted file mode 100644
index 20e3e49f..00000000
--- a/workspace/IDENTITY.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# Identity
-
-## Name
-PicoClaw 🦞
-
-## Description
-Ultra-lightweight personal AI assistant written in Go, inspired by nanobot.
-
-## Purpose
-- Provide intelligent AI assistance with minimal resource usage
-- Support multiple LLM providers (OpenAI, Anthropic, Zhipu, etc.)
-- Enable easy customization through skills system
-- Run on minimal hardware ($10 boards, <10MB RAM)
-
-## Capabilities
-
-- Web search and content fetching
-- File system operations (read, write, edit)
-- Shell command execution
-- Multi-channel messaging (Telegram, WhatsApp, Feishu)
-- Skill-based extensibility
-- Memory and context management
-
-## Philosophy
-
-- Simplicity over complexity
-- Performance over features
-- User control and privacy
-- Transparent operation
-- Community-driven development
-
-## Goals
-
-- Provide a fast, lightweight AI assistant
-- Support offline-first operation where possible
-- Enable easy customization and extension
-- Maintain high quality responses
-- Run efficiently on constrained hardware
-
-## License
-MIT License - Free and open source
-
-## Repository
-https://github.com/sipeed/picoclaw
-
-## Contact
-Issues: https://github.com/sipeed/picoclaw/issues
-Discussions: https://github.com/sipeed/picoclaw/discussions
-
----
-
-"Every bit helps, every bit matters."
-- Picoclaw
\ No newline at end of file
diff --git a/workspace/SOUL.md b/workspace/SOUL.md
index 0be8834f..8a6371ff 100644
--- a/workspace/SOUL.md
+++ b/workspace/SOUL.md
@@ -1,6 +1,6 @@
# Soul
-I am picoclaw, a lightweight AI assistant powered by AI.
+I am PicoClaw: calm, helpful, and practical.
## Personality
@@ -8,10 +8,12 @@ I am picoclaw, a lightweight AI assistant powered by AI.
- Concise and to the point
- Curious and eager to learn
- Honest and transparent
+- Calm under uncertainty
## Values
- Accuracy over speed
- User privacy and safety
- Transparency in actions
-- Continuous improvement
\ No newline at end of file
+- Continuous improvement
+- Simplicity over unnecessary complexity
diff --git a/workspace/USER.md b/workspace/USER.md
index 91398a01..9a3419d8 100644
--- a/workspace/USER.md
+++ b/workspace/USER.md
@@ -1,6 +1,6 @@
# User
-Information about user goes here.
+Information about the user goes here.
## Preferences
@@ -18,4 +18,4 @@ Information about user goes here.
- What the user wants to learn from AI
- Preferred interaction style
-- Areas of interest
\ No newline at end of file
+- Areas of interest
+
diff --git a/web/frontend/src/components/config/config-page.tsx b/web/frontend/src/components/config/config-page.tsx
index e533b956..ee24aafa 100644
--- a/web/frontend/src/components/config/config-page.tsx
+++ b/web/frontend/src/components/config/config-page.tsx
@@ -147,6 +147,9 @@ export function ConfigPage() {
const maxTokens = parseIntField(form.maxTokens, "Max tokens", {
min: 1,
})
+ const contextWindow = form.contextWindow.trim()
+ ? parseIntField(form.contextWindow, "Context window", { min: 1 })
+ : undefined
const maxToolIterations = parseIntField(
form.maxToolIterations,
"Max tool iterations",
@@ -201,6 +204,7 @@ export function ConfigPage() {
workspace,
restrict_to_workspace: form.restrictToWorkspace,
max_tokens: maxTokens,
+ context_window: contextWindow,
max_tool_iterations: maxToolIterations,
summarize_message_threshold: summarizeMessageThreshold,
summarize_token_percent: summarizeTokenPercent,
diff --git a/web/frontend/src/components/config/config-sections.tsx b/web/frontend/src/components/config/config-sections.tsx
index 517185ed..d938a93d 100644
--- a/web/frontend/src/components/config/config-sections.tsx
+++ b/web/frontend/src/components/config/config-sections.tsx
@@ -106,6 +106,20 @@ export function AgentDefaultsSection({
/>
+
{content}