feat(api,sdk,docs): add keep_tools for editing strategies

Author: gusye1234

AGENTS.md

@@ -19,6 +19,8 @@ Acontext is a platform for building AI agents with persistent context, observabi
 - CORE: Python + FastAPI + SQLAlchemy/PostgreSQL + pgvector + Redis + RabbitMQ + S3 + OpenAI/Anthropic + OpenTelemetry
 
 ## RULES
+### Find SDKs after modifying API
+When your task is about modify API, always look for the revelant SDKs and see it should be updated.
 ### Find Document after modifying SDKs
 When your task is about implement/update SDKs at `src/client`, always look for the revelant documents and see it should be updated.
 DON't update openapi.json, or swagger.json/yaml. those are artifacts generated by programs, no need to manually edit them.

docs/engineering/editing.mdx

@@ -153,6 +153,7 @@ This strategy will replace the oldest tool results' content with a placeholder t
 **Parameters:**
 - `keep_recent_n_tool_results` (optional, default: 3): Number of most recent tool results to keep with original content
 - `tool_result_placeholder` (optional, default: "Done"): Custom text to replace old tool results with
+- `keep_tools` (optional): List of tool names that should never have their results removed. Tool results from these tools are always kept regardless of `keep_recent_n_tool_results`
 
 **Example Output:**
 
@@ -237,6 +238,7 @@ This is particularly useful when you have many tool calls in your session histor
 
 **Parameters:**
 - `keep_recent_n_tool_calls` (optional, default: 3): Number of most recent tool calls to keep with full parameters
+- `keep_tools` (optional): List of tool names that should never have their parameters removed. Tool calls for these tools always keep their full parameters regardless of `keep_recent_n_tool_calls`
 
 **How it works:**
 - Keeps the most recent N tool calls with their original parameters

src/client/acontext-py/src/acontext/types/session.py

@@ -13,10 +13,13 @@ class RemoveToolResultParams(TypedDict, total=False):
             Defaults to 3 if not specified.
         tool_result_placeholder: Custom text to replace old tool results with.
             Defaults to "Done" if not specified.
+        keep_tools: List of tool names that should never have their results removed.
+            Tool results from these tools are always kept regardless of keep_recent_n_tool_results.
     """
 
     keep_recent_n_tool_results: NotRequired[int]
     tool_result_placeholder: NotRequired[str]
+    keep_tools: NotRequired[list[str]]
 
 
 class RemoveToolResultStrategy(TypedDict):
@@ -36,9 +39,12 @@ class RemoveToolCallParamsParams(TypedDict, total=False):
     Attributes:
         keep_recent_n_tool_calls: Number of most recent tool calls to keep with full parameters.
             Defaults to 3 if not specified.
+        keep_tools: List of tool names that should never have their parameters removed.
+            Tool calls for these tools always keep their full parameters regardless of keep_recent_n_tool_calls.
     """
 
     keep_recent_n_tool_calls: NotRequired[int]
+    keep_tools: NotRequired[list[str]]
 
 
 class RemoveToolCallParamsStrategy(TypedDict):

src/client/acontext-ts/src/types/session.ts

@@ -162,6 +162,12 @@ export const RemoveToolResultParamsSchema = z.object({
    * @default "Done"
    */
   tool_result_placeholder: z.string().optional(),
+
+  /**
+   * List of tool names that should never have their results removed.
+   * Tool results from these tools are always kept regardless of keep_recent_n_tool_results.
+   */
+  keep_tools: z.array(z.string()).optional(),
 });
 
 export type RemoveToolResultParams = z.infer<typeof RemoveToolResultParamsSchema>;
@@ -175,6 +181,12 @@ export const RemoveToolCallParamsParamsSchema = z.object({
    * @default 3
    */
   keep_recent_n_tool_calls: z.number().optional(),
+
+  /**
+   * List of tool names that should never have their parameters removed.
+   * Tool calls for these tools always keep their full parameters regardless of keep_recent_n_tool_calls.
+   */
+  keep_tools: z.array(z.string()).optional(),
 });
 export type RemoveToolCallParamsParams = z.infer<typeof RemoveToolCallParamsParamsSchema>;
 

src/server/api/go/internal/pkg/editor/strategy_remove_tool_call_params.go

@@ -9,6 +9,7 @@ import (
 // RemoveToolCallParamsStrategy removes parameters from old tool-call parts
 type RemoveToolCallParamsStrategy struct {
 	KeepRecentN int
+	KeepTools   []string // Tool names that should never have their parameters removed
 }
 
 // Name returns the strategy name
@@ -18,12 +19,19 @@ func (s *RemoveToolCallParamsStrategy) Name() string {
 
 // Apply removes input parameters from old tool-call parts
 // Keeps the most recent N tool-call parts with their original parameters
+// Also keeps parameters for tools listed in KeepTools
 func (s *RemoveToolCallParamsStrategy) Apply(messages []model.Message) ([]model.Message, error) {
 	if s.KeepRecentN < 0 {
 		return nil, fmt.Errorf("keep_recent_n_tool_calls must be >= 0, got %d", s.KeepRecentN)
 	}
 
-	// Collect all tool-call parts with their positions
+	// Build a set of tool names to keep for O(1) lookup
+	keepToolsSet := make(map[string]bool)
+	for _, toolName := range s.KeepTools {
+		keepToolsSet[toolName] = true
+	}
+
+	// Collect all tool-call parts with their positions, excluding those in KeepTools
 	type toolCallPosition struct {
 		messageIdx int
 		partIdx    int
@@ -33,6 +41,15 @@ func (s *RemoveToolCallParamsStrategy) Apply(messages []model.Message) ([]model.
 	for msgIdx, msg := range messages {
 		for partIdx, part := range msg.Parts {
 			if part.Type == "tool-call" {
+				// Check if this tool call should be kept based on KeepTools
+				if part.Meta != nil {
+					if toolName, ok := part.Meta["name"].(string); ok {
+						if keepToolsSet[toolName] {
+							// Skip this tool call - its parameters should always be kept
+							continue
+						}
+					}
+				}
 				toolCallPositions = append(toolCallPositions, toolCallPosition{
 					messageIdx: msgIdx,
 					partIdx:    partIdx,
@@ -75,7 +92,26 @@ func createRemoveToolCallParamsStrategy(params map[string]interface{}) (EditStra
 		}
 	}
 
+	// Get keep_tools list (tool names that should never have their parameters removed)
+	var keepTools []string
+	if keepToolsValue, ok := params["keep_tools"]; ok {
+		if keepToolsArr, ok := keepToolsValue.([]interface{}); ok {
+			for _, v := range keepToolsArr {
+				if toolName, ok := v.(string); ok {
+					keepTools = append(keepTools, toolName)
+				} else {
+					return nil, fmt.Errorf("keep_tools must be an array of strings, got element of type %T", v)
+				}
+			}
+		} else if keepToolsStrArr, ok := keepToolsValue.([]string); ok {
+			keepTools = keepToolsStrArr
+		} else {
+			return nil, fmt.Errorf("keep_tools must be an array of strings, got %T", keepToolsValue)
+		}
+	}
+
 	return &RemoveToolCallParamsStrategy{
 		KeepRecentN: keepRecentNInt,
+		KeepTools:   keepTools,
 	}, nil
 }

src/server/api/go/internal/pkg/editor/strategy_remove_tool_call_params_test.go

@@ -170,4 +170,236 @@ func TestRemoveToolCallParamsStrategy_Apply(t *testing.T) {
 		assert.NoError(t, err)
 		assert.Nil(t, result[0].Parts[0].Meta)
 	})
+
+	t.Run("keep_tools prevents removal of specified tool call params", func(t *testing.T) {
+		messages := []model.Message{
+			{
+				Parts: []model.Part{
+					{
+						Type: "tool-call",
+						Meta: map[string]any{
+							"id":        "call_1",
+							"name":      "important_tool",
+							"arguments": `{"key": "important_value"}`,
+						},
+					},
+				},
+			},
+			{
+				Parts: []model.Part{
+					{
+						Type: "tool-call",
+						Meta: map[string]any{
+							"id":        "call_2",
+							"name":      "regular_tool",
+							"arguments": `{"key": "regular_value"}`,
+						},
+					},
+				},
+			},
+			{
+				Parts: []model.Part{
+					{
+						Type: "tool-call",
+						Meta: map[string]any{
+							"id":        "call_3",
+							"name":      "important_tool",
+							"arguments": `{"key": "another_important_value"}`,
+						},
+					},
+				},
+			},
+		}
+
+		strategy := &RemoveToolCallParamsStrategy{KeepRecentN: 0, KeepTools: []string{"important_tool"}}
+		result, err := strategy.Apply(messages)
+
+		assert.NoError(t, err)
+		// important_tool calls should keep their arguments
+		assert.Equal(t, `{"key": "important_value"}`, result[0].Parts[0].Meta["arguments"])
+		assert.Equal(t, `{"key": "another_important_value"}`, result[2].Parts[0].Meta["arguments"])
+		// regular_tool should have arguments cleared
+		assert.Equal(t, "{}", result[1].Parts[0].Meta["arguments"])
+	})
+
+	t.Run("keep_tools with keep_recent_n", func(t *testing.T) {
+		messages := []model.Message{
+			{
+				Parts: []model.Part{
+					{
+						Type: "tool-call",
+						Meta: map[string]any{
+							"id":        "call_1",
+							"name":      "regular_tool",
+							"arguments": `{"key": "old_regular"}`,
+						},
+					},
+				},
+			},
+			{
+				Parts: []model.Part{
+					{
+						Type: "tool-call",
+						Meta: map[string]any{
+							"id":        "call_2",
+							"name":      "important_tool",
+							"arguments": `{"key": "important"}`,
+						},
+					},
+				},
+			},
+			{
+				Parts: []model.Part{
+					{
+						Type: "tool-call",
+						Meta: map[string]any{
+							"id":        "call_3",
+							"name":      "regular_tool",
+							"arguments": `{"key": "recent_regular"}`,
+						},
+					},
+				},
+			},
+		}
+
+		// Keep 1 recent regular tool call + all important_tool calls
+		strategy := &RemoveToolCallParamsStrategy{KeepRecentN: 1, KeepTools: []string{"important_tool"}}
+		result, err := strategy.Apply(messages)
+
+		assert.NoError(t, err)
+		// Old regular call should have arguments cleared
+		assert.Equal(t, "{}", result[0].Parts[0].Meta["arguments"])
+		// important_tool should keep arguments
+		assert.Equal(t, `{"key": "important"}`, result[1].Parts[0].Meta["arguments"])
+		// Recent regular call should keep arguments (within keep_recent_n)
+		assert.Equal(t, `{"key": "recent_regular"}`, result[2].Parts[0].Meta["arguments"])
+	})
+
+	t.Run("keep_tools with multiple tool names", func(t *testing.T) {
+		messages := []model.Message{
+			{
+				Parts: []model.Part{
+					{
+						Type: "tool-call",
+						Meta: map[string]any{
+							"id":        "call_1",
+							"name":      "tool_a",
+							"arguments": `{"key": "a"}`,
+						},
+					},
+				},
+			},
+			{
+				Parts: []model.Part{
+					{
+						Type: "tool-call",
+						Meta: map[string]any{
+							"id":        "call_2",
+							"name":      "tool_b",
+							"arguments": `{"key": "b"}`,
+						},
+					},
+				},
+			},
+			{
+				Parts: []model.Part{
+					{
+						Type: "tool-call",
+						Meta: map[string]any{
+							"id":        "call_3",
+							"name":      "tool_c",
+							"arguments": `{"key": "c"}`,
+						},
+					},
+				},
+			},
+		}
+
+		strategy := &RemoveToolCallParamsStrategy{KeepRecentN: 0, KeepTools: []string{"tool_a", "tool_c"}}
+		result, err := strategy.Apply(messages)
+
+		assert.NoError(t, err)
+		// tool_a and tool_c should keep arguments
+		assert.Equal(t, `{"key": "a"}`, result[0].Parts[0].Meta["arguments"])
+		assert.Equal(t, `{"key": "c"}`, result[2].Parts[0].Meta["arguments"])
+		// tool_b should have arguments cleared
+		assert.Equal(t, "{}", result[1].Parts[0].Meta["arguments"])
+	})
+}
+
+func TestCreateRemoveToolCallParamsStrategy(t *testing.T) {
+	t.Run("create with keep_tools parameter", func(t *testing.T) {
+		config := StrategyConfig{
+			Type: "remove_tool_call_params",
+			Params: map[string]interface{}{
+				"keep_tools": []interface{}{"tool1", "tool2"},
+			},
+		}
+
+		strategy, err := CreateStrategy(config)
+
+		assert.NoError(t, err)
+		rtcp, ok := strategy.(*RemoveToolCallParamsStrategy)
+		assert.True(t, ok)
+		assert.Equal(t, []string{"tool1", "tool2"}, rtcp.KeepTools)
+	})
+
+	t.Run("invalid keep_tools type returns error", func(t *testing.T) {
+		config := StrategyConfig{
+			Type: "remove_tool_call_params",
+			Params: map[string]interface{}{
+				"keep_tools": "not_an_array",
+			},
+		}
+
+		_, err := CreateStrategy(config)
+
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "keep_tools must be an array of strings")
+	})
+
+	t.Run("invalid keep_tools element type returns error", func(t *testing.T) {
+		config := StrategyConfig{
+			Type: "remove_tool_call_params",
+			Params: map[string]interface{}{
+				"keep_tools": []interface{}{"valid", 123},
+			},
+		}
+
+		_, err := CreateStrategy(config)
+
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "keep_tools must be an array of strings")
+	})
+
+	t.Run("empty keep_tools is valid", func(t *testing.T) {
+		config := StrategyConfig{
+			Type: "remove_tool_call_params",
+			Params: map[string]interface{}{
+				"keep_tools": []interface{}{},
+			},
+		}
+
+		strategy, err := CreateStrategy(config)
+
+		assert.NoError(t, err)
+		rtcp, ok := strategy.(*RemoveToolCallParamsStrategy)
+		assert.True(t, ok)
+		assert.Empty(t, rtcp.KeepTools)
+	})
+
+	t.Run("default values when no params provided", func(t *testing.T) {
+		config := StrategyConfig{
+			Type:   "remove_tool_call_params",
+			Params: map[string]interface{}{},
+		}
+
+		strategy, err := CreateStrategy(config)
+
+		assert.NoError(t, err)
+		rtcp, ok := strategy.(*RemoveToolCallParamsStrategy)
+		assert.True(t, ok)
+		assert.Equal(t, 3, rtcp.KeepRecentN)
+		assert.Nil(t, rtcp.KeepTools)
+	})
 }