Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

feat(agent): keep long sandbox turns from truncating, overflowing, or rewriting files

wizardchen4c0d42c4cb64
diff --git a/cli/cmd/agent/view.go b/cli/cmd/agent/view.go
index 7edf2c563..c384c0b12 100644
--- a/cli/cmd/agent/view.go
+++ b/cli/cmd/agent/view.go
@@ -146,7 +146,9 @@ func renderAgent(w io.Writer, a *sdk.Agent) {
if c.MaxCompletionTokens != 0 {
llm = append(llm, row{"Max completion tokens", fmt.Sprintf("%d", c.MaxCompletionTokens)})
}
- if c.MaxIterations != 0 {
+ if c.MaxIterations < 0 {
+ llm = append(llm, row{"Max iterations", "unlimited"})
+ } else if c.MaxIterations != 0 {
llm = append(llm, row{"Max iterations", fmt.Sprintf("%d", c.MaxIterations)})
}
if c.AgentMode != "" {
diff --git a/client/agent_manage.go b/client/agent_manage.go
index 136c045ea..e82679356 100644
--- a/client/agent_manage.go
+++ b/client/agent_manage.go
@@ -83,7 +83,7 @@ type AgentConfig struct {
MaxCompletionTokens int `json:"max_completion_tokens"`
Thinking *bool `json:"thinking"`
CitationEnabled *bool `json:"citation_enabled"`
- MaxIterations int `json:"max_iterations"`
+ MaxIterations int `json:"max_iterations"` // -1 = unlimited
LLMCallTimeout int `json:"llm_call_timeout,omitempty"`
AllowedTools []string `json:"allowed_tools"`
MCPSelectionMode string `json:"mcp_selection_mode"`
diff --git a/config/builtin_models.yaml.example b/config/builtin_models.yaml.example
index a873a3bcf..f0a18a24a 100644
--- a/config/builtin_models.yaml.example
+++ b/config/builtin_models.yaml.example
@@ -39,6 +39,7 @@ builtin_models: []
# base_url: ${LLM_BASE_URL}
# api_key: ${LLM_API_KEY}
# provider: ${LLM_PROVIDER} # openai | generic | aliyun | moonshot | ...
+# context_window: 200000 # optional; omit to use the 200K default
#
# - id: builtin-embedding-default
# type: Embedding
@@ -73,3 +74,4 @@ builtin_models: []
# base_url: https://api.openai.com/v1
# api_key: ${OPENAI_API_KEY}
# provider: openai
+# context_window: 200000 # optional; omit to use the 200K default
diff --git a/docs/BUILTIN_MODELS.md b/docs/BUILTIN_MODELS.md
index b4fe9bba2..3b1eb4d8a 100644
--- a/docs/BUILTIN_MODELS.md
+++ b/docs/BUILTIN_MODELS.md
@@ -45,6 +45,7 @@ builtin_models:
base_url: <string>
api_key: <string, supports ${ENV_VAR}>
provider: <string> # openai | generic | moonshot | ...
+ context_window: <int, optional> # 对话/VLM 上下文窗口(token);省略则默认 200000
embedding_parameters: # 仅 Embedding 类型
dimension: <int>
truncate_prompt_tokens: <int>
@@ -64,6 +65,7 @@ builtin_models:
base_url: https://api.openai.com/v1
api_key: ${OPENAI_API_KEY}
provider: openai
+ context_window: 200000
- id: builtin-openai-embeddings
name: text-embedding-3-small
diff --git a/docs/api/agent.md b/docs/api/agent.md
index 4463a427f..a41d46a31 100644
--- a/docs/api/agent.md
+++ b/docs/api/agent.md
@@ -432,7 +432,7 @@ curl --location 'http://localhost:8080/api/v1/agents/placeholders' \
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
-| `max_iterations` | int | 10 | ReAct 最大迭代次数 |
+| `max_iterations` | int | 10 | ReAct 最大迭代次数。`-1` 表示不限制,直到模型自然结束或用户停止;正数上限为 100 |
| `allowed_tools` | []string | - | 允许使用的工具列表 |
| `mcp_selection_mode` | string | - | MCP 服务选择模式:`all`/`selected`/`none` |
| `mcp_services` | []string | - | 选中的 MCP 服务 ID 列表 |
diff --git a/docs/api/tenant.md b/docs/api/tenant.md
index e8bad6655..0a72af541 100644
--- a/docs/api/tenant.md
+++ b/docs/api/tenant.md
@@ -630,7 +630,7 @@ curl --location --request PUT 'http://localhost:8080/api/v1/tenants/kv/agent-con
**约束**:
-- `agent-config`: `max_iterations` 取值范围 `(0, 30]`;`temperature` 取值范围 `[0, 2]`。
+- `agent-config`: `max_iterations` 为正整数时上限 100,`-1` 表示不限制;`temperature` 取值范围 `[0, 2]`。
- `web-search-config`: `max_results` 取值范围 `[1, 50]`。
- `conversation-config`: 包含多项阈值校验(如 `keyword_threshold` / `vector_threshold` ∈ `[0, 1]`,`rerank_threshold` ∈ `[-10, 10]`,`temperature` ∈ `[0, 2]`,`max_completion_tokens` ∈ `[1, 100000]` 等)。
- `retrieval-config`: `embedding_top_k` / `rerank_top_k` ∈ `[0, 200]`;阈值范围同上。
diff --git a/docs/docs.go b/docs/docs.go
index 6037c0e27..76dd2e987 100644
--- a/docs/docs.go
+++ b/docs/docs.go
@@ -17912,7 +17912,7 @@ const docTemplate = `{
"type": "integer"
},
"max_iterations": {
- "description": "===== Agent Mode Settings =====\nMaximum iterations for ReAct loop (only for agent type)",
+ "description": "===== Agent Mode Settings =====\nMaximum ReAct iterations. -1 is unlimited; 0 is unset (default applied).",
"type": "integer"
},
"mcp_auth_wait_timeout": {
diff --git a/docs/swagger.json b/docs/swagger.json
index 6d695c8de..fec4cbeb8 100644
--- a/docs/swagger.json
+++ b/docs/swagger.json
@@ -17905,7 +17905,7 @@
"type": "integer"
},
"max_iterations": {
- "description": "===== Agent Mode Settings =====\nMaximum iterations for ReAct loop (only for agent type)",
+ "description": "===== Agent Mode Settings =====\nMaximum ReAct iterations. -1 is unlimited; 0 is unset (default applied).",
"type": "integer"
},
"mcp_auth_wait_timeout": {
diff --git a/docs/swagger.yaml b/docs/swagger.yaml
index 411b3110c..68de7146d 100644
--- a/docs/swagger.yaml
+++ b/docs/swagger.yaml
@@ -876,7 +876,7 @@ definitions:
max_iterations:
description: |-
===== Agent Mode Settings =====
- Maximum iterations for ReAct loop (only for agent type)
+ Maximum ReAct iterations. -1 is unlimited; 0 is unset (default applied).
type: integer
mcp_auth_wait_timeout:
description: |-
diff --git a/frontend/src/api/agent/index.ts b/frontend/src/api/agent/index.ts
index 1ff670b7e..8c05a5596 100644
--- a/frontend/src/api/agent/index.ts
+++ b/frontend/src/api/agent/index.ts
@@ -49,7 +49,7 @@ export interface CustomAgentConfig {
citation_enabled?: boolean; // 是否在最终回答中输出知识库/网页来源引用(默认开启)
// ===== Agent模式设置 =====
- max_iterations?: number; // 最大迭代次数
+ max_iterations?: number; // 最大迭代次数;-1 表示不限制
llm_call_timeout?: number; // LLM调用超时时间(秒)
allowed_tools?: string[]; // 允许的工具
reflection_enabled?: boolean; // 是否启用反思
diff --git a/frontend/src/api/model/index.ts b/frontend/src/api/model/index.ts
index a5f02c2c6..4ad93f09a 100644
--- a/frontend/src/api/model/index.ts
+++ b/frontend/src/api/model/index.ts
@@ -31,6 +31,9 @@ export interface ModelConfig {
// 会在调用远程模型 API 时附加到每个请求上。Authorization、Content-Type 等保留头会被忽略。
custom_headers?: Record<string, string>;
supports_vision?: boolean; // Whether the model accepts image/multimodal input
+ // 对话/VLM 的上下文窗口(token)。0 或不填表示使用后端默认 200000。
+ context_window?: number;
+ max_output_tokens?: number;
// 后台任务(入库/富化)对该模型的并发上限,按模型 ID 全副本共享。
// 0 或不填表示沿用全局默认(model.max_concurrency);仅对 chat/embedding/vllm 生效。
max_concurrency?: number;
diff --git a/frontend/src/assets/img/context-compaction.svg b/frontend/src/assets/img/context-compaction.svg
new file mode 100644
index 000000000..c69855c43
--- /dev/null
+++ b/frontend/src/assets/img/context-compaction.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 16 16" width="128" height="128">
+ <path fill-rule="evenodd" clip-rule="evenodd" d="M2 7.5H14V8.5H2V7.5Z" fill="#07C05F"/>
+ <path fill-rule="evenodd" clip-rule="evenodd" d="M8 1L11.1213 4.12132L10.4142 4.82843L8.5 2.91421V6H7.5V2.91421L5.58579 4.82843L4.87868 4.12132L8 1Z" fill="#07C05F"/>
+ <path fill-rule="evenodd" clip-rule="evenodd" d="M8 15L4.87868 11.8787L5.58579 11.1716L7.5 13.0858V10H8.5V13.0858L10.4142 11.1716L11.1213 11.8787L8 15Z" fill="#07C05F"/>
+</svg>
diff --git a/frontend/src/components/Input-field.vue b/frontend/src/components/Input-field.vue
index c74fc5a22..1428130ba 100644
--- a/frontend/src/components/Input-field.vue
+++ b/frontend/src/components/Input-field.vue
@@ -17,6 +17,11 @@ import AgentSelector from './AgentSelector.vue';
import { getCaretCoordinates } from '@/utils/caret';
import { getRootZoom, rectToCssPx, cssViewportSize } from '@/utils/zoom';
import { type ModelConfig } from '@/api/model';
+import {
+ formatContextWindow,
+ isDefaultContextWindow,
+ effectiveContextWindow,
+} from '@/utils/contextWindow';
import { type CustomAgent, BUILTIN_QUICK_ANSWER_ID, BUILTIN_SMART_REASONING_ID } from '@/api/agent';
import { useChatResourcesStore } from '@/stores/chatResources';
import { useEditorResourcesStore } from '@/stores/editorResources';
@@ -1058,6 +1063,27 @@ const modelDisplayName = (model: ModelConfig) => {
return displayName || model.name;
};
+const contextWindowTitle = (tokens?: number) => {
+ if (isDefaultContextWindow(tokens)) {
+ return t('model.editor.contextWindowDefaultHint', { value: formatContextWindow(tokens) });
+ }
+ return t('model.editor.contextWindowTokens', { count: effectiveContextWindow(tokens) });
+};
+
+const selectedModelContextLabel = computed(() => {
+ if (!selectedModel.value) return '';
+ return formatContextWindow(selectedModel.value.parameters?.context_window);
+});
+
+const selectedModelContextIsDefault = computed(() => {
+ return isDefaultContextWindow(selectedModel.value?.parameters?.context_window);
+});
+
+const selectedModelContextTitle = computed(() => {
+ if (!selectedModel.value) return '';
+ return contextWindowTitle(selectedModel.value.parameters?.context_window);
+});
+
const updateModelDropdownPosition = () => {
const anchor = modelButtonRef.value;
if (!anchor) {
@@ -1852,6 +1878,13 @@ watch(() => uiStore.showSettingsModal, (visible, prevVisible) => {
}
});
+watch(() => route.path, (path, prev) => {
+ if (prev === '/platform/settings' && path !== '/platform/settings') {
+ loadWebSearchConfig(true);
+ loadChatModels(true);
+ }
+});
+
watch([selectedKbIds, selectedFileIds], ([kbIds, fileIds]) => {
if (!kbIds.length && !fileIds.length) {
closeModelSelector();
@@ -2659,6 +2692,12 @@ defineExpose({
<span class="model-selector-name">
{{ selectedModelDisplayName }}
</span>
+ <span
+ v-if="selectedModelContextLabel"
+ class="model-selector-ctx"
+ :class="{ 'is-default': selectedModelContextIsDefault }"
+ :title="selectedModelContextTitle"
+ >{{ selectedModelContextLabel }}</span>
<svg width="12" height="12" viewBox="0 0 12 12" fill="currentColor" class="model-dropdown-arrow"
:class="{ 'rotate': showModelSelector }">
<path d="M2.5 4.5L6 8L9.5 4.5H2.5Z" />
@@ -2690,6 +2729,11 @@ defineExpose({
<span v-if="model.display_name" class="model-option-raw-name">{{ model.name }}</span>
</div>
</div>
+ <span
+ class="model-option-ctx"
+ :class="{ 'is-default': isDefaultContextWindow(model.parameters?.context_window) }"
+ :title="contextWindowTitle(model.parameters?.context_window)"
+ >{{ formatContextWindow(model.parameters?.context_window) }}</span>
</div>
<div v-if="availableModels.length === 0" class="model-option empty">
{{ $t('input.noModel') }}
@@ -3473,6 +3517,18 @@ const getImgSrc = (url: string) => {
white-space: nowrap;
}
+.model-selector-ctx {
+ flex-shrink: 0;
+ font-size: 11px;
+ font-variant-numeric: tabular-nums;
+ color: var(--td-text-color-placeholder, #999);
+ font-weight: 400;
+
+ &.is-default {
+ opacity: 0.85;
+ }
+}
+
.model-dropdown-arrow {
width: 10px;
height: 10px;
@@ -3577,6 +3633,8 @@ const getImgSrc = (url: string) => {
.model-option {
display: flex;
align-items: center;
+ justify-content: space-between;
+ gap: 8px;
padding: 6px 8px;
cursor: pointer;
transition: background 0.12s;
@@ -3608,8 +3666,8 @@ const getImgSrc = (url: string) => {
display: flex;
align-items: center;
gap: 8px;
- width: 100%;
min-width: 0;
+ flex: 1;
}
.model-option-icon {
@@ -3645,6 +3703,21 @@ const getImgSrc = (url: string) => {
flex-shrink: 0;
}
+.model-option-ctx {
+ flex-shrink: 0;
+ font-size: 11px;
+ font-variant-numeric: tabular-nums;
+ color: var(--td-text-color-secondary);
+ background: var(--td-bg-color-secondarycontainer);
+ padding: 0 6px;
+ border-radius: 4px;
+ line-height: 18px;
+
+ &.is-default {
+ color: var(--td-text-color-placeholder);
+ }
+}
+
/* Agent 模式选择下拉菜单 */
.agent-mode-selector-overlay {
position: fixed;
diff --git a/frontend/src/components/ModelDebugDrawer.vue b/frontend/src/components/ModelDebugDrawer.vue
index 00fd0c6d8..0b562dea1 100644
--- a/frontend/src/components/ModelDebugDrawer.vue
+++ b/frontend/src/components/ModelDebugDrawer.vue
@@ -58,7 +58,12 @@
>
<div class="model-option">
<span class="model-option__name">{{ modelLabel(model) }}</span>
- <span class="model-option__meta">{{ vendorLabel(model) }}</span>
+ <span class="model-option__meta">
+ {{ vendorLabel(model) }}
+ <template v-if="modelHasContextWindow(model.type)">
+ · {{ formatContextWindow(model.parameters?.context_window) }}
+ </template>
+ </span>
</div>
</t-option>
</t-select>
@@ -200,6 +205,10 @@ import SettingDrawer from '@/components/settings/SettingDrawer.vue'
import { debugModel, type ModelConfig, type ModelDebugResult } from '@/api/model'
import { fileSizeVerification } from '@/utils'
import { modelSupportsThinking } from '@/utils/thinkingControl'
+import {
+ formatContextWindow,
+ modelHasContextWindow,
+} from '@/utils/contextWindow'
const props = defineProps<{
visible: boolean
diff --git a/frontend/src/components/ModelEditorDialog.vue b/frontend/src/components/ModelEditorDialog.vue
index 94fcb12d6..e1a917df0 100644
--- a/frontend/src/components/ModelEditorDialog.vue
+++ b/frontend/src/components/ModelEditorDialog.vue
@@ -343,6 +343,14 @@
</div>
</div>
+ <!-- Chat / VLM: context window. Agent compaction sizes itself from this. -->
+ <div v-if="activeModelType === 'chat' || activeModelType === 'vllm'" class="form-item">
+ <label class="form-label">{{ $t('model.editor.contextWindowLabel') }}</label>
+ <t-input v-model.number="formData.contextWindow" type="number" :min="1024" :max="10000000"
+ :placeholder="$t('model.editor.contextWindowPlaceholder', { value: DEFAULT_MODEL_CONTEXT_WINDOW })" />
+ <p class="form-desc">{{ $t('model.editor.contextWindowDesc') }}</p>
+ </div>
+
<!-- Chat: supports vision toggle (VLLM models are inherently multimodal) -->
<div v-if="activeModelType === 'chat'" class="form-item">
<label class="form-label">{{ $t('model.editor.supportsVisionLabel') }}</label>
@@ -411,6 +419,7 @@ import {
resolveThinkingControl,
type ThinkingControlValue,
} from '@/utils/thinkingControl'
+import { DEFAULT_MODEL_CONTEXT_WINDOW } from '@/utils/contextWindow'
import SettingDrawer from '@/components/settings/SettingDrawer.vue'
import CredentialResource, {
type CredentialFieldDef,
@@ -437,6 +446,8 @@ interface ModelFormData {
interfaceType?: 'ollama' | 'openai'
isDefault: boolean
supportsVision?: boolean
+ /** 对话/VLM 上下文窗口(token)。空/0 表示使用默认 200000。 */
+ contextWindow?: number
/** 后台任务对该模型的并发上限;0/undefined 表示沿用全局默认。仅 chat/embedding/vllm 生效。 */
maxConcurrency?: number
/** extra_config.thinking_control — how agent thinking on/off maps to API fields. */
@@ -885,6 +896,7 @@ const formData = ref<ModelFormData>({
interfaceType: 'ollama',
isDefault: false,
supportsVision: false,
+ contextWindow: undefined,
maxConcurrency: undefined,
thinkingControl: defaultThinkingControl('generic', ''),
customHeaders: [],
@@ -1126,6 +1138,7 @@ const resetForm = () => {
interfaceType: undefined,
isDefault: false,
supportsVision: false,
+ contextWindow: undefined,
maxConcurrency: undefined,
thinkingControl: defaultThinkingControl('generic', ''),
customHeaders: [],
diff --git a/frontend/src/components/ModelSelector.vue b/frontend/src/components/ModelSelector.vue
index 70af4e793..b855f5195 100644
--- a/frontend/src/components/ModelSelector.vue
+++ b/frontend/src/components/ModelSelector.vue
@@ -11,6 +11,16 @@
filterable
style="width: 100%;"
>
+ <template v-if="selectedModel && showContextWindow" #valueDisplay>
+ <span class="selected-model">
+ <span class="selected-model__name">{{ modelDisplayName(selectedModel) }}</span>
+ <span
+ class="model-ctx"
+ :class="{ 'model-ctx--default': isDefaultContextWindow(selectedModel.parameters?.context_window) }"
+ :title="contextWindowTitle(selectedModel.parameters?.context_window)"
+ >{{ formatContextWindow(selectedModel.parameters?.context_window) }}</span>
+ </span>
+ </template>
<!-- 已有的模型选项 -->
<t-option
v-for="model in models"
@@ -24,6 +34,12 @@
<span v-if="model.display_name" class="model-raw-name">{{ model.name }}</span>
<t-tag v-if="model.is_builtin" size="small" theme="primary">{{ $t('model.builtinTag') }}</t-tag>
<t-tag v-if="model.is_default" size="small" theme="success">{{ $t('model.defaultTag') }}</t-tag>
+ <span
+ v-if="showContextWindow"
+ class="model-ctx"
+ :class="{ 'model-ctx--default': isDefaultContextWindow(model.parameters?.context_window) }"
+ :title="contextWindowTitle(model.parameters?.context_window)"
+ >{{ formatContextWindow(model.parameters?.context_window) }}</span>
</div>
</t-option>
@@ -44,10 +60,17 @@
<script setup lang="ts">
import { ref, computed, watch, onMounted } from 'vue'
-import { listModels, type ModelConfig } from '@/api/model'
+import { type ModelConfig } from '@/api/model'
+import { useChatResourcesStore } from '@/stores/chatResources'
import { MessagePlugin } from 'tdesign-vue-next'
import { useI18n } from 'vue-i18n'
import { filterModelsByType } from './modelSelectorFilter'
+import {
+ formatContextWindow,
+ isDefaultContextWindow,
+ effectiveContextWindow,
+ modelHasContextWindow,
+} from '@/utils/contextWindow'
interface Props {
modelType: 'KnowledgeQA' | 'Embedding' | 'Rerank' | 'VLLM' | 'ASR'
@@ -75,6 +98,7 @@ const emit = defineEmits<{
const models = ref<ModelConfig[]>([])
const loading = ref(false)
const { t } = useI18n()
+const chatResources = useChatResourcesStore()
const placeholderText = computed(() => {
return props.placeholder || t('model.selectModelPlaceholder')
@@ -85,12 +109,24 @@ const modelDisplayName = (model: ModelConfig) => {
return displayName || model.name
}
-// 监听 allModels / modelType 变化,自动过滤当前类型的模型
-watch(() => [props.allModels, props.modelType] as const, ([newModels]) => {
- if (newModels && Array.isArray(newModels)) {
- models.value = filterModelsByType(newModels, props.modelType)
+const showContextWindow = computed(() => modelHasContextWindow(props.modelType))
+
+const contextWindowTitle = (tokens?: number) => {
+ if (isDefaultContextWindow(tokens)) {
+ return t('model.editor.contextWindowDefaultHint', { value: formatContextWindow(tokens) })
}
-}, { immediate: true })
+ return t('model.editor.contextWindowTokens', { count: effectiveContextWindow(tokens) })
+}
+
+// 外部传入 allModels 时跟着 prop 走;否则用空间级缓存,设置页改完窗口立刻能看见。
+watch(
+ () => [props.allModels, props.modelType, chatResources.allModels] as const,
+ ([newModels]) => {
+ const source = Array.isArray(newModels) ? newModels : chatResources.allModels
+ models.value = filterModelsByType(source, props.modelType)
+ },
+ { immediate: true },
+)
const selectedModel = computed(() => {
if (!props.selectedModelId) return null
@@ -99,20 +135,14 @@ const selectedModel = computed(() => {
// 加载模型列表(仅在未提供 allModels 时调用)
const loadModels = async () => {
- // 如果外部提供了 allModels,则不需要加载
if (props.allModels) {
return
}
-
+
loading.value = true
try {
- const result = await listModels()
- // 前端按类型筛选模型
- if (result && Array.isArray(result)) {
- models.value = filterModelsByType(result, props.modelType)
- } else {
- models.value = []
- }
+ await chatResources.ensureModels()
+ models.value = filterModelsByType(chatResources.allModels, props.modelType)
} catch (error) {
console.error(t('model.loadFailed'), error)
MessagePlugin.error(t('model.loadFailed'))
@@ -183,6 +213,10 @@ onMounted(() => {
text-overflow: ellipsis;
white-space: nowrap;
}
+
+ .model-ctx {
+ margin-left: auto;
+ }
&.add {
.model-name {
@@ -191,4 +225,34 @@ onMounted(() => {
}
}
}
+
+.model-ctx {
+ flex-shrink: 0;
+ font-size: 11px;
+ font-variant-numeric: tabular-nums;
+ color: var(--td-text-color-secondary);
+ background: var(--td-bg-color-secondarycontainer);
+ padding: 0 6px;
+ border-radius: 4px;
+ line-height: 18px;
+
+ &--default {
+ color: var(--td-text-color-placeholder);
+ }
+}
+
+.selected-model {
+ display: inline-flex;
+ align-items: center;
+ gap: 8px;
+ min-width: 0;
+ max-width: 100%;
+
+ &__name {
+ min-width: 0;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ }
+}
</style>
diff --git a/frontend/src/composables/useChatStreamHandler.ts b/frontend/src/composables/useChatStreamHandler.ts
index 71ec58c7c..d591a38db 100644
--- a/frontend/src/composables/useChatStreamHandler.ts
+++ b/frontend/src/composables/useChatStreamHandler.ts
@@ -598,6 +598,27 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
}
break
}
+ case 'context_compacted': {
+ // Shown in the timeline rather than swallowed: after a compaction the
+ // agent no longer sees the earlier rounds, and without a marker that
+ // reads as the model ignoring what it was told.
+ if (!message.agentEventStream) message.agentEventStream = []
+ const d = dataPayload || {}
+ ;(message.agentEventStream as ChatMessage[]).push({
+ type: 'context_compacted',
+ event_id: data.id || `compaction-${Date.now()}`,
+ reason: d.reason,
+ round: d.round,
+ tokens_before: d.tokens_before,
+ tokens_after: d.tokens_after,
+ messages_before: d.messages_before,
+ messages_after: d.messages_after,
+ summary: d.summary,
+ degraded: d.degraded,
+ split_turn: d.split_turn,
+ })
+ break
+ }
case 'tool_approval_required': {
if (!message.agentEventStream) message.agentEventStream = []
const d = dataPayload || {}
@@ -970,7 +991,8 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
data.response_type === 'tool_call' ||
data.response_type === 'tool_result' ||
data.response_type === 'reflection' ||
- data.response_type === 'artifacts_pending'
+ data.response_type === 'artifacts_pending' ||
+ data.response_type === 'context_compacted'
const lastMessage = messagesList[messagesList.length - 1]
const isCurrentlyAgentMode = lastMessage?.isAgentMode === true
diff --git a/frontend/src/i18n/locales/en-US.ts b/frontend/src/i18n/locales/en-US.ts
index f42600963..bfa516f9b 100755
--- a/frontend/src/i18n/locales/en-US.ts
+++ b/frontend/src/i18n/locales/en-US.ts
@@ -823,6 +823,9 @@ export default {
toolCalls: '<strong>{tools}</strong> tool call(s)',
durationSuffix: '<strong>{duration}</strong>',
stepSummarySeparator: ' · ',
+ contextCompacted: 'Compacted context',
+ contextCompactedSummary: '{before} → {after} tokens',
+ contextCompactedDegraded: 'Summary unavailable, raw transcript kept',
title: 'Agents',
subtitle: 'Configure and manage your agents to customize conversation behavior and capabilities',
createAgent: 'Create Agent',
@@ -985,6 +988,8 @@ export default {
rerankModelPlaceholder: 'Select ReRank Model',
rerankModelOptionalHint: 'No RAG knowledge base in current scope, so this is optional. If a RAG knowledge base is added later, the workspace default rerank model will be used as a fallback. Configuring it explicitly is still recommended.',
maxIterations: 'Max Iterations',
+ maxIterationsLimit: 'Limit',
+ maxIterationsUnlimited: 'Unlimited',
allowedTools: 'Allowed Tools',
multiTurn: 'Multi-turn Conversation',
historyTurns: 'History Turns',
@@ -4231,6 +4236,11 @@ export default {
dimensionOverrideDesc: 'Enable only if the provider documentation says this model accepts a dimensions parameter.',
supportsVisionLabel: 'Supports Vision / Multimodal',
supportsVisionDesc: 'Whether the model accepts image and multimodal input',
+ contextWindowLabel: 'Context Window',
+ contextWindowPlaceholder: 'Default {value}',
+ contextWindowDesc: 'How many tokens this model can take in one request. Agent history compaction uses this limit. Leave empty for the default 200000 (200K). Use the provider’s real window — a larger guess means compaction never fires and the provider rejects the request.',
+ contextWindowDefaultHint: 'Unset, using default {value}',
+ contextWindowTokens: '{count} tokens',
maxConcurrencyLabel: 'Background concurrency limit',
maxConcurrencyPlaceholder: '0 = use global default',
maxConcurrencyDesc: 'Caps concurrent background (ingestion/enrichment) calls to this model, shared per model across all replicas. 0 or empty falls back to the global default; interactive chat is never affected.',
@@ -4496,7 +4506,7 @@ export default {
title: 'Model Recommendation'
},
maxIterations: {
- desc: 'Maximum reasoning steps when the Agent executes tasks'
+ desc: 'Caps how many reasoning steps one task may take. Unlimited keeps going until the model stops on its own or you stop it.'
},
thinkingModel: {
desc: 'LLM used for Agent reasoning and planning'
@@ -5604,7 +5614,7 @@ export default {
rewriteSystemPrompt: 'System prompt for question rewriting (leave empty for default)',
rewriteUserPrompt: 'User prompt template for question rewriting (leave empty for default)',
selectTools: 'Select tools available to the Agent',
- maxIterations: 'Maximum reasoning steps when the Agent executes tasks',
+ maxIterations: 'Caps how many reasoning steps one task may take. Unlimited keeps going until the model stops on its own or you stop it.',
kbScope: 'Select the scope of knowledge bases accessible to the agent',
webSearch: 'When enabled, the agent can search the internet for information',
webSearchProvider: 'Specify a search engine for this agent. Leave empty to use the default.',
diff --git a/frontend/src/i18n/locales/ko-KR.ts b/frontend/src/i18n/locales/ko-KR.ts
index 832d2ac92..dfbca04e3 100755
--- a/frontend/src/i18n/locales/ko-KR.ts
+++ b/frontend/src/i18n/locales/ko-KR.ts
@@ -1114,7 +1114,7 @@ export default {
rewriteSystemPrompt: '질문 재작성용 시스템 프롬프트 (비워두면 기본값 사용)',
rewriteUserPrompt: '질문 재작성용 사용자 프롬프트 템플릿 (비워두면 기본값 사용)',
selectTools: 'Agent가 사용할 수 있는 도구를 선택하세요',
- maxIterations: 'Agent가 작업 수행 시 최대 추론 단계 수',
+ maxIterations: 'Agent가 한 작업에서 수행할 최대 추론 단계 수입니다. 「제한 없음」을 선택하면 모델이 스스로 끝나거나 직접 중지할 때까지 계속 실행됩니다.',
kbScope: '에이전트가 접근할 수 있는 지식베이스 범위를 선택하세요',
webSearch: '활성화하면 에이전트가 인터넷에서 정보를 검색할 수 있습니다',
webSearchProvider: '이 에이전트의 검색 엔진을 지정합니다. 비워두면 기본 검색 엔진을 사용합니다',
@@ -2216,7 +2216,7 @@ export default {
desc: 'Agent 추론 및 계획을 위한 LLM 모델'
},
maxIterations: {
- desc: 'Agent가 작업을 실행할 때의 최대 추론 단계 수'
+ desc: 'Agent가 한 작업에서 수행할 최대 추론 단계 수입니다. 「제한 없음」을 선택하면 모델이 스스로 끝나거나 직접 중지할 때까지 계속 실행됩니다.'
},
modelRecommendation: {
title: '모델 추천'
@@ -2371,6 +2371,11 @@ export default {
dimensionOverrideDesc: '제공자 문서에서 이 모델이 dimensions 매개변수를 지원한다고 확인한 경우에만 켜세요.',
supportsVisionLabel: '비전/멀티모달 지원',
supportsVisionDesc: '모델의 이미지 등 멀티모달 입력 지원 여부',
+ contextWindowLabel: '컨텍스트 창',
+ contextWindowPlaceholder: '기본값 {value}',
+ contextWindowDesc: '모델이 한 요청에 수용할 수 있는 토큰 수입니다. 에이전트 대화 압축이 이 한도를 사용합니다. 비워 두면 기본값 200000(200K)을 사용합니다. 공급자 문서의 실제 값을 입력하세요. 더 크게 설정하면 압축이 발생하지 않고 요청이 거부될 수 있습니다.',
+ contextWindowDefaultHint: '설정되지 않음, 기본값 {value} 사용',
+ contextWindowTokens: '{count} 토큰',
maxConcurrencyLabel: '백그라운드 동시 실행 상한',
maxConcurrencyPlaceholder: '0이면 전역 기본값 사용',
maxConcurrencyDesc: '문서 인덱싱/보강 등 백그라운드 작업이 이 모델을 호출하는 동시 실행 수를 제한합니다(모델별로 모든 복제본이 공유). 0 또는 비워 두면 전역 기본값을 사용하며, 대화형 채팅에는 영향을 주지 않습니다.',
@@ -5674,6 +5679,9 @@ export default {
toolCalls: '도구 <strong>{tools}</strong>회 호출',
durationSuffix: '소요 시간 <strong>{duration}</strong>',
stepSummarySeparator: ' · ',
+ contextCompacted: '컨텍스트 압축',
+ contextCompactedSummary: '{before} → {after} 토큰',
+ contextCompactedDegraded: '요약을 사용할 수 없어 원본 기록을 유지했습니다',
title: '에이전트',
subtitle: '에이전트 구성 및 관리, 대화 동작 및 기능 맞춤화',
createAgent: '에이전트 만들기',
@@ -5773,6 +5781,8 @@ export default {
rerankModelPlaceholder: 'ReRank 모델을 선택하세요.',
rerankModelOptionalHint: '현재 범위에 RAG 유형의 지식베이스가 없으므로 선택 사항입니다. 이후 RAG 지식베이스가 추가되면 워크스페이스 기본 ReRank 모델로 자동 폴백되지만, 명시적으로 설정하는 것을 권장합니다.',
maxIterations: '최대 반복 횟수',
+ maxIterationsLimit: '제한',
+ maxIterationsUnlimited: '제한 없음',
allowedTools: '허용된 도구',
multiTurn: '여러 라운드의 대화',
historyTurns: '라운드 수를 유지하세요',
diff --git a/frontend/src/i18n/locales/ru-RU.ts b/frontend/src/i18n/locales/ru-RU.ts
index 1128cb574..c2a664627 100755
--- a/frontend/src/i18n/locales/ru-RU.ts
+++ b/frontend/src/i18n/locales/ru-RU.ts
@@ -1114,7 +1114,7 @@ export default {
rewriteSystemPrompt: 'Системный промпт для перефразирования вопросов (пустое = по умолчанию)',
rewriteUserPrompt: 'Шаблон пользовательского промпта для перефразирования (пустое = по умолчанию)',
selectTools: 'Выберите инструменты, доступные агенту',
- maxIterations: 'Максимальное количество шагов рассуждения при выполнении задач',
+ maxIterations: 'Ограничивает число шагов рассуждения за одну задачу. «Без ограничения» — цикл идёт, пока модель не остановится сама или вы не остановите её.',
kbScope: 'Выберите область баз знаний, доступных агенту',
webSearch: 'При включении агент может искать информацию в интернете',
webSearchProvider: 'Укажите поисковый движок для этого агента. Если оставить пустым, будет использоваться движок по умолчанию',
@@ -2216,7 +2216,7 @@ export default {
desc: 'LLM для рассуждений и планирования'
},
maxIterations: {
- desc: 'Максимальное число шагов рассуждений при выполнении задач'
+ desc: 'Ограничивает число шагов рассуждения за одну задачу. «Без ограничения» — цикл идёт, пока модель не остановится сама или вы не остановите её.'
},
modelRecommendation: {
title: 'Model Recommendation'
@@ -2371,6 +2371,11 @@ export default {
dimensionOverrideDesc: 'Включайте только если документация провайдера подтверждает поддержку параметра dimensions.',
supportsVisionLabel: 'Поддержка визуального / мультимодального ввода',
supportsVisionDesc: 'Поддерживает ли модель изображения и другой мультимодальный ввод',
+ contextWindowLabel: 'Контекстное окно',
+ contextWindowPlaceholder: 'По умолчанию {value}',
+ contextWindowDesc: 'Сколько токенов модель принимает за один запрос. Сжатие истории агента использует этот лимит. Пустое значение — по умолчанию 200000 (200K). Укажите реальное окно провайдера: завышенное значение не запускает сжатие, и провайдер отклоняет запрос.',
+ contextWindowDefaultHint: 'Не задано, используется значение по умолчанию {value}',
+ contextWindowTokens: '{count} токенов',
maxConcurrencyLabel: 'Лимит фоновой параллельности',
maxConcurrencyPlaceholder: '0 — использовать глобальное значение',
maxConcurrencyDesc: 'Ограничивает число одновременных фоновых вызовов (индексация/обогащение) к этой модели, общее для модели по всем репликам. 0 или пусто — используется глобальное значение по умолчанию; интерактивный чат не затрагивается.',
@@ -5674,6 +5679,9 @@ export default {
toolCalls: '<strong>{tools}</strong> вызов(ов) инструментов',
durationSuffix: '<strong>{duration}</strong>',
stepSummarySeparator: ' · ',
+ contextCompacted: 'Контекст сжат',
+ contextCompactedSummary: '{before} → {after} токенов',
+ contextCompactedDegraded: 'Сводка недоступна, сохранена исходная запись',
title: 'Agents',
subtitle: 'Configure and manage your agents to customize conversation behavior and capabilities',
createAgent: 'Create Agent',
@@ -5773,6 +5781,8 @@ export default {
rerankModelPlaceholder: 'Select ReRank Model',
rerankModelOptionalHint: 'В текущей области нет RAG-базы знаний, поэтому поле необязательное. Если RAG-база будет добавлена позже, будет использоваться модель ReRank по умолчанию для пространства; всё же рекомендуется настроить её явно.',
maxIterations: 'Max Iterations',
+ maxIterationsLimit: 'Лимит',
+ maxIterationsUnlimited: 'Без ограничения',
allowedTools: 'Allowed Tools',
multiTurn: 'Multi-turn Conversation',
historyTurns: 'History Turns',
diff --git a/frontend/src/i18n/locales/zh-CN.ts b/frontend/src/i18n/locales/zh-CN.ts
index 92ca1514c..6a9fa34b9 100755
--- a/frontend/src/i18n/locales/zh-CN.ts
+++ b/frontend/src/i18n/locales/zh-CN.ts
@@ -1116,7 +1116,7 @@ export default {
rewriteSystemPrompt: '用于问题改写的系统提示词(留空使用默认)',
rewriteUserPrompt: '用于问题改写的用户提示词模板(留空使用默认)',
selectTools: '选择 Agent 可以使用的工具',
- maxIterations: 'Agent 执行任务时的最大推理步骤数',
+ maxIterations: '限制 Agent 单次任务的推理步数。选「不限制」时会一直跑到模型自然结束或你手动停止。',
kbScope: '选择智能体可访问的知识库范围',
webSearch: '启用后智能体可以搜索互联网获取信息',
webSearchProvider: '为此智能体指定搜索引擎,留空则使用默认搜索引擎',
@@ -2218,7 +2218,7 @@ export default {
desc: '用于 Agent 推理和规划的 LLM 模型'
},
maxIterations: {
- desc: 'Agent 执行任务时的最大推理步骤数'
+ desc: '限制 Agent 单次任务的推理步数。选「不限制」时会一直跑到模型自然结束或你手动停止。'
},
modelRecommendation: {
title: '模型推荐'
@@ -2373,6 +2373,11 @@ export default {
dimensionOverrideDesc: '仅在确认该模型支持 dimensions 参数时开启;默认只使用检测到的实际维度。',
supportsVisionLabel: '支持视觉/多模态',
supportsVisionDesc: '模型是否支持图片等多模态输入',
+ contextWindowLabel: '上下文窗口',
+ contextWindowPlaceholder: '默认 {value}',
+ contextWindowDesc: '该模型一次请求能容纳的 token 数。智能体压缩对话历史会按此上限工作。留空则使用默认 200000(200K)。请按厂商文档填写真实值,填大会导致压缩不触发、上游直接拒绝请求。',
+ contextWindowDefaultHint: '未设置,使用默认 {value}',
+ contextWindowTokens: '{count} tokens',
maxConcurrencyLabel: '后台并发上限',
maxConcurrencyPlaceholder: '0 表示使用全局默认',
maxConcurrencyDesc: '限制文档入库/富化等后台任务对该模型的并发调用数(按模型全副本共享)。0 或留空表示沿用全局默认;不影响交互式对话。',
@@ -5676,6 +5681,9 @@ export default {
toolCalls: '调用 <strong>{tools}</strong> 次工具',
durationSuffix: '耗时 <strong>{duration}</strong>',
stepSummarySeparator: ' · ',
+ contextCompacted: '压缩上下文',
+ contextCompactedSummary: '{before} → {after} tokens',
+ contextCompactedDegraded: '摘要不可用,已保留原始记录',
title: '智能体',
subtitle: '配置和管理您的智能体,自定义对话行为和能力',
createAgent: '创建智能体',
@@ -5775,6 +5783,8 @@ export default {
rerankModelPlaceholder: '请选择 ReRank 模型',
rerankModelOptionalHint: '当前作用域内暂无 RAG 类型知识库,可不填;后续若加入 RAG 知识库,将自动使用空间默认重排模型,仍建议显式配置。',
maxIterations: '最大迭代次数',
+ maxIterationsLimit: '限制',
+ maxIterationsUnlimited: '不限制',
allowedTools: '允许的工具',
multiTurn: '多轮对话',
historyTurns: '保留轮数',
diff --git a/frontend/src/stores/chatResources.ts b/frontend/src/stores/chatResources.ts
index 7a0f44b44..a61e949bc 100644
--- a/frontend/src/stores/chatResources.ts
+++ b/frontend/src/stores/chatResources.ts
@@ -46,6 +46,9 @@ export const useChatResourcesStore = defineStore('chatResources', () => {
// 自己是否仍是最新的那次,避免误清正在飞行的句柄。
let kbAllGen = 0
let agentsAllGen = 0
+ // 模型列表同样用代际挡住过期的 inflight:设置页保存后会 replaceModels,
+ // 不能让保存前发出的 ensureModels 把旧列表写回来。
+ let modelsGen = 0
const agentKbCache = new Map<string, { at: number; data: any[] }>()
const agentKbInflight = new Map<string, Promise<any[]>>()
@@ -203,12 +206,22 @@ export const useChatResourcesStore = defineStore('chatResources', () => {
async function ensureModels(force = false): Promise<void> {
return runOnce('models', force, async () => {
+ const gen = ++modelsGen
const models = await listModels()
+ if (gen !== modelsGen) return
allModels.value = Array.isArray(models) ? models : []
loadedAt.value.models = Date.now()
})
}
+ /** 用刚拉到的列表覆盖缓存(模型增删改之后调用,避免 60s TTL 把旧窗口大小继续展示)。 */
+ function replaceModels(models: ModelConfig[]) {
+ modelsGen++
+ inflight.delete('models')
+ allModels.value = Array.isArray(models) ? models : []
+ loadedAt.value.models = Date.now()
+ }
+
/** @deprecated 使用 ensureModels;保留别名供对话输入栏调用 */
async function ensureChatModels(force = false): Promise<void> {
return ensureModels(force)
@@ -339,6 +352,7 @@ export const useChatResourcesStore = defineStore('chatResources', () => {
kbAllInflight = null
agentsLoadedLocale = ''
bumpAgentsGeneration()
+ modelsGen++
invalidateKnowledgeBaseDetail()
return
}
@@ -356,6 +370,9 @@ export const useChatResourcesStore = defineStore('chatResources', () => {
agentsLoadedLocale = ''
bumpAgentsGeneration()
}
+ if (keys.includes('models')) {
+ modelsGen++
+ }
}
return {
@@ -373,6 +390,7 @@ export const useChatResourcesStore = defineStore('chatResources', () => {
ensureKnowledgeBases,
ensureAgents,
ensureModels,
+ replaceModels,
ensureChatModels,
ensureWebSearchProviders,
ensureSandboxConfigs,
diff --git a/frontend/src/utils/contextWindow.test.ts b/frontend/src/utils/contextWindow.test.ts
new file mode 100644
index 000000000..5fda946a7
--- /dev/null
+++ b/frontend/src/utils/contextWindow.test.ts
@@ -0,0 +1,41 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import {
+ DEFAULT_MODEL_CONTEXT_WINDOW,
+ effectiveContextWindow,
+ formatContextWindow,
+ formatTokenCount,
+ isDefaultContextWindow,
+ modelHasContextWindow,
+} from './contextWindow.ts'
+
+test('effectiveContextWindow falls back to 200K', () => {
+ assert.equal(effectiveContextWindow(undefined), DEFAULT_MODEL_CONTEXT_WINDOW)
+ assert.equal(effectiveContextWindow(0), DEFAULT_MODEL_CONTEXT_WINDOW)
+ assert.equal(effectiveContextWindow(256000), 256000)
+})
+
+test('formatTokenCount uses K/M for round thousands', () => {
+ assert.equal(formatTokenCount(128000), '128K')
+ assert.equal(formatTokenCount(200000), '200K')
+ assert.equal(formatTokenCount(131072), '128K')
+ assert.equal(formatTokenCount(1_000_000), '1M')
+ assert.equal(formatTokenCount(1048576), '1M')
+ assert.equal(formatTokenCount(8192), '8K')
+})
+
+test('formatContextWindow uses the default when unset', () => {
+ assert.equal(formatContextWindow(undefined), '200K')
+ assert.equal(formatContextWindow(128000), '128K')
+})
+
+test('modelHasContextWindow is chat and VLM only', () => {
+ assert.equal(modelHasContextWindow('KnowledgeQA'), true)
+ assert.equal(modelHasContextWindow('VLLM'), true)
+ assert.equal(modelHasContextWindow('chat'), true)
+ assert.equal(modelHasContextWindow('Embedding'), false)
+ assert.equal(modelHasContextWindow('Rerank'), false)
+ assert.equal(isDefaultContextWindow(0), true)
+ assert.equal(isDefaultContextWindow(200000), false)
+})
diff --git a/frontend/src/utils/contextWindow.ts b/frontend/src/utils/contextWindow.ts
new file mode 100644
index 000000000..ea518e538
--- /dev/null
+++ b/frontend/src/utils/contextWindow.ts
@@ -0,0 +1,44 @@
+/** Matches internal/types.DefaultMaxContextTokens. */
+export const DEFAULT_MODEL_CONTEXT_WINDOW = 200000
+
+export function modelHasContextWindow(type?: string): boolean {
+ return type === 'KnowledgeQA' || type === 'VLLM' || type === 'chat' || type === 'vllm'
+}
+
+/** Tokens the backend will actually use: the model's value, or 200K. */
+export function effectiveContextWindow(tokens?: number | null): number {
+ if (typeof tokens === 'number' && tokens > 0) {
+ return tokens
+ }
+ return DEFAULT_MODEL_CONTEXT_WINDOW
+}
+
+export function isDefaultContextWindow(tokens?: number | null): boolean {
+ return !(typeof tokens === 'number' && tokens > 0)
+}
+
+/** Compact label: 128000 → 128K, 200000 → 200K, 1048576 → 1M. */
+export function formatTokenCount(tokens: number): string {
+ if (!Number.isFinite(tokens) || tokens <= 0) {
+ return ''
+ }
+ const n = Math.round(tokens)
+ if (n >= 1_000_000 && n % 1_000_000 === 0) {
+ return `${n / 1_000_000}M`
+ }
+ if (n >= 1000 && n % 1000 === 0) {
+ return `${n / 1000}K`
+ }
+ if (n >= 1024 && n % 1024 === 0) {
+ const k = n / 1024
+ if (k >= 1024 && k % 1024 === 0) {
+ return `${k / 1024}M`
+ }
+ return `${k}K`
+ }
+ return String(n)
+}
+
+export function formatContextWindow(tokens?: number | null): string {
+ return formatTokenCount(effectiveContextWindow(tokens))
+}
diff --git a/frontend/src/views/agent/AgentEditorModal.vue b/frontend/src/views/agent/AgentEditorModal.vue
index 757f0b039..c53201df6 100644
--- a/frontend/src/views/agent/AgentEditorModal.vue
+++ b/frontend/src/views/agent/AgentEditorModal.vue
@@ -706,14 +706,19 @@
</div>
</div>
- <!-- 最大迭代次数(Agent 模式) -->
+ <!-- 最大迭代次数(Agent 模式):正数为上限,-1 为不限制 -->
<div v-if="isAgentMode" class="setting-row">
<div class="setting-info">
<label>{{ $t('agent.editor.maxIterations') }}</label>
<p class="desc">{{ $t('agentEditor.desc.maxIterations') }}</p>
</div>
- <div class="setting-control">
- <t-input-number v-model="formData.config.max_iterations" :min="1" :max="50" theme="column" />
+ <div class="setting-control max-tokens-control">
+ <t-radio-group v-model="maxIterationsMode">
+ <t-radio-button value="limit">{{ $t('agent.editor.maxIterationsLimit') }}</t-radio-button>
+ <t-radio-button value="unlimited">{{ $t('agent.editor.maxIterationsUnlimited') }}</t-radio-button>
+ </t-radio-group>
+ <t-input-number v-if="maxIterationsMode === 'limit'" v-model="formData.config.max_iterations"
+ :min="2" :max="50" theme="column" />
</div>
</div>
@@ -2882,6 +2887,22 @@ const maxCompletionTokensMode = computed({
},
});
+const lastFiniteMaxIterations = ref(10);
+const maxIterationsMode = computed({
+ get: () => (formData.value.config.max_iterations < 0 ? 'unlimited' : 'limit'),
+ set: (mode: 'limit' | 'unlimited') => {
+ if (mode === 'unlimited') {
+ if (formData.value.config.max_iterations > 1) {
+ lastFiniteMaxIterations.value = formData.value.config.max_iterations;
+ }
+ formData.value.config.max_iterations = -1;
+ return;
+ }
+ const restored = lastFiniteMaxIterations.value > 1 ? lastFiniteMaxIterations.value : 10;
+ formData.value.config.max_iterations = restored;
+ },
+});
+
const currentIntentTemplate = computed(() =>
intentPromptTemplates.value.find((template) => template.id === selectedIntent.value),
);
@@ -3426,13 +3447,16 @@ watch(() => props.visible, async (val) => {
// 兼容旧数据:如果没有 agent_mode 字段,根据 allowed_tools 推断
if (!agentData.config.agent_mode) {
- const isAgent = agentData.config.max_iterations > 1 || (agentData.config.allowed_tools && agentData.config.allowed_tools.length > 0);
+ const isAgent = agentData.config.max_iterations < 0 || agentData.config.max_iterations > 1 || (agentData.config.allowed_tools && agentData.config.allowed_tools.length > 0);
agentData.config.agent_mode = isAgent ? 'smart-reasoning' : 'quick-answer';
}
// 设置初始化标志,防止 watch 自动添加工具
isInitializing.value = true;
formData.value = agentData;
+ if (agentData.config.max_iterations > 1) {
+ lastFiniteMaxIterations.value = agentData.config.max_iterations;
+ }
// 初始化知识库选择模式
initKbSelectionMode();
initMcpSelectionMode();
@@ -3709,7 +3733,7 @@ watch(agentMode, (val, _oldVal) => {
}
formData.value.config.allowed_tools = tools;
}
- if (formData.value.config.max_iterations <= 1) {
+ if (formData.value.config.max_iterations >= 0 && formData.value.config.max_iterations <= 1) {
formData.value.config.max_iterations = 10;
}
// 切换到 Agent 模式时,如果系统提示词是快速问答的默认值或为空,替换为 Agent 默认提示词
@@ -3807,6 +3831,12 @@ watch(() => uiStore.showSettingsModal, async (visible, prevVisible) => {
}
});
+watch(() => chatResources.allModels, (list) => {
+ if (props.visible) {
+ allModels.value = list;
+ }
+});
+
const mapKbToOption = (kb: any, shared: boolean, orgName?: string) => {
const strategy = kb.indexing_strategy;
const caps: KBCapabilities | undefined = kb.capabilities;
diff --git a/frontend/src/views/chat/components/AgentStreamDisplay.vue b/frontend/src/views/chat/components/AgentStreamDisplay.vue
index ddd364cd7..204c82fa4 100644
--- a/frontend/src/views/chat/components/AgentStreamDisplay.vue
+++ b/frontend/src/views/chat/components/AgentStreamDisplay.vue
@@ -40,6 +40,25 @@
</div>
</div>
+ <!-- Context Compaction -->
+ <div v-if="event.type === 'context_compacted'" class="tool-event">
+ <div class="action-card">
+ <div class="action-header" @click="toggleEvent(event.event_id)">
+ <div class="action-title">
+ <span class="action-title-icon icon-mask" :style="maskIconStyle(compactionIcon)"
+ aria-hidden="true" />
+ <span class="action-name">{{ $t('agent.contextCompacted') }}</span>
+ <span class="action-summary">{{ compactionSummaryText(event) }}</span>
+ </div>
+ </div>
+ <div v-if="event.summary && isEventExpanded(event.event_id)" class="action-details">
+ <div class="thinking-detail-content markdown-content">
+ <div v-html="renderMarkdownContent(event.summary)"></div>
+ </div>
+ </div>
+ </div>
+ </div>
+
<!-- Thinking Event (streaming / merged). When a round's retracted
preamble was folded in, it becomes the card title and the
reasoning is the expandable body. -->
@@ -252,6 +271,25 @@
</div>
</div>
+ <!-- Context Compaction -->
+ <div v-if="event.type === 'context_compacted'" class="tool-event">
+ <div class="action-card">
+ <div class="action-header" @click="toggleEvent(event.event_id)">
+ <div class="action-title">
+ <span class="action-title-icon icon-mask" :style="maskIconStyle(compactionIcon)"
+ aria-hidden="true" />
+ <span class="action-name">{{ $t('agent.contextCompacted') }}</span>
+ <span class="action-summary">{{ compactionSummaryText(event) }}</span>
+ </div>
+ </div>
+ <div v-if="event.summary && isEventExpanded(event.event_id)" class="action-details">
+ <div class="thinking-detail-content markdown-content">
+ <div v-html="renderMarkdownContent(event.summary)"></div>
+ </div>
+ </div>
+ </div>
+ </div>
+
<!-- Thinking Event (streaming / merged). A folded preamble (retracted
from the answer area) is shown as the card title; the reasoning is
the expandable body. -->
@@ -847,6 +885,7 @@ const handleWikiDrawerClick = (e: MouseEvent) => {
// Import icons
import agentIcon from '@/assets/img/agent.svg';
import thinkingIcon from '@/assets/img/Frame3718.svg';
+import compactionIcon from '@/assets/img/context-compaction.svg';
interface SessionData {
id?: string;
@@ -2635,6 +2674,27 @@ const getPlanStatusSummary = (event: any): string => {
return textParts.length > 0 ? textParts.join(' · ') : '';
};
+/**
+ * One-line caption for a compaction card. The token counts are the point: they
+ * are what tells the user how much of the conversation the agent can no longer
+ * see verbatim.
+ */
+const compactionSummaryText = (event: any): string => {
+ const before = Number(event?.tokens_before) || 0;
+ const after = Number(event?.tokens_after) || 0;
+ const parts: string[] = [];
+ if (before > 0 && after > 0) {
+ parts.push(
+ t('agent.contextCompactedSummary', {
+ before: before.toLocaleString(),
+ after: after.toLocaleString(),
+ }),
+ );
+ }
+ if (event?.degraded) parts.push(t('agent.contextCompactedDegraded'));
+ return parts.join(t('agent.stepSummarySeparator'));
+};
+
/** Render SVG assets in the channel / brand color via CSS mask. */
function maskIconStyle(src: string, size = 18): Record<string, string> {
if (!src) return {}
diff --git a/frontend/src/views/knowledge/KnowledgeBaseEditorModal.vue b/frontend/src/views/knowledge/KnowledgeBaseEditorModal.vue
index 363715d32..0d7ff0334 100644
--- a/frontend/src/views/knowledge/KnowledgeBaseEditorModal.vue
+++ b/frontend/src/views/knowledge/KnowledgeBaseEditorModal.vue
@@ -1604,6 +1604,12 @@ watch(
}
}
)
+
+watch(() => chatResources.allModels, (list) => {
+ if (props.visible) {
+ allModels.value = list || []
+ }
+})
</script>
<style scoped lang="less">
diff --git a/frontend/src/views/settings/ModelSettings.vue b/frontend/src/views/settings/ModelSettings.vue
index 749c12425..f3ab82d9b 100644
--- a/frontend/src/views/settings/ModelSettings.vue
+++ b/frontend/src/views/settings/ModelSettings.vue
@@ -107,6 +107,14 @@
<span class="model-card__sep">·</span>
<span>{{ $t('model.editor.dimensionLabel') }} {{ model.dimension }}</span>
</template>
+ <template v-if="model._modelType === 'chat' || model._modelType === 'vllm'">
+ <span class="model-card__sep">·</span>
+ <span
+ class="model-card__ctx"
+ :class="{ 'model-card__ctx--default': isDefaultContextWindow(model.contextWindow) }"
+ :title="contextWindowTitle(model.contextWindow)"
+ >{{ formatContextWindow(model.contextWindow) }}</span>
+ </template>
<template v-if="model._modelType === 'chat' && model.supportsVision">
<span class="model-card__sep">·</span>
<span class="model-card__vision" :title="$t('model.editor.supportsVisionLabel')"
@@ -284,10 +292,17 @@ import {
import { useAuthStore } from '@/stores/auth'
import { useUIStore } from '@/stores/ui'
import { focusKbEditorSection } from '@/config/contextualGuides'
+import { useChatResourcesStore } from '@/stores/chatResources'
+import {
+ formatContextWindow,
+ isDefaultContextWindow,
+ effectiveContextWindow,
+} from '@/utils/contextWindow'
const { t, te } = useI18n()
const authStore = useAuthStore()
const uiStore = useUIStore()
+const chatResources = useChatResourcesStore()
const router = useRouter()
type ModelType = 'chat' | 'embedding' | 'rerank' | 'vllm' | 'asr'
type FilterType = 'all' | ModelType
@@ -352,6 +367,7 @@ function convertToLegacyFormat(model: ModelConfig) {
supportsDimensionOverride: model.parameters.embedding_parameters?.supports_dimension_override || false,
isBuiltin: model.is_builtin || false,
supportsVision: model.parameters.supports_vision || false,
+ contextWindow: model.parameters.context_window || undefined,
maxConcurrency: model.parameters.max_concurrency,
customHeaders: model.parameters.custom_headers
? Object.entries(model.parameters.custom_headers).map(([key, value]) => ({ key, value: String(value) }))
@@ -441,6 +457,13 @@ const modelDisplayName = (model: any) => {
return displayName || model.name
}
+const contextWindowTitle = (tokens?: number) => {
+ if (isDefaultContextWindow(tokens)) {
+ return t('model.editor.contextWindowDefaultHint', { value: formatContextWindow(tokens) })
+ }
+ return t('model.editor.contextWindowTokens', { count: effectiveContextWindow(tokens) })
+}
+
const emptyHint = computed(() => {
if (activeTypeFilter.value === 'all') return t('modelSettings.chat.empty')
const map: Record<ModelType, string> = {
@@ -459,6 +482,9 @@ const loadModels = async () => {
try {
const models = await listModels()
allModels.value = models
+ // 设置页自己 listModels 之后立刻写回空间级缓存。否则对话输入栏 /
+ // 智能体编辑器会继续拿 60s TTL 里的旧 context_window,刷新页面才对。
+ chatResources.replaceModels(models)
} catch (error: any) {
console.error('加载模型列表失败:', error)
MessagePlugin.error(error.message)
@@ -616,6 +642,10 @@ const handleModelSave = async (modelData: any) => {
} : saveType === 'chat' ? {
supports_vision: modelData.supportsVision ?? false
} : {}),
+ ...((saveType === 'chat' || saveType === 'vllm')
+ && Number(modelData.contextWindow) >= 1024
+ ? { context_window: Math.round(Number(modelData.contextWindow)) }
+ : {}),
// 后台并发上限:仅 chat/embedding/vllm 受治理,>0 才写入(0/空沿用全局默认)。
...(['chat', 'embedding', 'vllm'].includes(saveType)
&& Number(modelData.maxConcurrency) > 0
@@ -1137,6 +1167,14 @@ onMounted(() => {
gap: 3px;
}
+.model-card__ctx {
+ font-variant-numeric: tabular-nums;
+}
+
+.model-card__ctx--default {
+ color: var(--td-text-color-placeholder);
+}
+
.model-card__actions {
flex-shrink: 0;
display: flex;
diff --git a/frontend/src/views/settings/WeKnoraCloudSettings.vue b/frontend/src/views/settings/WeKnoraCloudSettings.vue
index 0ae1488cc..9d46dee6e 100644
--- a/frontend/src/views/settings/WeKnoraCloudSettings.vue
+++ b/frontend/src/views/settings/WeKnoraCloudSettings.vue
@@ -208,6 +208,7 @@ import { ref, computed, onMounted } from 'vue'
import { MessagePlugin } from 'tdesign-vue-next'
import { useI18n } from 'vue-i18n'
import { saveWeKnoraCloudCredentials, getWeKnoraCloudStatus, createModel, listModels } from '@/api/model'
+import { useChatResourcesStore } from '@/stores/chatResources'
import { testEmbeddingModel } from '@/api/initialization'
import {
WKC_MODEL_KINDS,
@@ -220,6 +221,7 @@ import {
} from '@/utils/weknoraCloudModels'
const { t } = useI18n()
+const chatResources = useChatResourcesStore()
const form = ref({ appId: '', appSecret: '' })
const saving = ref(false)
@@ -253,6 +255,7 @@ const refreshExistingKinds = async () => {
try {
const models = await listModels()
existingKinds.value = existingWkcKinds(models)
+ chatResources.replaceModels(models)
} catch {
existingKinds.value = new Set()
}
diff --git a/internal/agent/act.go b/internal/agent/act.go
index 0072ff1f0..e35a50153 100644
--- a/internal/agent/act.go
+++ b/internal/agent/act.go
@@ -6,7 +6,6 @@ import (
"errors"
"fmt"
"sort"
- "strings"
"sync"
"time"
@@ -227,6 +226,19 @@ func (e *AgentEngine) executeToolCalls(
round := iteration + 1
n := len(response.ToolCalls)
+
+ // A completion-token cap cuts the response mid-serialization, so every call
+ // in it may carry incomplete arguments. Running them is worse than failing
+ // them: a truncated write_sandbox_file lands a half-written file and still
+ // reports success, which the model only discovers by reading the file back.
+ if isLengthFinishReason(response.FinishReason) {
+ logger.Warnf(ctx, "[Agent][Round-%d] Response hit the completion-token cap (finish=%s); "+
+ "refusing %d tool call(s) with possibly truncated arguments",
+ round, response.FinishReason, n)
+ e.failTruncatedToolCalls(ctx, response, step, iteration, sessionID)
+ return
+ }
+
logger.Infof(ctx, "[Agent][Round-%d] Executing %d tool call(s)", round, n)
// Use parallel execution when enabled and there are multiple tool calls
@@ -238,31 +250,34 @@ func (e *AgentEngine) executeToolCalls(
for i, tc := range response.ToolCalls {
e.executeSingleToolCall(ctx, tc, i, step, iteration, round, sessionID, assistantMessageID)
}
- annotateLengthTruncatedToolErrors(response.FinishReason, step.ToolCalls)
}
-// truncatedOutputHint explains a failed tool call that the provider cut off at
-// the completion-token cap. It stays tool-neutral: any tool can be the one that
-// got truncated, and naming another tool's fields would send the model chasing
-// arguments the failing call does not have.
-const truncatedOutputHint = "\n\nThe previous model output was cut off at the completion-token limit " +
- "(finish_reason=length), so these arguments are incomplete rather than wrong. " +
- "Retry with a complete JSON object and a smaller payload."
-
-// annotateLengthTruncatedToolErrors appends that explanation to every failed
-// result in the round. Results carry a pointer, so mutating through the slice
-// reaches the caller's tool calls.
-func annotateLengthTruncatedToolErrors(finishReason string, toolCalls []types.ToolCall) {
- if !isLengthFinishReason(finishReason) {
- return
- }
- for i := range toolCalls {
- result := toolCalls[i].Result
- if result == nil || result.Success ||
- strings.Contains(result.Error, "finish_reason=length") {
- continue
+// truncatedArgumentsError is handed to the model instead of a tool result when
+// the arguments were cut off. It stays tool-neutral: any tool can be the one
+// that got truncated, and naming another tool's fields would send the model
+// chasing arguments the failing call does not have.
+const truncatedArgumentsError = "Tool call was not executed: the model output was cut off " +
+ "before the arguments finished, so they are incomplete rather than wrong. " +
+ "Re-issue the call with a complete JSON object. If the payload is large, " +
+ "split it across several smaller calls."
+
+// failTruncatedToolCalls records every call in a truncated response as failed
+// without running any of them, emitting the same events a real execution would
+// so the UI and the transcript stay consistent.
+func (e *AgentEngine) failTruncatedToolCalls(
+ ctx context.Context, response *types.ChatResponse,
+ step *types.AgentStep, iteration int, sessionID string,
+) {
+ for i, tc := range response.ToolCalls {
+ toolCall := types.ToolCall{
+ ID: agenttools.NormalizeToolCallID(tc.ID, tc.Function.Name, i),
+ Name: tc.Function.Name,
+ Args: map[string]any{"_raw": tc.Function.Arguments},
+ ProviderMetadata: tc.ProviderMetadata,
+ Result: &types.ToolResult{Success: false, Error: truncatedArgumentsError},
}
- result.Error += truncatedOutputHint
+ step.ToolCalls = append(step.ToolCalls, toolCall)
+ e.emitToolOutcome(ctx, toolCall, iteration, sessionID)
}
}
@@ -292,58 +307,20 @@ func (e *AgentEngine) executeToolCallsParallel(
}
_ = g.Wait()
- annotateLengthTruncatedToolErrors(response.FinishReason, results)
// Append results and emit events in original order
for _, toolCall := range results {
step.ToolCalls = append(step.ToolCalls, toolCall)
-
- result := toolCall.Result
- if result == nil {
- result = &types.ToolResult{Success: false, Error: "no result"}
- }
-
- e.eventBus.Emit(ctx, event.Event{
- ID: toolCall.ID + "-tool-result",
- Type: event.EventAgentToolResult,
- SessionID: sessionID,
- Data: event.AgentToolResultData{
- ToolCallID: toolCall.ID,
- ToolName: toolCall.Name,
- Output: result.Output,
- Error: result.Error,
- Success: result.Success,
- Duration: toolCall.Duration,
- Iteration: iteration,
- Data: agenttools.SanitizeToolDataForPersist(toolCall.Name, result.Data),
- },
- })
-
- e.eventBus.Emit(ctx, event.Event{
- ID: toolCall.ID + "-tool-exec",
- Type: event.EventAgentTool,
- SessionID: sessionID,
- Data: event.AgentActionData{
- Iteration: iteration,
- ToolName: toolCall.Name,
- ToolInput: toolCall.Args,
- ToolOutput: result.Output,
- Success: result.Success,
- Error: result.Error,
- Duration: toolCall.Duration,
- },
- })
+ e.emitToolOutcome(ctx, toolCall, iteration, sessionID)
}
}
-// executeSingleToolCall runs one tool call sequentially (original behavior).
-func (e *AgentEngine) executeSingleToolCall(
- ctx context.Context, tc types.LLMToolCall, i int,
- step *types.AgentStep, iteration, round int, sessionID, assistantMessageID string,
+// emitToolOutcome publishes the result and action events for one finished tool
+// call. Every path that produces a ToolCall goes through here — sequential,
+// parallel, and refused-as-truncated — so the UI sees one event shape.
+func (e *AgentEngine) emitToolOutcome(
+ ctx context.Context, toolCall types.ToolCall, iteration int, sessionID string,
) {
- toolCall := e.runToolCall(ctx, tc, i, iteration, round, sessionID, assistantMessageID)
- step.ToolCalls = append(step.ToolCalls, toolCall)
-
result := toolCall.Result
if result == nil {
result = &types.ToolResult{Success: false, Error: "no result"}
@@ -381,6 +358,16 @@ func (e *AgentEngine) executeSingleToolCall(
})
}
+// executeSingleToolCall runs one tool call sequentially (original behavior).
+func (e *AgentEngine) executeSingleToolCall(
+ ctx context.Context, tc types.LLMToolCall, i int,
+ step *types.AgentStep, iteration, round int, sessionID, assistantMessageID string,
+) {
+ toolCall := e.runToolCall(ctx, tc, i, iteration, round, sessionID, assistantMessageID)
+ step.ToolCalls = append(step.ToolCalls, toolCall)
+ e.emitToolOutcome(ctx, toolCall, iteration, sessionID)
+}
+
// runToolCall handles argument parsing, execution, logging, and pipeline events for a single tool call.
// It returns the completed ToolCall struct. Safe to call from multiple goroutines.
func (e *AgentEngine) runToolCall(
@@ -395,7 +382,7 @@ func (e *AgentEngine) runToolCall(
var args map[string]any
argsStr := tc.Function.Arguments
if err := json.Unmarshal([]byte(argsStr), &args); err != nil {
- repaired := agenttools.RepairJSON(argsStr)
+ repaired, truncated := agenttools.RepairJSONDetail(argsStr)
if repairErr := json.Unmarshal([]byte(repaired), &args); repairErr != nil {
logger.Errorf(ctx, "%s Failed to parse arguments (repair failed): %v", toolTag, err)
return types.ToolCall{
@@ -413,6 +400,23 @@ func (e *AgentEngine) runToolCall(
},
}
}
+ // Closing off an unterminated string or bracket makes the payload
+ // parse, but the values inside are still the partial ones the provider
+ // managed to emit. Executing that writes half a file or searches half a
+ // query, and the tool reports success either way — so refuse instead.
+ // This is the belt for streams that break without a finish reason,
+ // where the length check in executeToolCalls has nothing to match on.
+ if truncated {
+ logger.Warnf(ctx, "%s Arguments were cut off mid-emission (%d bytes); refusing to execute",
+ toolTag, len(argsStr))
+ return types.ToolCall{
+ ID: tc.ID,
+ Name: tc.Function.Name,
+ Args: map[string]any{"_raw": argsStr},
+ ProviderMetadata: tc.ProviderMetadata,
+ Result: &types.ToolResult{Success: false, Error: truncatedArgumentsError},
+ }
+ }
logger.Warnf(ctx, "%s Repaired malformed JSON arguments", toolTag)
// The initial model-context pass could not inspect malformed JSON.
// Decode the repaired payload before execution, while preserving the
diff --git a/internal/agent/compaction/compaction_test.go b/internal/agent/compaction/compaction_test.go
new file mode 100644
index 000000000..fde395284
--- /dev/null
+++ b/internal/agent/compaction/compaction_test.go
@@ -0,0 +1,382 @@
+package compaction
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "strings"
+ "testing"
+
+ agenttoken "github.com/Tencent/WeKnora/internal/agent/token"
+ "github.com/Tencent/WeKnora/internal/models/chat"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+// stubChat records what the summarizer was asked and returns a canned reply.
+type stubChat struct {
+ response string
+ finishReason string
+ err error
+ calls int
+ prompts []string
+}
+
+func (s *stubChat) Chat(
+ _ context.Context, messages []chat.Message, _ *chat.ChatOptions,
+) (*types.ChatResponse, error) {
+ s.calls++
+ if len(messages) > 1 {
+ s.prompts = append(s.prompts, messages[len(messages)-1].Content)
+ }
+ if s.err != nil {
+ return nil, s.err
+ }
+ return &types.ChatResponse{Content: s.response, FinishReason: s.finishReason}, nil
+}
+
+func (s *stubChat) ChatStream(
+ context.Context, []chat.Message, *chat.ChatOptions,
+) (<-chan types.StreamResponse, error) {
+ return nil, nil
+}
+
+func (s *stubChat) GetModelName() string { return "stub" }
+func (s *stubChat) GetModelID() string { return "stub" }
+
+func newEstimator(t *testing.T) *agenttoken.Estimator {
+ t.Helper()
+ est, err := agenttoken.NewEstimator()
+ require.NoError(t, err)
+ return est
+}
+
+func testSettings() Settings {
+ return Settings{
+ Enabled: true,
+ MaxContextTokens: 40000,
+ ReserveTokens: 8000,
+ KeepRecentTokens: 2000,
+ }
+}
+
+// filler produces text large enough to matter against the token budgets above.
+func filler(n int) string { return strings.Repeat("some conversation content ", n) }
+
+// reactTurn builds what an agent turn actually looks like: one user message
+// followed by many assistant/tool rounds, with no further user message. This
+// is the shape that the previous "never touch the current turn" rule made
+// impossible to compact.
+func reactTurn(rounds int) []chat.Message {
+ msgs := []chat.Message{
+ {Role: "system", Content: "you are an agent"},
+ {Role: "user", Content: "build me a deck"},
+ }
+ for i := 0; i < rounds; i++ {
+ msgs = append(msgs,
+ chat.Message{
+ Role: "assistant",
+ Content: filler(20),
+ ToolCalls: []chat.ToolCall{{
+ ID: "call-" + string(rune('a'+i%26)),
+ Type: "function",
+ Function: chat.FunctionCall{
+ Name: "write_sandbox_file",
+ Arguments: `{"path":"/workspace/out.html","content":"` + filler(40) + `"}`,
+ },
+ }},
+ },
+ chat.Message{
+ Role: "tool",
+ Name: "write_sandbox_file",
+ ToolCallID: "call-" + string(rune('a'+i%26)),
+ Content: filler(30),
+ },
+ )
+ }
+ return msgs
+}
+
+// The regression this package exists for: a single ReAct turn with no second
+// user message must still compact. The old cut rule exempted everything after
+// the last user message, so a twenty-round turn was entirely untouchable and
+// every round paid for a summarization that freed nothing.
+func TestCompactsInsideASingleTurn(t *testing.T) {
+ est := newEstimator(t)
+ llm := &stubChat{response: "## Goal\nbuild a deck"}
+ c := New(llm, est, testSettings())
+ require.NotNil(t, c)
+
+ msgs := reactTurn(40)
+ require.Equal(t, 1, countRole(msgs, "user"), "fixture must have no turn boundary to hide behind")
+
+ result, err := c.Compact(context.Background(), msgs, ReasonThreshold)
+ require.NoError(t, err)
+
+ assert.Greater(t, result.Freed(), 0, "compaction must actually shrink the context")
+ assert.Less(t, result.TokensAfter, result.TokensBefore/2)
+ assert.True(t, result.SplitTurn, "a turn larger than the budget has to be split")
+ assert.Equal(t, "system", result.Messages[0].Role)
+ assert.Equal(t, chat.MessageKindCompactionSummary, result.Messages[1].Kind)
+}
+
+// Cutting mid-turn discards the user's original request, so the prefix gets its
+// own summary. Without it the retained tail is a pile of tool calls with no
+// statement of what they were for.
+func TestSplitTurnSummarizesThePrefixSeparately(t *testing.T) {
+ est := newEstimator(t)
+ llm := &stubChat{response: "summary text"}
+ c := New(llm, est, testSettings())
+
+ result, err := c.Compact(context.Background(), reactTurn(12), ReasonThreshold)
+ require.NoError(t, err)
+
+ require.True(t, result.SplitTurn)
+ assert.Contains(t, result.Summary, "Turn Context (split turn)")
+ require.GreaterOrEqual(t, len(llm.prompts), 1)
+ assert.Contains(t, llm.prompts[len(llm.prompts)-1], "PREFIX of a turn",
+ "the prefix must be summarized with the prefix instructions, not the history ones")
+}
+
+// The retained tail has to stay valid for the provider: a tool result whose
+// originating assistant message was summarized away is rejected outright.
+func TestKeptTailNeverStartsWithAnOrphanToolResult(t *testing.T) {
+ est := newEstimator(t)
+ c := New(&stubChat{response: "s"}, est, testSettings())
+
+ for rounds := 4; rounds <= 40; rounds++ {
+ result, err := c.Compact(context.Background(), reactTurn(rounds), ReasonThreshold)
+ if errors.Is(err, ErrNothingToCompact) {
+ continue // still inside the keep-recent budget
+ }
+ require.NoError(t, err)
+
+ pending := map[string]bool{}
+ for _, msg := range result.Messages {
+ for _, tc := range msg.ToolCalls {
+ pending[tc.ID] = true
+ }
+ if msg.Role == "tool" {
+ assert.True(t, pending[msg.ToolCallID],
+ "rounds=%d: tool result %s has no preceding call", rounds, msg.ToolCallID)
+ }
+ }
+ }
+}
+
+// The keep-recent budget is a ceiling. Treating it as a floor — stop at the
+// first message that reaches the budget and keep that message too — is what
+// made compaction fire every couple of rounds: one knowledge_search result is
+// routinely larger than the whole budget, so the retained tail overshot and
+// left almost no headroom before the next threshold crossing.
+func TestRetainedTailStaysWithinTheKeepRecentBudget(t *testing.T) {
+ est := newEstimator(t)
+ s := testSettings()
+ c := New(&stubChat{response: "summary"}, est, s)
+
+ // A search result far larger than the budget, followed by small rounds.
+ msgs := []chat.Message{
+ {Role: "system", Content: "you are an agent"},
+ {Role: "user", Content: "research this"},
+ }
+ for i := 0; i < 6; i++ {
+ id := "search-" + string(rune('a'+i))
+ msgs = append(msgs,
+ chat.Message{Role: "assistant", ToolCalls: []chat.ToolCall{{
+ ID: id, Type: "function",
+ Function: chat.FunctionCall{Name: "knowledge_search", Arguments: `{"query":"x"}`},
+ }}},
+ chat.Message{Role: "tool", Name: "knowledge_search", ToolCallID: id, Content: filler(600)},
+ )
+ }
+
+ result, err := c.Compact(context.Background(), msgs, ReasonThreshold)
+ require.NoError(t, err)
+
+ // Measure the verbatim tail only: the summary is budgeted separately.
+ tail := result.Messages[2:]
+ tailTokens := est.EstimateMessages(tail)
+ assert.LessOrEqual(t, tailTokens, s.Normalize().KeepRecentTokens,
+ "the retained tail must fit the budget, not merely reach it")
+}
+
+// The point of compaction is the headroom it leaves, not the tokens it frees.
+// Landing just under the threshold counts as a successful compaction and still
+// re-triggers a round or two later, which is what the user sees as "constantly
+// compacting".
+func TestCompactionLeavesRoomForSeveralMoreRounds(t *testing.T) {
+ est := newEstimator(t)
+ s := testSettings().Normalize()
+ c := New(&stubChat{response: strings.Repeat("summary line\n", 40)}, est, s)
+
+ result, err := c.Compact(context.Background(), reactTurn(40), ReasonThreshold)
+ require.NoError(t, err)
+
+ assert.Less(t, result.TokensAfter, s.Threshold()*2/3,
+ "post-compaction context must sit well below the threshold, not just under it")
+ assert.False(t, s.ShouldCompact(result.TokensAfter),
+ "a compaction that still leaves the context over the threshold is a no-op")
+}
+
+// Compacting an already-compacted context must report that it cannot help,
+// rather than spending another summarization call to produce the same result.
+// This is what stops the every-round loop.
+func TestSecondCompactionReportsNothingToDo(t *testing.T) {
+ est := newEstimator(t)
+ llm := &stubChat{response: "## Goal\nbuild a deck"}
+ c := New(llm, est, testSettings())
+
+ first, err := c.Compact(context.Background(), reactTurn(12), ReasonThreshold)
+ require.NoError(t, err)
+ callsAfterFirst := llm.calls
+
+ _, err = c.Compact(context.Background(), first.Messages, ReasonThreshold)
+ require.ErrorIs(t, err, ErrNothingToCompact)
+ assert.Equal(t, callsAfterFirst, llm.calls, "a no-op compaction must not call the LLM")
+}
+
+// A summary must never be summarized again: successive passes would degrade it
+// into a summary of a summary. It is instead handed to the update prompt as
+// prior context, and only the messages after it are new input.
+func TestPreviousSummaryIsUpdatedNotResummarized(t *testing.T) {
+ est := newEstimator(t)
+ llm := &stubChat{response: "## Goal\nfirst pass"}
+ c := New(llm, est, testSettings())
+
+ first, err := c.Compact(context.Background(), reactTurn(12), ReasonThreshold)
+ require.NoError(t, err)
+
+ // New work arrives after the compaction, so there is something to fold in.
+ grown := append(append([]chat.Message{}, first.Messages...), reactTurn(10)[2:]...)
+ llm.prompts = nil
+ second, err := c.Compact(context.Background(), grown, ReasonThreshold)
+ require.NoError(t, err)
+
+ prompt := llm.prompts[0]
+ assert.Contains(t, prompt, "<previous-summary>")
+ assert.Contains(t, prompt, "first pass")
+ conversation := prompt[strings.Index(prompt, "<conversation>"):strings.Index(prompt, "</conversation>")]
+ assert.NotContains(t, conversation, "compacted into the following summary",
+ "the prior summary must not re-enter as conversation input")
+
+ assert.Equal(t, 1, countKind(second.Messages, chat.MessageKindCompactionSummary),
+ "exactly one summary survives; they must not stack")
+}
+
+// A summary cut off by the token cap reads like a valid checkpoint but ends
+// mid-section, and every later round inherits that truncation as its only
+// memory. A length stop is a failure, not a result.
+func TestTruncatedSummaryIsRejected(t *testing.T) {
+ est := newEstimator(t)
+ llm := &stubChat{response: "## Goal\nhalf a sum", finishReason: "length"}
+ c := New(llm, est, testSettings())
+
+ result, err := c.Compact(context.Background(), reactTurn(12), ReasonThreshold)
+ require.NoError(t, err)
+
+ assert.True(t, result.Degraded)
+ assert.Contains(t, result.Summary, "Raw conversation archive")
+ assert.NotContains(t, result.Summary, "half a sum")
+}
+
+func TestSummarizerFailureFallsBackToArchive(t *testing.T) {
+ est := newEstimator(t)
+ c := New(&stubChat{err: assert.AnError}, est, testSettings())
+
+ result, err := c.Compact(context.Background(), reactTurn(12), ReasonThreshold)
+ require.NoError(t, err)
+
+ assert.True(t, result.Degraded)
+ assert.Greater(t, result.Freed(), 0, "a degraded summary still has to free room")
+ assert.Contains(t, result.Summary, "Raw conversation archive")
+}
+
+// Sandbox paths are the detail a prose summarizer drops first, and losing them
+// makes the agent rebuild files it already wrote.
+func TestFilePathsSurviveCompaction(t *testing.T) {
+ est := newEstimator(t)
+ c := New(&stubChat{response: "prose that mentions no paths"}, est, testSettings())
+
+ result, err := c.Compact(context.Background(), reactTurn(12), ReasonThreshold)
+ require.NoError(t, err)
+
+ assert.Contains(t, result.Summary, "<modified-files>")
+ assert.Contains(t, result.Summary, "/workspace/out.html")
+}
+
+// A conversation that already fits has nothing outside the keep-recent budget.
+func TestSmallConversationIsLeftAlone(t *testing.T) {
+ est := newEstimator(t)
+ llm := &stubChat{response: "s"}
+ c := New(llm, est, testSettings())
+
+ _, err := c.Compact(context.Background(), []chat.Message{
+ {Role: "system", Content: "sys"},
+ {Role: "user", Content: "hi"},
+ {Role: "assistant", Content: "hello"},
+ }, ReasonThreshold)
+
+ require.ErrorIs(t, err, ErrNothingToCompact)
+ assert.Zero(t, llm.calls)
+}
+
+func TestKeepRecentIsScaledDownOnSmallWindows(t *testing.T) {
+ // A 20k window cannot keep the 20k default and still have room for the
+ // reserve and the summary; keeping it would guarantee a re-trigger.
+ s := Settings{MaxContextTokens: 20000, ReserveTokens: 8000}.Normalize()
+ assert.Equal(t, 3000, s.KeepRecentTokens, "a quarter of the usable window")
+
+ // A large window keeps the default untouched.
+ big := Settings{MaxContextTokens: 200000, ReserveTokens: 16384}.Normalize()
+ assert.Equal(t, DefaultKeepRecentTokens, big.KeepRecentTokens)
+}
+
+func TestThresholdAndShouldCompact(t *testing.T) {
+ s := Settings{Enabled: true, MaxContextTokens: 128000, ReserveTokens: 28672}.Normalize()
+ assert.Equal(t, 128000-28672, s.Threshold())
+ assert.False(t, s.ShouldCompact(s.Threshold()))
+ assert.True(t, s.ShouldCompact(s.Threshold()+1))
+
+ // No window means no budget to enforce.
+ assert.Zero(t, Settings{Enabled: true}.Threshold())
+ assert.False(t, Settings{Enabled: true}.ShouldCompact(1_000_000))
+
+ // Disabled never triggers, whatever the size.
+ assert.False(t, Settings{MaxContextTokens: 1000, ReserveTokens: 100}.
+ Normalize().ShouldCompact(1_000_000))
+}
+
+// Kind is engine bookkeeping; a provider must never see it.
+func TestSummaryKindIsNotSerialized(t *testing.T) {
+ msg := SummaryMessage("text")
+ encoded, err := marshalMessage(msg)
+ require.NoError(t, err)
+ assert.NotContains(t, encoded, "compaction_summary")
+ assert.NotContains(t, encoded, "Kind")
+}
+
+func marshalMessage(msg chat.Message) (string, error) {
+ encoded, err := json.Marshal(msg)
+ return string(encoded), err
+}
+
+func countRole(msgs []chat.Message, role string) int {
+ n := 0
+ for _, m := range msgs {
+ if m.Role == role {
+ n++
+ }
+ }
+ return n
+}
+
+func countKind(msgs []chat.Message, kind chat.MessageKind) int {
+ n := 0
+ for _, m := range msgs {
+ if m.Kind == kind {
+ n++
+ }
+ }
+ return n
+}
diff --git a/internal/agent/compaction/compactor.go b/internal/agent/compaction/compactor.go
new file mode 100644
index 000000000..c54b86e88
--- /dev/null
+++ b/internal/agent/compaction/compactor.go
@@ -0,0 +1,245 @@
+package compaction
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "strings"
+ "time"
+
+ agenttoken "github.com/Tencent/WeKnora/internal/agent/token"
+ "github.com/Tencent/WeKnora/internal/models/chat"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+const (
+ // maxSummarizationAttempts bounds the retries for one compaction. Each
+ // attempt is a full LLM round-trip, and a compaction that keeps failing is
+ // better served by the raw archive than by stalling the turn.
+ maxSummarizationAttempts = 2
+
+ // summarizationTimeout is the per-attempt budget for a summarization call.
+ summarizationTimeout = 60 * time.Second
+
+ // llmCallLabel identifies compaction traffic in tracing and usage
+ // accounting, separating it from the agent's own reasoning rounds.
+ llmCallLabel = "agent_context_compaction"
+)
+
+// Reason records what asked for a compaction, for logging and for the UI.
+type Reason string
+
+const (
+ // ReasonThreshold is the routine case: context crossed the budget.
+ ReasonThreshold Reason = "threshold"
+ // ReasonOverflow is repair after the provider rejected or truncated a
+ // request because the window was full.
+ ReasonOverflow Reason = "overflow"
+)
+
+// ErrNothingToCompact means the context cannot be made smaller: everything
+// outside the keep-recent budget is already gone. Callers must treat this as a
+// stop signal rather than retrying, or they reproduce the every-round
+// summarization loop this package exists to prevent.
+var ErrNothingToCompact = errors.New("compaction: nothing outside the keep-recent budget")
+
+// Result describes what one compaction did.
+type Result struct {
+ Messages []chat.Message
+ Summary string
+ Reason Reason
+ TokensBefore int
+ TokensAfter int
+ MessagesBefore int
+ MessagesAfter int
+ // Degraded reports that at least one summary came from the raw archive
+ // because the summarizer failed. The context still shrank; its memory is
+ // just coarser.
+ Degraded bool
+ // SplitTurn reports that the cut divided a single turn, so a turn-prefix
+ // summary was generated alongside the history summary.
+ SplitTurn bool
+}
+
+// Freed is how much room the compaction actually recovered. A non-positive
+// value means the summary cost as much as the history it replaced.
+func (r *Result) Freed() int {
+ return r.TokensBefore - r.TokensAfter
+}
+
+// Compactor summarizes conversation history into a checkpoint.
+type Compactor struct {
+ chatModel chat.Chat
+ estimator *agenttoken.Estimator
+ settings Settings
+}
+
+// New builds a compactor. It returns nil when compaction cannot run, so the
+// caller can treat a nil compactor as "feature off" without a second flag.
+func New(chatModel chat.Chat, estimator *agenttoken.Estimator, settings Settings) *Compactor {
+ if chatModel == nil || estimator == nil || settings.MaxContextTokens <= 0 {
+ return nil
+ }
+ return &Compactor{chatModel: chatModel, estimator: estimator, settings: settings.Normalize()}
+}
+
+// Settings returns the normalized settings, including the derived threshold.
+func (c *Compactor) Settings() Settings {
+ if c == nil {
+ return Settings{}
+ }
+ return c.settings
+}
+
+// Compact replaces history older than the keep-recent budget with a summary.
+// It returns ErrNothingToCompact when no such history exists.
+func (c *Compactor) Compact(
+ ctx context.Context, messages []chat.Message, reason Reason,
+) (*Result, error) {
+ if c == nil {
+ return nil, ErrNothingToCompact
+ }
+ prep := Prepare(messages, c.settings, c.estimator)
+ if prep == nil {
+ return nil, ErrNothingToCompact
+ }
+
+ summary, degraded := c.buildSummary(ctx, prep)
+ summary += prep.fileOps.format()
+ compacted := Apply(messages, prep, summary)
+
+ return &Result{
+ Messages: compacted,
+ Summary: summary,
+ Reason: reason,
+ TokensBefore: prep.TokensBefore,
+ TokensAfter: c.estimator.EstimateMessages(compacted),
+ MessagesBefore: len(messages),
+ MessagesAfter: len(compacted),
+ Degraded: degraded,
+ SplitTurn: prep.IsSplitTurn,
+ }, nil
+}
+
+// buildSummary produces the checkpoint text, falling back to a raw archive for
+// any part the summarizer could not produce.
+func (c *Compactor) buildSummary(ctx context.Context, p *Preparation) (string, bool) {
+ degraded := false
+
+ history := p.PreviousSummary
+ if len(p.MessagesToSummarize) > 0 {
+ instructions := initialSummarizationInstructions
+ if p.PreviousSummary != "" {
+ instructions = updateSummarizationInstructions
+ }
+ text, err := c.summarize(
+ ctx, p.MessagesToSummarize, p.PreviousSummary, instructions, c.settings.summaryBudget(),
+ )
+ if err != nil {
+ degraded = true
+ // The previous summary is still the best record of everything
+ // before this span, so the archive is appended to it rather than
+ // replacing it.
+ history = joinNonEmpty(p.PreviousSummary, rawArchive(p.MessagesToSummarize))
+ } else {
+ history = text
+ }
+ }
+
+ if p.IsSplitTurn && len(p.TurnPrefixMessages) > 0 {
+ prefix, err := c.summarize(
+ ctx, p.TurnPrefixMessages, "", turnPrefixInstructions, c.settings.turnPrefixBudget(),
+ )
+ if err != nil {
+ degraded = true
+ prefix = rawArchive(p.TurnPrefixMessages)
+ }
+ if history == "" {
+ history = "No prior history."
+ }
+ history += splitTurnSeparator + prefix
+ }
+
+ return history, degraded
+}
+
+// summarize runs one summarization call with retries.
+func (c *Compactor) summarize(
+ ctx context.Context,
+ messages []chat.Message,
+ previousSummary, instructions string,
+ maxTokens int,
+) (string, error) {
+ prompt := buildSummarizationPrompt(messages, previousSummary, instructions)
+ var lastErr error
+
+ for attempt := 1; attempt <= maxSummarizationAttempts; attempt++ {
+ callCtx, cancel := context.WithTimeout(ctx, summarizationTimeout)
+ callCtx = types.WithLLMCallMetadata(callCtx, llmCallLabel, "")
+ resp, err := c.chatModel.Chat(callCtx, []chat.Message{
+ {Role: "system", Content: summarizationSystemPrompt},
+ {Role: "user", Content: prompt},
+ }, &chat.ChatOptions{
+ Temperature: 0.3, // low temperature for factual summarization
+ MaxTokens: maxTokens,
+ })
+ cancel()
+
+ if err != nil {
+ lastErr = err
+ continue
+ }
+ if err := validateSummary(resp); err != nil {
+ lastErr = err
+ continue
+ }
+ return strings.TrimSpace(resp.Content), nil
+ }
+
+ return "", fmt.Errorf("summarization failed after %d attempts: %w",
+ maxSummarizationAttempts, lastErr)
+}
+
+// validateSummary rejects responses that cannot serve as a checkpoint.
+//
+// The length stop is the one worth spelling out: a summary cut off by the token
+// cap reads like a valid summary but silently ends mid-section, and every later
+// round inherits that truncation as its only memory of the dropped history.
+// A partial summary is a failure: it cannot serve as a checkpoint.
+func validateSummary(resp *types.ChatResponse) error {
+ if resp == nil || strings.TrimSpace(resp.Content) == "" {
+ return errors.New("empty response from LLM")
+ }
+ switch strings.ToLower(strings.TrimSpace(resp.FinishReason)) {
+ case "length", "max_tokens", "max_output_tokens":
+ return errors.New("generation hit the token cap and the summary is incomplete")
+ }
+ return nil
+}
+
+// buildSummarizationPrompt wraps the transcript in a tag and puts the
+// instructions last, so the summarizer cannot mistake conversation text for
+// its own instructions.
+func buildSummarizationPrompt(messages []chat.Message, previousSummary, instructions string) string {
+ var sb strings.Builder
+ sb.WriteString("<conversation>\n")
+ sb.WriteString(serializeConversation(messages))
+ sb.WriteString("\n</conversation>\n\n")
+ if previousSummary != "" {
+ sb.WriteString("<previous-summary>\n")
+ sb.WriteString(previousSummary)
+ sb.WriteString("\n</previous-summary>\n\n")
+ }
+ sb.WriteString(instructions)
+ return sb.String()
+}
+
+func joinNonEmpty(parts ...string) string {
+ kept := make([]string, 0, len(parts))
+ for _, p := range parts {
+ if strings.TrimSpace(p) != "" {
+ kept = append(kept, p)
+ }
+ }
+ return strings.Join(kept, "\n\n")
+}
diff --git a/internal/agent/compaction/cutpoint.go b/internal/agent/compaction/cutpoint.go
new file mode 100644
index 000000000..7e93629bf
--- /dev/null
+++ b/internal/agent/compaction/cutpoint.go
@@ -0,0 +1,118 @@
+package compaction
+
+import (
+ agenttoken "github.com/Tencent/WeKnora/internal/agent/token"
+ "github.com/Tencent/WeKnora/internal/models/chat"
+)
+
+// CutPoint is where the conversation is divided into "summarize this" and
+// "keep this verbatim".
+type CutPoint struct {
+ // FirstKeptIdx is the index of the first message kept verbatim.
+ FirstKeptIdx int
+ // TurnStartIdx is the user message that opened the turn the cut lands in,
+ // or -1 when the cut falls on a turn boundary.
+ TurnStartIdx int
+ // IsSplitTurn reports that the cut divides a single turn, so the part
+ // before it needs its own summary to explain the part after it.
+ IsSplitTurn bool
+}
+
+// isCutPointMessage reports whether history may be cut immediately before this
+// message. Everything except a tool result qualifies. Tool results are excluded
+// because they must stay with the assistant message that requested them —
+// cutting between the two leaves an orphaned tool result and providers reject
+// the request outright.
+//
+// The corollary is what makes mid-turn compaction safe: a cut that lands on an
+// assistant message keeps that message and every tool result following it, so
+// the pairing is never split from either side.
+func isCutPointMessage(msg *chat.Message) bool {
+ return msg.Role != "tool"
+}
+
+// isTurnStartMessage reports whether this message opens a turn. Compaction
+// summaries count: they stand in for everything before them, so the turn they
+// begin is complete on its own.
+func isTurnStartMessage(msg *chat.Message) bool {
+ return msg.Role == "user"
+}
+
+// historyStart is the first index compaction may touch. The system prompt is
+// never a candidate — it carries the agent's instructions, not its history.
+func historyStart(messages []chat.Message) int {
+ if len(messages) > 0 && messages[0].Role == "system" {
+ return 1
+ }
+ return 0
+}
+
+// FindCutPoint walks backwards from the newest message accumulating estimated
+// size, and keeps the largest suffix that still fits keepRecentTokens.
+//
+// The budget is a ceiling, not a floor. Stopping at the first message that
+// reaches the budget and keeping that message too is the obvious reading and
+// the wrong one: a single knowledge_search result is routinely ten thousand
+// tokens on its own, so "keep the recent 16k" would hand back 25k and leave
+// barely a round of headroom before the next compaction.
+//
+// Nothing here consults the current turn. That is deliberate: the budget is the
+// only rule, and a turn large enough to exceed it on its own gets split rather
+// than exempted.
+func FindCutPoint(
+ messages []chat.Message,
+ start, keepRecentTokens int,
+ estimator *agenttoken.Estimator,
+) CutPoint {
+ if start < 0 {
+ start = 0
+ }
+ var cutPoints []int
+ for i := start; i < len(messages); i++ {
+ if isCutPointMessage(&messages[i]) {
+ cutPoints = append(cutPoints, i)
+ }
+ }
+ if len(cutPoints) == 0 {
+ return CutPoint{FirstKeptIdx: start, TurnStartIdx: -1}
+ }
+
+ // Worst case, keep only the newest group. A single message larger than the
+ // whole budget cannot be cut any further here — trimming that is the tool
+ // result trimmer's job, not the cut point's.
+ cutIdx := cutPoints[len(cutPoints)-1]
+ accumulated := 0
+ for i := len(messages) - 1; i >= start; i-- {
+ accumulated += estimator.EstimateMessage(&messages[i])
+ if accumulated > keepRecentTokens {
+ break
+ }
+ // Still within budget, so this is a better (earlier) place to cut.
+ // Only legal cut points are recorded, which keeps every tool result
+ // attached to the assistant message that requested it.
+ if isCutPointMessage(&messages[i]) {
+ cutIdx = i
+ }
+ }
+
+ if isTurnStartMessage(&messages[cutIdx]) {
+ return CutPoint{FirstKeptIdx: cutIdx, TurnStartIdx: -1}
+ }
+ turnStart := findTurnStartIdx(messages, cutIdx, start)
+ return CutPoint{
+ FirstKeptIdx: cutIdx,
+ TurnStartIdx: turnStart,
+ IsSplitTurn: turnStart >= 0,
+ }
+}
+
+// findTurnStartIdx returns the index of the user message that opened the turn
+// containing entryIdx, or -1 if the turn started before the searchable range.
+func findTurnStartIdx(messages []chat.Message, entryIdx, start int) int {
+ for i := entryIdx; i >= start; i-- {
+ if isTurnStartMessage(&messages[i]) {
+ return i
+ }
+ }
+ return -1
+}
diff --git a/internal/agent/compaction/fileops.go b/internal/agent/compaction/fileops.go
new file mode 100644
index 000000000..7ad13ea5a
--- /dev/null
+++ b/internal/agent/compaction/fileops.go
@@ -0,0 +1,181 @@
+package compaction
+
+// Sandbox file operations have to survive compaction.
+//
+// Dropping the history that says "I wrote /workspace/output/deck.html" leaves
+// the model with no record of the artifacts it already produced, so it starts
+// rebuilding files that are already on disk — and for a file large enough to
+// need chunked writes, restarting is exactly the loop that never terminates.
+// The LLM summary is supposed to carry this, but it is prose and a list of
+// paths is the first detail a summarizer drops. So the paths are extracted
+// mechanically, re-attached to every summary, and inherited by the next one.
+//
+// Three sets while collecting, two lists when rendering: a file that was
+// written is reported only as modified even if it was also read.
+
+import (
+ "encoding/json"
+ "fmt"
+ "strings"
+
+ agenttools "github.com/Tencent/WeKnora/internal/agent/tools"
+ "github.com/Tencent/WeKnora/internal/models/chat"
+)
+
+const (
+ readFilesTag = "read-files"
+ modifiedFilesTag = "modified-files"
+
+ // maxTrackedFilePaths bounds what the block can add to every subsequent
+ // request. A session touching more files than this has its oldest entries
+ // dropped rather than growing the prompt without limit.
+ maxTrackedFilePaths = 50
+)
+
+// fileOps is the set of sandbox paths the compacted history touched. Reads and
+// writes are kept apart while collecting so a path can be reclassified when a
+// later call writes something that was only read before.
+type fileOps struct {
+ read []string
+ written []string
+ edited []string
+}
+
+func appendUnique(list []string, path string) []string {
+ path = strings.TrimSpace(path)
+ if path == "" || len(list) >= maxTrackedFilePaths {
+ return list
+ }
+ for _, existing := range list {
+ if existing == path {
+ return list
+ }
+ }
+ return append(list, path)
+}
+
+// extractFileOps collects the sandbox paths the summarized-away messages read
+// and wrote. previousSummary carries the block inherited from an earlier
+// compaction, which is no longer part of the message range being summarized
+// now that summaries are excluded from their own successor's input.
+func extractFileOps(previousSummary string, groups ...[]chat.Message) fileOps {
+ var ops fileOps
+ ops.inherit(previousSummary)
+ for _, group := range groups {
+ for _, msg := range group {
+ ops.inherit(msg.Content)
+ for _, tc := range msg.ToolCalls {
+ path := toolCallPath(tc.Function.Arguments)
+ if path == "" {
+ continue
+ }
+ switch tc.Function.Name {
+ case agenttools.ToolWriteSandboxFile:
+ ops.written = appendUnique(ops.written, path)
+ case agenttools.ToolEditSandboxFile:
+ ops.edited = appendUnique(ops.edited, path)
+ case agenttools.ToolReadSandboxFile:
+ ops.read = appendUnique(ops.read, path)
+ }
+ }
+ }
+ }
+ return ops
+}
+
+// inherit folds an already-rendered block back into the collecting sets. Its
+// modified list has been through resolve(), so it goes back in as written.
+func (o *fileOps) inherit(content string) {
+ if content == "" {
+ return
+ }
+ inheritedRead, inheritedModified := parseFileOpsBlock(content)
+ for _, p := range inheritedRead {
+ o.read = appendUnique(o.read, p)
+ }
+ for _, p := range inheritedModified {
+ o.written = appendUnique(o.written, p)
+ }
+}
+
+// resolve collapses the three sets into what the model is shown: everything
+// touched is "modified", and only files never written are listed as read.
+func (o fileOps) resolve() (read, modified []string) {
+ for _, p := range o.written {
+ modified = appendUnique(modified, p)
+ }
+ for _, p := range o.edited {
+ modified = appendUnique(modified, p)
+ }
+ for _, p := range o.read {
+ if !contains(modified, p) {
+ read = appendUnique(read, p)
+ }
+ }
+ return read, modified
+}
+
+func contains(list []string, want string) bool {
+ for _, p := range list {
+ if p == want {
+ return true
+ }
+ }
+ return false
+}
+
+// toolCallPath pulls the `path` argument out of a tool call. Malformed or
+// truncated arguments simply contribute nothing.
+func toolCallPath(arguments string) string {
+ var args struct {
+ Path string `json:"path"`
+ }
+ if err := json.Unmarshal([]byte(arguments), &args); err != nil {
+ return ""
+ }
+ return strings.TrimSpace(args.Path)
+}
+
+// format renders the block appended to a summary, or "" when nothing was
+// touched.
+func (o fileOps) format() string {
+ read, modified := o.resolve()
+ if len(read) == 0 && len(modified) == 0 {
+ return ""
+ }
+ var sb strings.Builder
+ writeTagged(&sb, readFilesTag, read)
+ writeTagged(&sb, modifiedFilesTag, modified)
+ return sb.String()
+}
+
+func writeTagged(sb *strings.Builder, tag string, paths []string) {
+ if len(paths) == 0 {
+ return
+ }
+ fmt.Fprintf(sb, "\n\n<%s>\n%s\n</%s>", tag, strings.Join(paths, "\n"), tag)
+}
+
+// parseFileOpsBlock reads back what format wrote, so consecutive compactions
+// accumulate instead of each forgetting the one before it.
+func parseFileOpsBlock(content string) (read, modified []string) {
+ return parseTagged(content, readFilesTag), parseTagged(content, modifiedFilesTag)
+}
+
+func parseTagged(content, tag string) []string {
+ open, closeTag := "<"+tag+">", "</"+tag+">"
+ start := strings.Index(content, open)
+ if start < 0 {
+ return nil
+ }
+ start += len(open)
+ end := strings.Index(content[start:], closeTag)
+ if end < 0 {
+ return nil
+ }
+ var paths []string
+ for _, line := range strings.Split(content[start:start+end], "\n") {
+ paths = appendUnique(paths, line)
+ }
+ return paths
+}
diff --git a/internal/agent/compaction/fileops_test.go b/internal/agent/compaction/fileops_test.go
new file mode 100644
index 000000000..ac5c7aebf
--- /dev/null
+++ b/internal/agent/compaction/fileops_test.go
@@ -0,0 +1,90 @@
+package compaction
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/models/chat"
+ "github.com/stretchr/testify/assert"
+)
+
+func toolCallMsg(name, arguments string) chat.Message {
+ return chat.Message{
+ Role: "assistant",
+ ToolCalls: []chat.ToolCall{{
+ ID: "call-1",
+ Type: "function",
+ Function: chat.FunctionCall{Name: name, Arguments: arguments},
+ }},
+ }
+}
+
+func TestResolveSplitsReadsFromWrites(t *testing.T) {
+ read, modified := extractFileOps("", []chat.Message{
+ toolCallMsg("write_sandbox_file", `{"path":"/workspace/output/deck.html","content":"<html>"}`),
+ toolCallMsg("edit_sandbox_file", `{"path":"/workspace/output/deck.html","old_string":"a"}`),
+ toolCallMsg("read_sandbox_file", `{"path":"/workspace/input/notes.txt"}`),
+ toolCallMsg("shell_exec", `{"command":"ls"}`),
+ }).resolve()
+
+ // Written then edited is one entry, not two.
+ assert.Equal(t, []string{"/workspace/output/deck.html"}, modified)
+ assert.Equal(t, []string{"/workspace/input/notes.txt"}, read)
+}
+
+// A file the agent read and then rewrote is only interesting as something it
+// modified; listing it twice invites the model to re-read its own output.
+func TestResolveDropsReadsThatWereAlsoWritten(t *testing.T) {
+ read, modified := extractFileOps("", []chat.Message{
+ toolCallMsg("read_sandbox_file", `{"path":"/workspace/output/deck.html"}`),
+ toolCallMsg("write_sandbox_file", `{"path":"/workspace/output/deck.html","content":"x"}`),
+ }).resolve()
+
+ assert.Equal(t, []string{"/workspace/output/deck.html"}, modified)
+ assert.Empty(t, read)
+}
+
+// Truncated arguments are the normal case for the calls this feature exists
+// to survive, so they must be skipped rather than poison the list.
+func TestExtractFileOpsIgnoresUnparseableArguments(t *testing.T) {
+ read, modified := extractFileOps("", []chat.Message{
+ toolCallMsg("write_sandbox_file", `{"path":"/workspace/output/a.html","content":"<htm`),
+ toolCallMsg("write_sandbox_file", `{"content":"no path here"}`),
+ }).resolve()
+
+ assert.Empty(t, modified)
+ assert.Empty(t, read)
+}
+
+// Without inheritance the second compaction forgets what the first one
+// recorded, which is the whole failure mode this guards against. The prior
+// block now arrives via the previous summary rather than as a message, because
+// summaries no longer re-enter their successor's input.
+func TestExtractFileOpsInheritsFromPreviousSummary(t *testing.T) {
+ earlier := fileOps{
+ written: []string{"/workspace/output/deck.html"},
+ read: []string{"/workspace/input/notes.txt"},
+ }
+
+ read, modified := extractFileOps("prose"+earlier.format(), []chat.Message{
+ toolCallMsg("write_sandbox_file", `{"path":"/workspace/output/report.md","content":"x"}`),
+ }).resolve()
+
+ assert.Equal(t, []string{"/workspace/output/deck.html", "/workspace/output/report.md"}, modified)
+ assert.Equal(t, []string{"/workspace/input/notes.txt"}, read)
+}
+
+func TestFileOpsFormatIsEmptyWhenNothingTouched(t *testing.T) {
+ assert.Empty(t, fileOps{}.format())
+}
+
+func TestFileOpsCapsTrackedPaths(t *testing.T) {
+ msgs := make([]chat.Message, 0, maxTrackedFilePaths+10)
+ for i := 0; i < maxTrackedFilePaths+10; i++ {
+ msgs = append(msgs, toolCallMsg("write_sandbox_file",
+ `{"path":"/workspace/output/`+strings.Repeat("a", i+1)+`.txt"}`))
+ }
+
+ _, modified := extractFileOps("", msgs).resolve()
+ assert.Len(t, modified, maxTrackedFilePaths)
+}
diff --git a/internal/agent/compaction/overflow.go b/internal/agent/compaction/overflow.go
new file mode 100644
index 000000000..bd666a046
--- /dev/null
+++ b/internal/agent/compaction/overflow.go
@@ -0,0 +1,116 @@
+package compaction
+
+import (
+ "regexp"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// Context overflow is worth detecting precisely because the recovery is
+// specific: compact and retry once. Misread as a generic failure it ends the
+// turn; misread as a transient error it retries the same oversized request
+// until the attempts run out. Patterns are collected from real provider
+// responses.
+var overflowPatterns = []*regexp.Regexp{
+ regexp.MustCompile(`(?i)prompt is too long`), // Anthropic
+ regexp.MustCompile(`(?i)request_too_large`), // Anthropic (HTTP 413)
+ regexp.MustCompile(`(?i)input is too long for requested model`), // Amazon Bedrock
+ regexp.MustCompile(`(?i)exceeds the context window`), // OpenAI
+ regexp.MustCompile(`(?i)exceeds (the )?(model'?s )?maximum context length`), // OpenAI-compatible proxies
+ regexp.MustCompile(`(?i)input token count.*exceeds the maximum`), // Google Gemini
+ regexp.MustCompile(`(?i)maximum prompt length is \d+`), // xAI Grok
+ regexp.MustCompile(`(?i)reduce the length of the messages`), // Groq
+ regexp.MustCompile(`(?i)maximum context length is \d+ tokens`), // OpenRouter
+ regexp.MustCompile(`(?i)exceeds (the )?maximum allowed input length`), // OpenRouter / Poolside
+ regexp.MustCompile(`(?i)is longer than the model'?s context length`), // Together AI
+ regexp.MustCompile(`(?i)exceeds the limit of \d+`), // GitHub Copilot
+ regexp.MustCompile(`(?i)exceeds the available context size`), // llama.cpp
+ regexp.MustCompile(`(?i)greater than the context length`), // LM Studio
+ regexp.MustCompile(`(?i)context window exceeds limit`), // MiniMax
+ regexp.MustCompile(`(?i)exceeded model token limit`), // Kimi
+ regexp.MustCompile(`(?i)too large for model with \d+ maximum context length`), // Mistral
+ regexp.MustCompile(`(?i)but the configured context size is`), // DS4
+ regexp.MustCompile(`(?i)model_context_window_exceeded`), // z.ai
+ regexp.MustCompile(`(?i)prompt too long; exceeded (max )?context length`), // Ollama
+ regexp.MustCompile(`(?i)range of input length should be`), // DashScope / Qwen
+ regexp.MustCompile(`(?i)context[_ ]length[_ ]exceeded`), // generic
+ regexp.MustCompile(`(?i)too many tokens`), // generic
+ regexp.MustCompile(`(?i)token limit exceeded`), // generic
+}
+
+// nonOverflowPatterns are errors that mention token counts while meaning
+// something else. Bedrock throttling reads "ThrottlingException: Too many
+// tokens, please wait before trying again", which matches an overflow pattern
+// and is not one. Matched anywhere in the message rather than anchored, since
+// WeKnora sees raw provider errors rather than a pre-normalized prefix.
+var nonOverflowPatterns = []*regexp.Regexp{
+ regexp.MustCompile(`(?i)throttling`),
+ regexp.MustCompile(`(?i)service unavailable`),
+ regexp.MustCompile(`(?i)rate limit`),
+ regexp.MustCompile(`(?i)too many requests`),
+}
+
+// IsOverflowError reports whether a failed LLM call failed because the request
+// did not fit in the context window.
+func IsOverflowError(err error) bool {
+ if err == nil {
+ return false
+ }
+ msg := err.Error()
+ for _, p := range nonOverflowPatterns {
+ if p.MatchString(msg) {
+ return false
+ }
+ }
+ for _, p := range overflowPatterns {
+ if p.MatchString(msg) {
+ return true
+ }
+ }
+ return false
+}
+
+// ResponseHitContextLimit reports whether a *successful* response was shaped by
+// a full context window rather than by the completion budget we asked for.
+// Three shapes:
+//
+// - The provider accepted an oversized request silently and reported a prompt
+// larger than the window (z.ai).
+// - The provider truncated the input to fill the window exactly, leaving no
+// room to generate, and stopped on length with no output (Xiaomi MiMo).
+// - The provider stopped on length having emitted less than we allowed, so
+// our own cap cannot be what stopped it (the general recoverable case).
+//
+// completionBudget is the max_tokens we requested, before any context-based
+// clamping; passing the clamped value would hide exactly the case this detects.
+func ResponseHitContextLimit(
+ resp *types.ChatResponse, contextWindow, completionBudget int,
+) bool {
+ if resp == nil {
+ return false
+ }
+ prompt := resp.Usage.PromptTokens
+ completion := resp.Usage.CompletionTokens
+ lengthStop := isLengthStop(resp.FinishReason)
+
+ if contextWindow > 0 && prompt > contextWindow {
+ return true
+ }
+ if contextWindow > 0 && lengthStop && completion == 0 && prompt > 0 &&
+ prompt >= contextWindow*99/100 {
+ return true
+ }
+ // Without usage there is nothing to compare against; treating that as
+ // overflow would retry every ordinary truncation.
+ return lengthStop && completionBudget > 0 && completion > 0 && completion < completionBudget
+}
+
+func isLengthStop(reason string) bool {
+ switch strings.ToLower(strings.TrimSpace(reason)) {
+ case "length", "max_tokens", "max_output_tokens":
+ return true
+ default:
+ return false
+ }
+}
diff --git a/internal/agent/compaction/overflow_test.go b/internal/agent/compaction/overflow_test.go
new file mode 100644
index 000000000..2390a6b0c
--- /dev/null
+++ b/internal/agent/compaction/overflow_test.go
@@ -0,0 +1,93 @@
+package compaction
+
+import (
+ "errors"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/assert"
+)
+
+// Real error strings from the providers WeKnora talks to. An overflow read as
+// a generic failure ends the turn; read as transient it retries the identical
+// oversized request until the attempts run out.
+func TestIsOverflowError(t *testing.T) {
+ overflow := []string{
+ "prompt is too long: 213462 tokens > 200000 maximum",
+ `413 {"error":{"type":"request_too_large","message":"Request exceeds the maximum size"}}`,
+ "Your input exceeds the context window of this model",
+ "Requested token count exceeds the model's maximum context length of 131072 tokens",
+ "Input length (265330) exceeds model's maximum context length (262144).",
+ "The input token count (1196265) exceeds the maximum number of tokens allowed (1048575)",
+ "This model's maximum prompt length is 131072 but the request contains 537812 tokens",
+ "Please reduce the length of the messages or completion",
+ "This endpoint's maximum context length is 131072 tokens",
+ "The input (300 tokens) is longer than the model's context length (200 tokens).",
+ "the request exceeds the available context size, try increasing it",
+ "prompt token count of 5000 exceeds the limit of 4096",
+ "invalid params, context window exceeds limit",
+ "Your request exceeded model token limit: 128000",
+ "Prompt has 5000 tokens, but the configured context size is 4096 tokens",
+ "Range of input length should be [1, 30000]",
+ "context_length_exceeded",
+ }
+ for _, msg := range overflow {
+ assert.True(t, IsOverflowError(errors.New(msg)), "should detect overflow: %s", msg)
+ }
+
+ // Throttling formats itself as a token complaint and is not an overflow.
+ notOverflow := []string{
+ "ThrottlingException: Too many tokens, please wait before trying again.",
+ "429 rate limit exceeded",
+ "Too many requests",
+ "connection reset by peer",
+ "context deadline exceeded",
+ }
+ for _, msg := range notOverflow {
+ assert.False(t, IsOverflowError(errors.New(msg)), "should not detect overflow: %s", msg)
+ }
+
+ assert.False(t, IsOverflowError(nil))
+}
+
+func TestResponseHitContextLimit(t *testing.T) {
+ const window, budget = 100000, 8000
+
+ // The general recoverable case: stopped on length below our own cap, so
+ // our cap is not what stopped it.
+ assert.True(t, ResponseHitContextLimit(&types.ChatResponse{
+ FinishReason: "length",
+ Usage: types.TokenUsage{PromptTokens: 90000, CompletionTokens: 2000},
+ }, window, budget))
+
+ // Used the full budget: the model simply had more to say, and retrying
+ // after a compaction would produce the same truncation.
+ assert.False(t, ResponseHitContextLimit(&types.ChatResponse{
+ FinishReason: "length",
+ Usage: types.TokenUsage{PromptTokens: 50000, CompletionTokens: budget},
+ }, window, budget))
+
+ // Silent overflow: the provider accepted a prompt larger than the window
+ // instead of rejecting it (z.ai).
+ assert.True(t, ResponseHitContextLimit(&types.ChatResponse{
+ FinishReason: "stop",
+ Usage: types.TokenUsage{PromptTokens: window + 1, CompletionTokens: 10},
+ }, window, budget))
+
+ // Server truncated the input to fill the window exactly, leaving no room
+ // to generate (Xiaomi MiMo).
+ assert.True(t, ResponseHitContextLimit(&types.ChatResponse{
+ FinishReason: "length",
+ Usage: types.TokenUsage{PromptTokens: window, CompletionTokens: 0},
+ }, window, budget))
+
+ // An ordinary completed response is not an overflow.
+ assert.False(t, ResponseHitContextLimit(&types.ChatResponse{
+ FinishReason: "stop",
+ Usage: types.TokenUsage{PromptTokens: 1000, CompletionTokens: 100},
+ }, window, budget))
+
+ // No usage means nothing to compare against.
+ assert.False(t, ResponseHitContextLimit(&types.ChatResponse{FinishReason: "length"}, window, budget))
+ assert.False(t, ResponseHitContextLimit(nil, window, budget))
+}
diff --git a/internal/agent/compaction/prepare.go b/internal/agent/compaction/prepare.go
new file mode 100644
index 000000000..3a2808f29
--- /dev/null
+++ b/internal/agent/compaction/prepare.go
@@ -0,0 +1,145 @@
+package compaction
+
+import (
+ "strings"
+
+ agenttoken "github.com/Tencent/WeKnora/internal/agent/token"
+ "github.com/Tencent/WeKnora/internal/models/chat"
+)
+
+// The summary is injected as a `user` message rather than a second `system`
+// one. A system message is an instruction; this is conversation history, and
+// providers that merge or specially weight system messages were the wrong
+// place to put it.
+const (
+ summaryPrefix = "The conversation history before this point was compacted " +
+ "into the following summary:\n\n<summary>\n"
+ summarySuffix = "\n</summary>"
+)
+
+// Preparation is everything the summarization step needs, computed before any
+// LLM call so the caller can decide not to make one.
+type Preparation struct {
+ // FirstKeptIdx is where the verbatim tail begins.
+ FirstKeptIdx int
+ // MessagesToSummarize are the complete turns being replaced by prose.
+ MessagesToSummarize []chat.Message
+ // TurnPrefixMessages is the discarded head of a split turn, summarized
+ // separately so the retained tail still has its originating request.
+ TurnPrefixMessages []chat.Message
+ IsSplitTurn bool
+ // PreviousSummary is the prior compaction's text, updated in place rather
+ // than summarized again.
+ PreviousSummary string
+ TokensBefore int
+ fileOps fileOps
+}
+
+// Prepare picks the cut point and collects the message ranges around it.
+//
+// It returns nil when compaction cannot help — no messages fall outside the
+// keep-recent budget, or the last compaction already left nothing to remove.
+// That nil is the guard against the failure mode where every round spends a
+// summarization call on a context it cannot shrink.
+func Prepare(messages []chat.Message, s Settings, estimator *agenttoken.Estimator) *Preparation {
+ if estimator == nil || len(messages) == 0 {
+ return nil
+ }
+ s = s.Normalize()
+
+ // Summarizing starts after the previous compaction's boundary. The
+ // summary message itself is excluded: feeding it back in is what turns
+ // successive compactions into a summary of a summary of a summary.
+ boundaryStart := historyStart(messages)
+ previousSummary := ""
+ for i := len(messages) - 1; i >= boundaryStart; i-- {
+ if messages[i].Kind != chat.MessageKindCompactionSummary {
+ continue
+ }
+ previousSummary = unwrapSummary(messages[i].Content)
+ boundaryStart = i + 1
+ break
+ }
+ if boundaryStart >= len(messages) {
+ return nil
+ }
+
+ cut := FindCutPoint(messages, boundaryStart, s.KeepRecentTokens, estimator)
+
+ historyEnd := cut.FirstKeptIdx
+ if cut.IsSplitTurn {
+ historyEnd = cut.TurnStartIdx
+ }
+ toSummarize := cloneRange(messages, boundaryStart, historyEnd)
+
+ var turnPrefix []chat.Message
+ if cut.IsSplitTurn {
+ turnPrefix = cloneRange(messages, cut.TurnStartIdx, cut.FirstKeptIdx)
+ }
+
+ if len(toSummarize) == 0 && len(turnPrefix) == 0 {
+ return nil
+ }
+
+ return &Preparation{
+ FirstKeptIdx: cut.FirstKeptIdx,
+ MessagesToSummarize: toSummarize,
+ TurnPrefixMessages: turnPrefix,
+ IsSplitTurn: cut.IsSplitTurn,
+ PreviousSummary: previousSummary,
+ TokensBefore: estimator.EstimateMessages(messages),
+ fileOps: extractFileOps(previousSummary, toSummarize, turnPrefix),
+ }
+}
+
+// Apply rebuilds the message list as system prompt, summary, and the verbatim
+// tail. Nothing between the system prompt and the cut point survives.
+func Apply(messages []chat.Message, p *Preparation, summary string) []chat.Message {
+ tailStart := min(max(p.FirstKeptIdx, 0), len(messages))
+ out := make([]chat.Message, 0, 2+len(messages)-tailStart)
+ if historyStart(messages) == 1 {
+ out = append(out, messages[0])
+ }
+ out = append(out, SummaryMessage(summary))
+ return append(out, messages[tailStart:]...)
+}
+
+// SummaryMessage wraps summary text in the envelope the model sees, tagged so
+// the next compaction recognizes it as its own output.
+func SummaryMessage(summary string) chat.Message {
+ return chat.Message{
+ Role: "user",
+ Kind: chat.MessageKindCompactionSummary,
+ Content: summaryPrefix + summary + summarySuffix,
+ }
+}
+
+// unwrapSummary recovers the raw text from a summary message so it can be
+// handed to the update prompt without its envelope.
+func unwrapSummary(content string) string {
+ start := strings.Index(content, "<summary>")
+ if start < 0 {
+ return strings.TrimSpace(content)
+ }
+ start += len("<summary>")
+ end := strings.LastIndex(content, "</summary>")
+ if end < start {
+ return strings.TrimSpace(content[start:])
+ }
+ return strings.TrimSpace(content[start:end])
+}
+
+func cloneRange(messages []chat.Message, start, end int) []chat.Message {
+ if start < 0 {
+ start = 0
+ }
+ if end > len(messages) {
+ end = len(messages)
+ }
+ if start >= end {
+ return nil
+ }
+ out := make([]chat.Message, end-start)
+ copy(out, messages[start:end])
+ return out
+}
diff --git a/internal/agent/compaction/prompts.go b/internal/agent/compaction/prompts.go
new file mode 100644
index 000000000..d9adc09f7
--- /dev/null
+++ b/internal/agent/compaction/prompts.go
@@ -0,0 +1,82 @@
+package compaction
+
+// The sections are not decoration: the summary is the agent's only memory of
+// the dropped turns, and unstructured prose reliably loses the two things the
+// next round actually needs — what is already finished, and what was about to
+// happen next.
+
+const summarizationSystemPrompt = "" +
+ "You are a context summarization assistant. Your task is to read a conversation " +
+ "between a user and an AI assistant, then produce a structured summary following " +
+ "the exact format specified.\n\n" +
+ "Do NOT continue the conversation. Do NOT respond to any questions in the " +
+ "conversation. ONLY output the structured summary."
+
+const summaryFormat = "" +
+ "## Goal\n" +
+ "[What the user is ultimately trying to accomplish. May be multiple items.]\n\n" +
+ "## Constraints & Preferences\n" +
+ "- [Requirements, formats, tools, or styles the user asked for, and anything they rejected]\n" +
+ "- [Or \"(none)\"]\n\n" +
+ "## Progress\n" +
+ "### Done\n" +
+ "- [x] [Completed work, naming the specific artifacts produced and where they were written]\n\n" +
+ "### In Progress\n" +
+ "- [ ] [Current work]\n\n" +
+ "### Blocked\n" +
+ "- [Issues preventing progress, if any]\n\n" +
+ "## Key Decisions\n" +
+ "- **[Decision]**: [Brief rationale, so it is not revisited]\n\n" +
+ "## Next Steps\n" +
+ "1. [Ordered list of what should happen next]\n\n" +
+ "## Critical Context\n" +
+ "- [Facts, numbers, identifiers, paths, and error messages later steps depend on]\n" +
+ "- [Or \"(none)\"]\n\n" +
+ "Keep each section concise. Write in the same language as the conversation. " +
+ "Preserve exact values — paths, names, numbers, and error text — rather than " +
+ "paraphrasing them. Output only the summary, with no preamble.\n\n" +
+ "Length matters: this summary shares the context window with the retained " +
+ "recent messages, so it must stay compact enough to be worth having. Aim for " +
+ "under 500 words. Prefer short bullets over prose, and drop detail that later " +
+ "steps cannot act on."
+
+const initialSummarizationInstructions = "" +
+ "The messages above are a conversation to summarize. Create a structured context " +
+ "checkpoint that another LLM will use to continue the work.\n\n" +
+ "Use this EXACT format:\n\n" + summaryFormat
+
+const updateSummarizationInstructions = "" +
+ "The messages above are NEW conversation messages to incorporate into the existing " +
+ "summary provided in <previous-summary> tags.\n\n" +
+ "RULES:\n" +
+ "- PRESERVE information from the previous summary that later steps still need\n" +
+ "- ADD new progress, decisions, and context from the new messages\n" +
+ "- UPDATE the Progress section: move items from \"In Progress\" to \"Done\" when completed\n" +
+ "- UPDATE \"Next Steps\" based on what was accomplished\n" +
+ "- PRESERVE exact file paths, function names, and error messages\n" +
+ "- CONDENSE as you go: the result must not be longer than the previous " +
+ "summary unless genuinely new facts require it. Completed work collapses to " +
+ "one line each; superseded plans, resolved errors, and abandoned approaches " +
+ "come out entirely. An update that only ever grows defeats the compaction " +
+ "it is part of.\n\n" +
+ "Use this EXACT format:\n\n" + summaryFormat
+
+// turnPrefixInstructions summarizes the discarded head of a split turn. It is
+// a different job from the history summary: the retained suffix is still in
+// context, so this only has to supply what the suffix cannot explain about
+// itself — above all, what the user originally asked for.
+const turnPrefixInstructions = "" +
+ "This is the PREFIX of a turn that was too large to keep. The SUFFIX (recent work) " +
+ "is retained in the conversation and is NOT shown here.\n\n" +
+ "Summarize the prefix to provide context for the retained suffix, using this EXACT " +
+ "format:\n\n" +
+ "## Original Request\n" +
+ "[What did the user ask for in this turn?]\n\n" +
+ "## Early Progress\n" +
+ "- [Key decisions and work done in the prefix, naming artifacts and paths]\n\n" +
+ "## Context for Suffix\n" +
+ "- [Information needed to understand the retained recent work]\n\n" +
+ "Be concise. Write in the same language as the conversation. Preserve exact file " +
+ "paths, names, and error messages. Output only the summary."
+
+const splitTurnSeparator = "\n\n---\n\n**Turn Context (split turn):**\n\n"
diff --git a/internal/agent/compaction/serialize.go b/internal/agent/compaction/serialize.go
new file mode 100644
index 000000000..6683c25de
--- /dev/null
+++ b/internal/agent/compaction/serialize.go
@@ -0,0 +1,128 @@
+package compaction
+
+import (
+ "encoding/json"
+ "fmt"
+ "sort"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/models/chat"
+)
+
+const (
+ // toolResultMaxChars caps a single tool result inside the summarization
+ // request. Tool output is the largest contributor to context size and the
+ // summary needs its gist, not its bytes.
+ toolResultMaxChars = 2000
+ // textMaxChars caps user and assistant prose, which is rarely the problem
+ // but should not be unbounded either.
+ textMaxChars = 4000
+ // toolArgsMaxChars caps rendered tool-call arguments. A write_sandbox_file
+ // call carries an entire file body in its arguments; the summary needs the
+ // path and the fact of the write, never the content.
+ toolArgsMaxChars = 400
+)
+
+// serializeConversation renders messages as a transcript rather than passing
+// them as a conversation. A model handed real messages tries to continue them;
+// handed a transcript, it summarizes them.
+func serializeConversation(messages []chat.Message) string {
+ var parts []string
+ for i := range messages {
+ msg := &messages[i]
+ switch msg.Role {
+ case "system":
+ continue
+ case "user":
+ if content := truncate(msg.Content, textMaxChars); content != "" {
+ parts = append(parts, "[User]: "+content)
+ }
+ case "assistant":
+ if msg.ReasoningContent != "" {
+ parts = append(parts,
+ "[Assistant thinking]: "+truncate(msg.ReasoningContent, textMaxChars))
+ }
+ if msg.Content != "" {
+ parts = append(parts, "[Assistant]: "+truncate(msg.Content, textMaxChars))
+ }
+ if calls := serializeToolCalls(msg.ToolCalls); calls != "" {
+ parts = append(parts, "[Assistant tool calls]: "+calls)
+ }
+ case "tool":
+ if content := truncate(msg.Content, toolResultMaxChars); content != "" {
+ parts = append(parts, fmt.Sprintf("[Tool result %s]: %s", msg.Name, content))
+ }
+ }
+ }
+ return strings.Join(parts, "\n\n")
+}
+
+func serializeToolCalls(calls []chat.ToolCall) string {
+ if len(calls) == 0 {
+ return ""
+ }
+ rendered := make([]string, 0, len(calls))
+ for _, tc := range calls {
+ rendered = append(rendered,
+ fmt.Sprintf("%s(%s)", tc.Function.Name, renderToolArgs(tc.Function.Arguments)))
+ }
+ return strings.Join(rendered, "; ")
+}
+
+// renderToolArgs turns an arguments JSON blob into `key=value` pairs, dropping
+// oversized values. Keys are sorted so the same call always renders the same
+// way, which matters when the transcript is compared across compactions.
+func renderToolArgs(arguments string) string {
+ var parsed map[string]any
+ if err := json.Unmarshal([]byte(arguments), &parsed); err != nil {
+ return truncate(arguments, toolArgsMaxChars)
+ }
+ keys := make([]string, 0, len(parsed))
+ for k := range parsed {
+ keys = append(keys, k)
+ }
+ sort.Strings(keys)
+ pairs := make([]string, 0, len(keys))
+ for _, k := range keys {
+ encoded, err := json.Marshal(parsed[k])
+ if err != nil {
+ continue
+ }
+ pairs = append(pairs, fmt.Sprintf("%s=%s", k, truncate(string(encoded), toolArgsMaxChars)))
+ }
+ return strings.Join(pairs, ", ")
+}
+
+func truncate(s string, maxChars int) string {
+ s = strings.TrimSpace(s)
+ runes := []rune(s)
+ if len(runes) <= maxChars {
+ return s
+ }
+ return fmt.Sprintf("%s\n\n[... %d more characters truncated]",
+ string(runes[:maxChars]), len(runes)-maxChars)
+}
+
+// rawArchive is the fallback when the summarizer is unavailable. It is lossy
+// and unstructured, but it keeps the tool names and paths that the next round
+// needs in order not to redo finished work.
+func rawArchive(messages []chat.Message) string {
+ var sb strings.Builder
+ sb.WriteString("Raw conversation archive (LLM summarization unavailable):\n\n")
+ for i := range messages {
+ msg := &messages[i]
+ switch msg.Role {
+ case "user":
+ fmt.Fprintf(&sb, "- User: %s\n", truncate(msg.Content, 500))
+ case "assistant":
+ if calls := serializeToolCalls(msg.ToolCalls); calls != "" {
+ fmt.Fprintf(&sb, "- Assistant [%s]: %s\n", calls, truncate(msg.Content, 500))
+ continue
+ }
+ fmt.Fprintf(&sb, "- Assistant: %s\n", truncate(msg.Content, 500))
+ case "tool":
+ fmt.Fprintf(&sb, "- Tool[%s]: %s\n", msg.Name, truncate(msg.Content, 500))
+ }
+ }
+ return sb.String()
+}
diff --git a/internal/agent/compaction/settings.go b/internal/agent/compaction/settings.go
new file mode 100644
index 000000000..3010e45e2
--- /dev/null
+++ b/internal/agent/compaction/settings.go
@@ -0,0 +1,112 @@
+// Package compaction keeps an agent turn inside the model's context window by
+// replacing older conversation with a structured summary.
+//
+// The cut point is chosen by token budget alone — never by "keep the current
+// turn intact". A ReAct loop is a single turn that can run twenty rounds and
+// produce a hundred thousand tokens of tool traffic; a compactor that refuses
+// to touch the current turn has nothing left to compact and burns an LLM call
+// per round achieving nothing.
+package compaction
+
+// DefaultReserveTokens is the floor on room kept free for the next response.
+const DefaultReserveTokens = 16384
+
+// DefaultKeepRecentTokens is how much recent conversation survives a
+// compaction untouched. It is what makes compaction terminate: whatever the
+// context grew to, it comes out of a compaction at roughly summary + this,
+// which is far below any sane threshold, so the next round cannot immediately
+// re-trigger.
+const DefaultKeepRecentTokens = 20000
+
+// Settings configures when compaction runs and how much it keeps.
+type Settings struct {
+ // Enabled turns automatic compaction on. Disabled still allows an
+ // explicit overflow-recovery compaction, which is a repair, not a policy.
+ Enabled bool
+ // MaxContextTokens is the model's context window. Zero disables
+ // compaction entirely: without a window there is no budget to enforce.
+ MaxContextTokens int
+ // ReserveTokens is the part of the window history may not occupy because
+ // the next response has to fit there.
+ ReserveTokens int
+ // KeepRecentTokens is the token budget of recent messages kept verbatim.
+ KeepRecentTokens int
+ // MaxSummaryTokens caps the summarization completion. Zero falls back to
+ // the reserve-derived budget alone.
+ MaxSummaryTokens int
+}
+
+// Normalize fills in defaults and reconciles budgets that cannot all be
+// honored at once.
+func (s Settings) Normalize() Settings {
+ if s.ReserveTokens <= 0 {
+ s.ReserveTokens = DefaultReserveTokens
+ }
+ if s.KeepRecentTokens <= 0 {
+ s.KeepRecentTokens = DefaultKeepRecentTokens
+ }
+ // What matters is not how much a compaction frees but how much room it
+ // leaves before the next one. Keeping half the usable window technically
+ // compacts and still re-triggers within a round or two, because the
+ // summary takes a further slice and a single tool result can be ten
+ // thousand tokens. A quarter leaves the post-compaction context at roughly
+ // half the threshold, which is several rounds of work.
+ //
+ // Large windows are unaffected: the default keep-recent budget is already
+ // well under a quarter of them. Tool schemas are not subtracted here —
+ // keepRecentTokens is a fixed conversation budget, not "whatever is left
+ // after the tool list".
+ if s.MaxContextTokens > 0 {
+ usable := s.MaxContextTokens - s.ReserveTokens
+ if quarter := usable / 4; quarter > 0 && s.KeepRecentTokens > quarter {
+ s.KeepRecentTokens = quarter
+ }
+ }
+ return s
+}
+
+// Threshold is the context size above which history must be compacted. It is
+// an absolute reserve rather than a fraction of the window, because what has
+// to fit is the response, whose size does not scale with the window.
+func (s Settings) Threshold() int {
+ if s.MaxContextTokens <= 0 {
+ return 0
+ }
+ return max(s.MaxContextTokens-s.ReserveTokens, 1)
+}
+
+// ShouldCompact reports whether the current context has crossed the threshold.
+func (s Settings) ShouldCompact(contextTokens int) bool {
+ if !s.Enabled {
+ return false
+ }
+ threshold := s.Threshold()
+ return threshold > 0 && contextTokens > threshold
+}
+
+// summaryBudget is the completion cap for a summarization call: 0.8 of
+// reserveTokens, clamped by the model's own output limit. The old hard-coded
+// 2000 was the reason long sessions produced summaries that stopped
+// mid-sentence.
+//
+// It is additionally capped at the keep-recent budget. The summary occupies the
+// compacted context alongside the retained tail, and successive compactions
+// update the summary in place under instructions to preserve what is already
+// there — so without a ceiling tied to the same budget it grows every round and
+// slowly reclaims the room compaction just freed.
+func (s Settings) summaryBudget() int {
+ budget := s.ReserveTokens * 4 / 5
+ if s.MaxSummaryTokens > 0 && s.MaxSummaryTokens < budget {
+ budget = s.MaxSummaryTokens
+ }
+ if s.KeepRecentTokens > 0 && s.KeepRecentTokens < budget {
+ budget = s.KeepRecentTokens
+ }
+ return max(budget, 1024)
+}
+
+// turnPrefixBudget is the smaller cap for summarizing the discarded prefix of
+// a split turn: it only has to explain the retained suffix, not the session.
+func (s Settings) turnPrefixBudget() int {
+ return max(s.summaryBudget()/2, 512)
+}
diff --git a/internal/agent/const.go b/internal/agent/const.go
index 125330ae1..af068d645 100644
--- a/internal/agent/const.go
+++ b/internal/agent/const.go
@@ -5,6 +5,7 @@ import (
"strings"
"time"
+ "github.com/Tencent/WeKnora/internal/agent/compaction"
"github.com/Tencent/WeKnora/internal/types"
"github.com/google/uuid"
)
@@ -17,10 +18,14 @@ const (
// DefaultUseCustomSystemPrompt is the default whether to use custom system prompt for the agent
DefaultUseCustomSystemPrompt = false
- // defaultLLMCallTimeout is the default maximum time allowed for a single LLM call.
- // This prevents a single slow call from consuming the entire pipeline deadline.
+ // defaultLLMStallTimeout is how long a single LLM stream may produce no
+ // output before it is cancelled. It is a stall budget, not a total budget:
+ // a round that streams a whole file body inside a write_sandbox_file call
+ // runs for minutes while emitting continuously, and killing it on elapsed
+ // time throws away the half-assembled call. The overall ceiling belongs to
+ // the provider transport (WEKNORA_LLM_STREAM_TIMEOUT_SECONDS).
// Can be overridden via AgentConfig.LLMCallTimeout.
- defaultLLMCallTimeout = 120 * time.Second
+ defaultLLMStallTimeout = 120 * time.Second
// defaultToolExecTimeout is the default maximum time for a single tool execution.
// Prevents long-running tools (web_fetch, database_query) from hanging indefinitely.
@@ -60,6 +65,10 @@ var transientErrorMarkers = []string{
"500", "502", "503", "504",
"overloaded", "timeout", "timed out",
"connection", "server error", "temporarily unavailable",
+ // A broken or silent stream is worth one more attempt: the round produced
+ // no usable turn, and the alternative is ending the conversation on a
+ // partial response.
+ "deadline exceeded", "stalled",
}
// isTransientError checks whether an error is likely transient and worth retrying.
@@ -76,14 +85,21 @@ func isTransientError(err error) bool {
return false
}
-// getLLMCallTimeout returns the configured LLM call timeout, falling back to default.
-func (e *AgentEngine) getLLMCallTimeout() time.Duration {
+// getLLMStallTimeout returns how long an LLM stream may go silent before it is
+// cancelled, from AgentConfig.LLMCallTimeout or the default.
+func (e *AgentEngine) getLLMStallTimeout() time.Duration {
if e.config.LLMCallTimeout > 0 {
return time.Duration(e.config.LLMCallTimeout) * time.Second
}
- return defaultLLMCallTimeout
+ return defaultLLMStallTimeout
}
+// contextSafetyTokens is slack between what we estimate the request costs and
+// what the provider will actually count. Token estimation is approximate and
+// providers add their own scaffolding; without a margin the request that
+// exactly fits by our arithmetic is the one that gets rejected.
+const contextSafetyTokens = 4096
+
// getCompletionTokenBudget is the max_tokens / max_completion_tokens sent on
// each ReAct LLM round. Unset without a sandbox is 4096; unset with a
// sandbox (write_sandbox_file / edit_sandbox_file) is 24576.
@@ -97,6 +113,28 @@ func (e *AgentEngine) getCompletionTokenBudget() int {
return types.AgentRoundMaxCompletionTokensFor(configured, sandboxID)
}
+// contextReserveTokens is the part of the window that history may not occupy,
+// because the next response has to fit there. Sizing it from the round's own
+// completion budget is what a fixed reserve gets wrong: an agent allowed to
+// emit 24576 tokens needs at least that much free, or the request is accepted
+// and the reply is truncated.
+func (e *AgentEngine) contextReserveTokens() int {
+ return max(e.getCompletionTokenBudget()+contextSafetyTokens, compaction.DefaultReserveTokens)
+}
+
+// clampCompletionBudgetToContext shrinks the round's completion budget to what
+// is actually left in the window. Asking for more output than the window can
+// hold is a request the provider rejects outright, which reads to the agent as
+// an unexplained failure.
+func (e *AgentEngine) clampCompletionBudgetToContext(currentTokens int) int {
+ budget := e.getCompletionTokenBudget()
+ if e.config == nil || e.config.MaxContextTokens <= 0 {
+ return budget
+ }
+ available := e.config.MaxContextTokens - currentTokens - contextSafetyTokens
+ return max(min(budget, available), 1)
+}
+
// generateEventID generates a unique event ID with type suffix for better traceability
func generateEventID(suffix string) string {
return fmt.Sprintf("%s-%s", uuid.New().String()[:8], suffix)
diff --git a/internal/agent/context_debug.go b/internal/agent/context_debug.go
new file mode 100644
index 000000000..13791ff3e
--- /dev/null
+++ b/internal/agent/context_debug.go
@@ -0,0 +1,169 @@
+package agent
+
+// Diagnostics for context accounting.
+//
+// The failure this exists to catch is silent by nature: the estimate and the
+// provider's bill disagree, and nothing in the normal logs compares them. That
+// is how reasoning_content went uncounted long enough to make a 130k context
+// measure as 26k — compaction fired constantly, cut in the wrong place, and
+// freed nothing, with every individual log line looking reasonable.
+//
+// So the load-bearing line here is the drift check: what we predicted the
+// request would cost against what the provider actually charged for it.
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/models/chat"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// contextBreakdown attributes context tokens to the kind of content holding
+// them, so an unexpected total can be traced to a source rather than guessed at.
+type contextBreakdown struct {
+ Messages int
+ Total int
+ Text int
+ Reasoning int
+ ToolResults int
+ ToolCallArgs int
+ Images int
+ Summaries int
+ ToolSchemas int
+ // LargestKind and LargestTokens identify the single biggest message,
+ // which is usually the thing worth acting on.
+ LargestKind string
+ LargestTokens int
+}
+
+func (e *AgentEngine) breakdownContext(messages []chat.Message, tools []chat.Tool) contextBreakdown {
+ b := contextBreakdown{Messages: len(messages), ToolSchemas: e.tokenEstimator.EstimateTools(tools)}
+ est := e.tokenEstimator
+
+ for i := range messages {
+ msg := &messages[i]
+ msgTokens := est.EstimateMessage(msg)
+ b.Total += msgTokens
+
+ if msgTokens > b.LargestTokens {
+ b.LargestTokens = msgTokens
+ b.LargestKind = msg.Role
+ if msg.Name != "" {
+ b.LargestKind += ":" + msg.Name
+ }
+ }
+
+ if reasoning := est.EstimateString(msg.ReasoningContent); reasoning > 0 {
+ b.Reasoning += reasoning
+ }
+ for _, tc := range msg.ToolCalls {
+ b.ToolCallArgs += est.EstimateString(tc.Function.Arguments)
+ }
+ for _, part := range msg.MultiContent {
+ if part.ImageURL != nil || part.Type == "image_url" {
+ b.Images += estimatedImageTokensForLog
+ }
+ }
+ if len(msg.MultiContent) == 0 {
+ b.Images += len(msg.Images) * estimatedImageTokensForLog
+ }
+
+ content := est.EstimateString(msg.Content)
+ switch {
+ case msg.Kind == chat.MessageKindCompactionSummary:
+ b.Summaries += content
+ case msg.Role == "tool":
+ b.ToolResults += content
+ default:
+ b.Text += content
+ }
+ }
+ b.Total += b.ToolSchemas
+ return b
+}
+
+// estimatedImageTokensForLog mirrors the estimator's per-image constant. It is
+// duplicated rather than exported because it is only ever a reporting detail.
+const estimatedImageTokensForLog = 1200
+
+func (b contextBreakdown) String() string {
+ var sb strings.Builder
+ fmt.Fprintf(&sb, "msgs=%d total=%d", b.Messages, b.Total)
+ fmt.Fprintf(&sb, " text=%d reasoning=%d tool_results=%d tool_args=%d",
+ b.Text, b.Reasoning, b.ToolResults, b.ToolCallArgs)
+ if b.Images > 0 {
+ fmt.Fprintf(&sb, " images=%d", b.Images)
+ }
+ if b.Summaries > 0 {
+ fmt.Fprintf(&sb, " summary=%d", b.Summaries)
+ }
+ fmt.Fprintf(&sb, " tool_schemas=%d", b.ToolSchemas)
+ if b.LargestTokens > 0 {
+ fmt.Fprintf(&sb, " largest=%s(%d)", b.LargestKind, b.LargestTokens)
+ }
+ return sb.String()
+}
+
+// logContextPrediction records what this round expects the request to cost,
+// broken down by source, alongside the threshold it is being judged against.
+func (e *AgentEngine) logContextPrediction(
+ ctx context.Context, round int, messages []chat.Message, tools []chat.Tool, predicted int,
+) {
+ settings := e.compactor.Settings()
+ b := e.breakdownContext(messages, tools)
+
+ messagesEst := b.Total - b.ToolSchemas
+ logger.Debugf(ctx, "[Agent][Round-%d][ctx] predicted=%d (baseline_usage=%d + delta) "+
+ "| messages=%d tool_schemas=%d request=%d | threshold=%d window=%d keep_recent=%d",
+ round, predicted, contextTokensFromUsage(e.lastUsage), messagesEst, b.ToolSchemas, b.Total,
+ settings.Threshold(), settings.MaxContextTokens, settings.KeepRecentTokens)
+ logger.Debugf(ctx, "[Agent][Round-%d][ctx] breakdown: %s", round, b)
+
+ // Compaction's predicted size is the messages-only (or usage+delta) figure.
+ // The independent check has to use the same accounting: with a usage
+ // baseline the provider already billed tools, so compare against the full
+ // request; without one, compare against messages alone. Mixing the two is
+ // how a 12k chat with 105k of tool schemas looked like an 8× miss.
+ compare := messagesEst
+ if contextTokensFromUsage(e.lastUsage) > 0 {
+ compare = b.Total
+ }
+ if predicted > 0 && compare > 0 {
+ if ratio := float64(predicted) / float64(compare); ratio > 1.5 || ratio < 0.67 {
+ logger.Warnf(ctx, "[Agent][Round-%d][ctx] usage baseline and direct estimate "+
+ "disagree by %.1fx (predicted=%d, estimated=%d) — one of them is missing "+
+ "content the other counts", round, ratio, predicted, compare)
+ }
+ }
+}
+
+// logContextDrift compares the prediction against what the provider billed.
+// This is the ground truth for whether the estimator is complete: everything
+// else in the pipeline is downstream of getting this number right.
+func (e *AgentEngine) logContextDrift(ctx context.Context, round, predicted int, usage types.TokenUsage) {
+ actual := usage.PromptTokens
+ if actual <= 0 || predicted <= 0 {
+ return
+ }
+ drift := predicted - actual
+ pct := float64(drift) / float64(actual) * 100
+
+ logger.Debugf(ctx, "[Agent][Round-%d][ctx] drift: predicted=%d actual_prompt=%d "+
+ "diff=%+d (%+.1f%%) completion=%d",
+ round, predicted, actual, drift, pct, usage.CompletionTokens)
+
+ // Under-estimating is the dangerous direction: it is how a request gets
+ // sent that the provider then rejects for size.
+ if pct < -25 {
+ logger.Warnf(ctx, "[Agent][Round-%d][ctx] estimate is %.0f%% below the provider's "+
+ "count (predicted=%d actual=%d) — compaction will fire late and cut too little",
+ round, -pct, predicted, actual)
+ } else if pct > 50 {
+ logger.Warnf(ctx, "[Agent][Round-%d][ctx] estimate is %.0f%% above the provider's "+
+ "count (predicted=%d actual=%d) — compaction will fire on a context that fits",
+ round, pct, predicted, actual)
+ }
+}
diff --git a/internal/agent/engine.go b/internal/agent/engine.go
index e710ef433..40f81a103 100644
--- a/internal/agent/engine.go
+++ b/internal/agent/engine.go
@@ -7,7 +7,7 @@ import (
"strings"
"time"
- agentmemory "github.com/Tencent/WeKnora/internal/agent/memory"
+ "github.com/Tencent/WeKnora/internal/agent/compaction"
"github.com/Tencent/WeKnora/internal/agent/skills"
agenttoken "github.com/Tencent/WeKnora/internal/agent/token"
agenttools "github.com/Tencent/WeKnora/internal/agent/tools"
@@ -37,21 +37,30 @@ type AgentEngine struct {
toolRegistry *agenttools.ToolRegistry
chatModel chat.Chat
eventBus *event.EventBus
- knowledgeBasesInfo []*KnowledgeBaseInfo // Detailed knowledge base information for prompt
- selectedDocs []*SelectedDocumentInfo // User-selected documents (via @ mention)
- pinnedMCPServices []*PinnedMCPServiceInfo // User @mentioned MCP services for this turn
- pinnedSkills []*PinnedSkillInfo // User @mentioned skills for this turn
- sessionID string // Session ID for logging and event emission
- systemPromptTemplate string // System prompt template (optional, uses default if empty)
- memoryPrompt string // Long-term memory envelope appended to the system prompt
- skillsManager *skills.Manager // Skills manager for Progressive Disclosure (optional)
- appConfig *appconfig.Config // Application config for prompt template resolution (optional)
- imageDescriber ImageDescriberFunc // VLM function for describing images in tool results (optional)
- tokenEstimator *agenttoken.Estimator // Token estimator for context window management
- memoryConsolidator *agentmemory.Consolidator // Memory consolidator for LLM-powered summarization (optional)
- lastUsage types.TokenUsage // Token usage from the most recent LLM call
- lastSentMsgCount int // Number of messages sent in the most recent LLM call
- modelContext *modelcontext.Registry // single request-local boundary for every model handle
+ knowledgeBasesInfo []*KnowledgeBaseInfo // Detailed knowledge base information for prompt
+ selectedDocs []*SelectedDocumentInfo // User-selected documents (via @ mention)
+ pinnedMCPServices []*PinnedMCPServiceInfo // User @mentioned MCP services for this turn
+ pinnedSkills []*PinnedSkillInfo // User @mentioned skills for this turn
+ sessionID string // Session ID for logging and event emission
+ systemPromptTemplate string // System prompt template (optional, uses default if empty)
+ memoryPrompt string // Long-term memory envelope appended to the system prompt
+ skillsManager *skills.Manager // Skills manager for Progressive Disclosure (optional)
+ appConfig *appconfig.Config // Application config for prompt template resolution (optional)
+ imageDescriber ImageDescriberFunc // VLM function for describing images in tool results (optional)
+ tokenEstimator *agenttoken.Estimator // Token estimator for context window management
+ compactor *compaction.Compactor // Summarizes older history to fit the context window (nil = disabled)
+ lastUsage types.TokenUsage // Token usage from the most recent LLM call
+ lastSentMsgCount int // Number of messages sent in the most recent LLM call
+ // overflowRecovered records that this turn already spent its one
+ // compact-and-retry on a context overflow. A second attempt would mean
+ // history size was never the problem, and looping on it burns the round
+ // budget without changing anything.
+ overflowRecovered bool
+ // compactionExhaustedAt is the message count at which compaction last
+ // reported it could free nothing. Below that count the answer has not
+ // changed, so there is no reason to spend another summarization call.
+ compactionExhaustedAt int
+ modelContext *modelcontext.Registry // single request-local boundary for every model handle
}
// ImageDescriberFunc generates a text description of an image.
@@ -89,12 +98,13 @@ func NewAgentEngine(
modelContext: modelcontext.NewRegistry(config.CitationsEnabled()),
}
- // Initialize memory consolidator if context window management is configured
- if config.MaxContextTokens > 0 {
- engine.memoryConsolidator = agentmemory.NewConsolidator(
- chatModel, tokenEst, config.MaxContextTokens, 0,
- )
- }
+ engine.compactor = compaction.New(chatModel, tokenEst, compaction.Settings{
+ Enabled: true,
+ MaxContextTokens: config.MaxContextTokens,
+ ReserveTokens: engine.contextReserveTokens(),
+ KeepRecentTokens: config.CompactionKeepRecentTokens,
+ MaxSummaryTokens: engine.getCompletionTokenBudget(),
+ })
return engine
}
@@ -189,18 +199,50 @@ func (e *AgentEngine) GetSkillsManager() *skills.Manager {
return e.skillsManager
}
-// estimateCurrentTokens returns the best estimate of the current context token count.
-// When API-reported usage from a previous round is available, it uses that as a
-// baseline and only BPE-estimates the delta (newly appended messages). Otherwise it
-// falls back to a full BPE estimation of all messages.
+// estimateCurrentTokens returns the best estimate of the current context token
+// count:
+//
+// - When API usage from a previous round is available, that number is the
+// baseline (the provider already billed tools + system + history) and only
+// the messages appended since then are BPE-estimated.
+// - Otherwise it is a pure message-size estimate. Tool schemas are NOT
+// added here. Adding 232 tool schemas (~105k) to a 12k conversation made
+// every round look over the 111k threshold even after a successful
+// compaction.
+//
+// The baseline already contains the assistant reply, as the `output` half of
+// the round that produced it. So the delta must start *after* that reply.
func (e *AgentEngine) estimateCurrentTokens(messages []chat.Message) int {
- if e.lastUsage.TotalTokens > 0 && e.lastSentMsgCount > 0 && e.lastSentMsgCount < len(messages) {
- delta := e.tokenEstimator.EstimateMessages(messages[e.lastSentMsgCount:])
- return e.lastUsage.TotalTokens + delta
+ if baseline := contextTokensFromUsage(e.lastUsage); baseline > 0 &&
+ e.lastSentMsgCount > 0 && e.lastSentMsgCount <= len(messages) {
+ return baseline + e.tokenEstimator.EstimateMessages(messages[e.deltaStart(messages):])
}
return e.tokenEstimator.EstimateMessages(messages)
}
+// deltaStart is the first message not already accounted for by e.lastUsage.
+func (e *AgentEngine) deltaStart(messages []chat.Message) int {
+ start := e.lastSentMsgCount
+ // The reply to the previous request lands here. Its tokens are the usage's
+ // completion half, so skip it — but only if it is really there, since a
+ // failed round appends nothing.
+ if start < len(messages) && messages[start].Role == "assistant" {
+ start++
+ }
+ return start
+}
+
+// contextTokensFromUsage reduces a usage report to the size of the context it
+// describes. Cache counters are not added in: WeKnora normalizes PromptTokens
+// to the provider's full input count, with read/write/miss as descriptive
+// subsets of it (see types.TokenUsage.SetPromptCacheUsage).
+func contextTokensFromUsage(usage types.TokenUsage) int {
+ if usage.TotalTokens > 0 {
+ return usage.TotalTokens
+ }
+ return usage.PromptTokens + usage.CompletionTokens
+}
+
// Execute executes the agent with conversation history and streaming output
// All events are emitted to EventBus and handled by subscribers (like Handler layer)
func (e *AgentEngine) Execute(
@@ -357,6 +399,30 @@ func truncateRunes(s string, n int) string {
return string(r[:n]) + "…"
}
+// withinIterationBudget reports whether another ReAct round is allowed.
+// A negative MaxIterations is unlimited: the loop still stops on a natural
+// finish, user cancel, empty-response retries, or a repeated-content stall.
+func (e *AgentEngine) withinIterationBudget(round int) bool {
+ if e.config == nil {
+ return false
+ }
+ if e.config.UnlimitedIterations() {
+ return true
+ }
+ return round < e.config.MaxIterations
+}
+
+func (e *AgentEngine) maxIterationsDisplay() string {
+ if e.config != nil && e.config.UnlimitedIterations() {
+ return "unlimited"
+ }
+ n := 0
+ if e.config != nil {
+ n = e.config.MaxIterations
+ }
+ return fmt.Sprintf("%d", n)
+}
+
// executeLoop executes the main ReAct loop
// All events are emitted through EventBus with the given sessionID
func (e *AgentEngine) executeLoop(
@@ -394,7 +460,7 @@ func (e *AgentEngine) executeLoop(
consecutiveSameContent := 0
lastResponseContent := ""
loop:
- for state.CurrentRound < e.config.MaxIterations {
+ for e.withinIterationBudget(state.CurrentRound) {
// Check for context cancellation (request timeout, user cancel, etc.)
select {
case <-ctx.Done():
@@ -526,18 +592,20 @@ func (e *AgentEngine) runReActIteration(
}, retErr)
}()
- // Context window management: estimate current token count using
- // the API-reported usage from the previous round plus a BPE delta
- // for newly appended messages (assistant reply + tool results).
+ // Compact older history before the next assistant response when the
+ // estimate is over the threshold. The trigger is estimateCurrentTokens —
+ // usage+delta when a previous round reported one, otherwise the message
+ // list alone. Tool schemas are not added here.
currentTokens := e.estimateCurrentTokens(*messagesPtr)
- beforeLen := len(*messagesPtr)
- *messagesPtr = e.manageContextWindow(ctx, *messagesPtr, round, currentTokens)
- if len(*messagesPtr) < beforeLen {
- currentTokens = e.tokenEstimator.EstimateMessages(*messagesPtr)
+ managed, changed := e.manageContextWindow(ctx, *messagesPtr, round, currentTokens)
+ if changed {
+ *messagesPtr = managed
+ currentTokens = e.tokenEstimator.EstimateMessages(managed)
}
- logger.Infof(ctx, "[Agent][Round-%d/%d] Starting: %d messages, %d tools, est_tokens=%d",
- round, e.config.MaxIterations, len(*messagesPtr), len(tools), currentTokens)
+ logger.Infof(ctx, "[Agent][Round-%d/%s] Starting: %d messages, %d tools, est_tokens=%d",
+ round, e.maxIterationsDisplay(), len(*messagesPtr), len(tools), currentTokens)
+ e.logContextPrediction(ctx, round, *messagesPtr, tools, currentTokens)
common.PipelineInfo(ctx, "Agent", "round_start", map[string]interface{}{
"iteration": state.CurrentRound,
"round": round,
@@ -548,7 +616,7 @@ func (e *AgentEngine) runReActIteration(
// 1. Think: Call LLM with function calling (includes retry + graceful degradation)
e.lastSentMsgCount = len(*messagesPtr)
- resp, err := e.callLLMWithRetry(ctx, *messagesPtr, tools, state, query, state.CurrentRound, sessionID)
+ resp, err := e.callLLMWithRetry(ctx, messagesPtr, tools, state, query, state.CurrentRound, sessionID)
if err != nil {
retErr = err
return iterOutcomeNext, err
@@ -556,7 +624,30 @@ func (e *AgentEngine) runReActIteration(
if resp == nil {
return iterOutcomeBreak, nil
}
+
+ // The round's own token estimate can be wrong — history is estimated, not
+ // counted — so a request that looked safe can still come back having hit
+ // the window. Compacting and retrying once turns that into a recovered
+ // round instead of a wasted one. Once per turn: if the retry overflows
+ // too, the problem is not the history size.
+ if !e.overflowRecovered && e.responseHitContextLimit(resp) {
+ e.overflowRecovered = true
+ logger.Warnf(ctx, "[Agent][Round-%d] Response hit the context window (finish=%s, "+
+ "completion=%d of %d requested); compacting and retrying once",
+ round, resp.FinishReason, resp.Usage.CompletionTokens, e.getCompletionTokenBudget())
+ *messagesPtr = e.forceCompaction(ctx, *messagesPtr, round)
+ e.lastSentMsgCount = len(*messagesPtr)
+ resp, err = e.callLLMWithRetry(ctx, messagesPtr, tools, state, query, state.CurrentRound, sessionID)
+ if err != nil {
+ retErr = err
+ return iterOutcomeNext, err
+ }
+ if resp == nil {
+ return iterOutcomeBreak, nil
+ }
+ }
response = resp
+ e.logContextDrift(ctx, round, currentTokens, response.Usage)
if response.Usage.TotalTokens > 0 {
e.lastUsage = response.Usage
state.TurnUsage.Accumulate(response.Usage)
diff --git a/internal/agent/engine_test.go b/internal/agent/engine_test.go
index 5823ff88e..90728f52c 100644
--- a/internal/agent/engine_test.go
+++ b/internal/agent/engine_test.go
@@ -4,9 +4,11 @@ import (
"context"
"encoding/json"
"fmt"
+ "strings"
"sync"
"testing"
+ "github.com/Tencent/WeKnora/internal/agent/compaction"
agenttools "github.com/Tencent/WeKnora/internal/agent/tools"
"github.com/Tencent/WeKnora/internal/event"
"github.com/Tencent/WeKnora/internal/modelcontext"
@@ -140,6 +142,40 @@ func TestStreamLLMSummarySlugSurvivesDocumentCompaction(t *testing.T) {
require.NotContains(t, result.ToolCalls[0].Function.Arguments, "res://")
}
+// Reproduces the round that ended a 40-round conversation: the stream broke
+// while serializing a large write_sandbox_file call, after a short preamble had
+// already streamed. Treating that as a completed turn let the preamble stand in
+// as the final answer and dropped the call, so the stream error must surface.
+func TestStreamLLMToEventBus_ErrorAfterContent_IsNotASuccessfulTurn(t *testing.T) {
+ model := &mockChat{responses: []mockResponse{{chunks: []types.StreamResponse{
+ {ResponseType: types.ResponseTypeAnswer, Content: "非常好,我已经获取了骨架模板。"},
+ {
+ ResponseType: types.ResponseTypeError,
+ Content: "context deadline exceeded",
+ Done: true,
+ FinishReason: types.FinishReasonIncomplete,
+ ToolCalls: []types.LLMToolCall{{
+ ID: "call-1",
+ Function: types.FunctionCall{
+ Name: "write_sandbox_file",
+ Arguments: "{\"path\":\"/a.html\",\"content\":\"<htm",
+ },
+ }},
+ },
+ }}}}
+
+ engine := newTestEngine(t, model)
+ result, err := engine.streamLLMToEventBus(context.Background(), nil, nil, nil)
+
+ require.Error(t, err, "a broken stream must not be reported as a completed turn")
+ require.Contains(t, err.Error(), "context deadline exceeded")
+ // The partial call rides along for diagnostics, and the finish reason must
+ // never fall back to "stop" — that fallback is what ended the conversation.
+ require.Len(t, result.ToolCalls, 1)
+ require.Equal(t, types.FinishReasonIncomplete, result.FinishReason)
+ require.True(t, isTransientError(err), "a broken stream must be retryable")
+}
+
func TestStreamLLMChunkReferenceExpandsBeforeEmission(t *testing.T) {
model := &mockChat{responses: []mockResponse{{chunks: []types.StreamResponse{
{ResponseType: types.ResponseTypeAnswer, Content: `answer <ref id="`},
@@ -252,6 +288,204 @@ func withMaxCompletionTokens(n int) testEngineOption {
}
}
+func withMaxContextTokens(n int) testEngineOption {
+ return func(cfg *types.AgentConfig) {
+ cfg.MaxContextTokens = n
+ }
+}
+
+func TestWithinIterationBudgetUnlimited(t *testing.T) {
+ unlimited := newTestEngine(t, &mockChat{}, withMaxIterations(types.UnlimitedMaxIterations))
+ require.True(t, unlimited.withinIterationBudget(0))
+ require.True(t, unlimited.withinIterationBudget(10_000))
+ require.Equal(t, "unlimited", unlimited.maxIterationsDisplay())
+
+ capped := newTestEngine(t, &mockChat{}, withMaxIterations(3))
+ require.True(t, capped.withinIterationBudget(0))
+ require.True(t, capped.withinIterationBudget(2))
+ require.False(t, capped.withinIterationBudget(3))
+ require.Equal(t, "3", capped.maxIterationsDisplay())
+}
+
+// History may not fill the window: the reply has to land somewhere. A reserve
+// expressed as a fraction of the window gets this wrong in both directions —
+// too little room on a small window, needlessly early compaction on a big one.
+func TestContextCompactionThresholdReservesRoomForTheReply(t *testing.T) {
+ engine := newTestEngine(t, &mockChat{},
+ withMaxContextTokens(128000), withMaxCompletionTokens(24576))
+
+ // Reserve is the round's own output budget plus estimation slack.
+ require.Equal(t, 24576+contextSafetyTokens, engine.contextReserveTokens())
+ require.Equal(t, 128000-24576-contextSafetyTokens, engine.compactor.Settings().Threshold())
+
+ // A tiny completion budget still keeps a floor of headroom, rather than
+ // letting history run to the very edge of the window.
+ small := newTestEngine(t, &mockChat{},
+ withMaxContextTokens(128000), withMaxCompletionTokens(1024))
+ require.Equal(t, compaction.DefaultReserveTokens, small.contextReserveTokens())
+
+ // An unknown window disables compaction rather than guessing.
+ require.Nil(t, newTestEngine(t, &mockChat{}).compactor)
+ require.Zero(t, newTestEngine(t, &mockChat{}).compactor.Settings().Threshold())
+}
+
+// The usage baseline already includes the assistant reply as its `output`
+// half. Starting the delta at that reply counts every completion twice, and
+// since the engine re-anchors on fresh usage each round the error rides along
+// permanently — inflating the estimate enough to trigger compaction on a
+// context that is nowhere near the threshold.
+func TestEstimateCurrentTokensDoesNotDoubleCountTheReply(t *testing.T) {
+ engine := newTestEngine(t, &mockChat{}, withMaxContextTokens(128000))
+
+ sent := []chat.Message{
+ {Role: "system", Content: "you are an agent"},
+ {Role: "user", Content: "do the thing"},
+ }
+ reply := chat.Message{
+ Role: "assistant",
+ Content: "working on it",
+ ReasoningContent: strings.Repeat("deliberating carefully. ", 200),
+ }
+ toolResult := chat.Message{Role: "tool", Name: "t", ToolCallID: "c1", Content: "result"}
+ messages := append(append([]chat.Message{}, sent...), reply, toolResult)
+
+ // The provider reported this round: 5000 in, and the reply as output.
+ replyTokens := engine.tokenEstimator.EstimateMessage(&reply)
+ engine.lastSentMsgCount = len(sent)
+ engine.lastUsage = types.TokenUsage{
+ PromptTokens: 5000,
+ CompletionTokens: replyTokens,
+ TotalTokens: 5000 + replyTokens,
+ }
+
+ got := engine.estimateCurrentTokens(messages)
+ want := 5000 + replyTokens + engine.tokenEstimator.EstimateMessages(messages[len(sent)+1:])
+ require.Equal(t, want, got)
+
+ // Stated as the property that actually matters: the reply is counted once.
+ require.Less(t, got, 5000+2*replyTokens,
+ "the assistant reply must not be billed by both the usage baseline and the delta")
+}
+
+// The compaction trigger counts conversation only. Tool schemas ride with
+// every request and show up in the provider's usage, but they are not added
+// to a no-usage estimate — doing so made a 12k chat with 232 MCP tools look
+// like 117k and compact every round, including the first.
+func TestEstimateCurrentTokensDoesNotCountToolSchemasWithoutUsage(t *testing.T) {
+ engine := newTestEngine(t, &mockChat{}, withMaxContextTokens(128000))
+
+ messages := []chat.Message{
+ {Role: "system", Content: "you are an agent"},
+ {Role: "user", Content: "do the thing"},
+ }
+ tools := make([]chat.Tool, 80)
+ for i := range tools {
+ tools[i] = chat.Tool{
+ Type: "function",
+ Function: chat.FunctionDef{
+ Name: fmt.Sprintf("tool_%d", i),
+ Description: strings.Repeat("does something useful. ", 80),
+ Parameters: []byte(`{"type":"object","properties":{"path":{"type":"string"}}}`),
+ },
+ }
+ }
+
+ got := engine.estimateCurrentTokens(messages)
+ require.Equal(t, engine.tokenEstimator.EstimateMessages(messages), got)
+
+ schemaTokens := engine.tokenEstimator.EstimateTools(tools)
+ require.Greater(t, schemaTokens, got*50,
+ "the fixture has to dwarf the conversation, the way a large MCP tool list does")
+ require.False(t, engine.compactor.Settings().ShouldCompact(got),
+ "a two-message conversation must not cross the threshold")
+}
+
+// summarizerChat counts summarization calls so a test can prove the engine is
+// not paying for one every round.
+type summarizerChat struct {
+ mockChat
+ calls int
+}
+
+func (s *summarizerChat) Chat(
+ context.Context, []chat.Message, *chat.ChatOptions,
+) (*types.ChatResponse, error) {
+ s.calls++
+ return &types.ChatResponse{Content: "## Goal\ndo the thing", FinishReason: "stop"}, nil
+}
+
+// The bug this replaces: inside one ReAct turn nothing was compactable, so
+// every round crossed the threshold, spent a summarization call, and freed
+// nothing. The loop is only broken if a second pass over the compacted context
+// declines to call the summarizer again.
+func TestContextCompactionDoesNotRunEveryRound(t *testing.T) {
+ llm := &summarizerChat{}
+ engine := newTestEngine(t, llm,
+ withMaxContextTokens(40000), withMaxCompletionTokens(4000))
+
+ // One user message, then many assistant/tool rounds — a ReAct turn with
+ // no turn boundary anywhere in it.
+ messages := []chat.Message{
+ {Role: "system", Content: "you are an agent"},
+ {Role: "user", Content: "build me a deck"},
+ }
+ body := strings.Repeat("tool output content ", 400)
+ for i := 0; i < 20; i++ {
+ id := fmt.Sprintf("call-%d", i)
+ messages = append(messages,
+ chat.Message{Role: "assistant", ToolCalls: []chat.ToolCall{{
+ ID: id,
+ Type: "function",
+ Function: chat.FunctionCall{Name: "write_sandbox_file", Arguments: `{"path":"/w/a.html"}`},
+ }}},
+ chat.Message{Role: "tool", Name: "write_sandbox_file", ToolCallID: id, Content: body},
+ )
+ }
+
+ before := engine.tokenEstimator.EstimateMessages(messages)
+ require.True(t, engine.compactor.Settings().ShouldCompact(before))
+
+ compacted, changed := engine.manageContextWindow(
+ context.Background(), messages, 1, before,
+ )
+ require.True(t, changed)
+ after := engine.tokenEstimator.EstimateMessages(compacted)
+ require.Less(t, after, before/2, "compaction has to actually free room")
+ callsAfterFirst := llm.calls
+ require.Positive(t, callsAfterFirst)
+
+ // Second round over the already-compacted context: no LLM call, because
+ // there is nothing left outside the keep-recent budget.
+ _, changedAgain := engine.manageContextWindow(
+ context.Background(), compacted, 2, after,
+ )
+ require.False(t, changedAgain)
+ require.Equal(t, callsAfterFirst, llm.calls,
+ "a context that cannot shrink must not spend another summarization call")
+}
+
+// Asking for more output than the window can still hold is rejected outright
+// by the provider, which surfaces to the agent as an unexplained failure.
+func TestClampCompletionBudgetToContext(t *testing.T) {
+ engine := newTestEngine(t, &mockChat{},
+ withMaxContextTokens(32000), withMaxCompletionTokens(24576))
+
+ // Plenty of room: the configured budget is untouched.
+ require.Equal(t, 24576, engine.clampCompletionBudgetToContext(1000))
+
+ // Filling up: the budget shrinks to what is actually left.
+ require.Equal(t, 32000-20000-contextSafetyTokens,
+ engine.clampCompletionBudgetToContext(20000))
+
+ // Past full: never returns zero or negative, which providers reject.
+ require.Positive(t, engine.clampCompletionBudgetToContext(40000))
+
+ // Unknown window means nothing to clamp against.
+ require.Equal(t, 24576,
+ newTestEngine(t, &mockChat{}, withMaxCompletionTokens(24576)).
+ clampCompletionBudgetToContext(999999))
+}
+
func TestBuildSystemPromptUsesInternalCitationSetting(t *testing.T) {
model := &mockChat{}
enabledEngine := newTestEngine(t, model)
diff --git a/internal/agent/finalize.go b/internal/agent/finalize.go
index 498e55194..72c2d19a3 100644
--- a/internal/agent/finalize.go
+++ b/internal/agent/finalize.go
@@ -97,7 +97,7 @@ Now generate the final answer:`, query, imageRequirement)
logger.Debugf(ctx, "[Agent][FinalAnswer] AnswerID: %s", answerID)
answerDoneEmitted := false
- budget := e.getCompletionTokenBudget()
+ budget := e.clampCompletionBudgetToContext(e.tokenEstimator.EstimateMessages(messages))
llmResult, err := e.streamLLMToEventBus(
ctx,
messages,
diff --git a/internal/agent/memory/consolidator.go b/internal/agent/memory/consolidator.go
deleted file mode 100644
index 22f15e636..000000000
--- a/internal/agent/memory/consolidator.go
+++ /dev/null
@@ -1,337 +0,0 @@
-// Package memory provides LLM-powered memory consolidation for agent conversations.
-// When the context window grows too large, older messages are summarized by the LLM
-// into a compact memory block that preserves key facts and tool results.
-package memory
-
-import (
- "context"
- "fmt"
- "strings"
- "time"
-
- "github.com/Tencent/WeKnora/internal/agent/token"
- "github.com/Tencent/WeKnora/internal/logger"
- "github.com/Tencent/WeKnora/internal/models/chat"
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- // DefaultConsolidationThreshold is the ratio of context window that triggers consolidation.
- // When token count exceeds MaxContextTokens * threshold, consolidation is triggered.
- DefaultConsolidationThreshold = 0.5
-
- // maxConsolidationAttempts is the maximum number of LLM calls for consolidation.
- // After this many failures, fall back to raw archiving.
- maxConsolidationAttempts = 3
-
- // consolidationTimeout is the timeout for the consolidation LLM call.
- consolidationTimeout = 60 * time.Second
-)
-
-// Consolidator compresses agent conversation history using LLM summarization.
-// When the message history grows too large for the context window, it summarizes
-// older messages into a compact system message that preserves key facts.
-type Consolidator struct {
- chatModel chat.Chat
- estimator *token.Estimator
- maxTokens int // context window size
- threshold float64 // trigger ratio (default 0.5)
-}
-
-// NewConsolidator creates a memory consolidator.
-// maxContextTokens is the total context window budget.
-// threshold is the ratio (0-1) at which consolidation triggers (0 = use default 0.5).
-func NewConsolidator(
- chatModel chat.Chat,
- estimator *token.Estimator,
- maxContextTokens int,
- threshold float64,
-) *Consolidator {
- if threshold <= 0 || threshold >= 1 {
- threshold = DefaultConsolidationThreshold
- }
- return &Consolidator{
- chatModel: chatModel,
- estimator: estimator,
- maxTokens: maxContextTokens,
- threshold: threshold,
- }
-}
-
-// ShouldConsolidate checks if consolidation is needed based on the caller-provided
-// token estimate. The estimate should come from the model API's Usage when available.
-func (c *Consolidator) ShouldConsolidate(currentTokens int) bool {
- if c.maxTokens <= 0 {
- return false
- }
- triggerAt := int(float64(c.maxTokens) * c.threshold)
- return currentTokens > triggerAt
-}
-
-// Consolidate summarizes older messages and returns a compressed message array.
-// It preserves:
-// - The system prompt (first message)
-// - The current turn: user query (last user message) and all subsequent
-// assistant/tool messages belonging to the same turn
-// - Recent history messages that fit within the token budget
-//
-// Older history messages are replaced with a summary system message.
-// On LLM failure after maxConsolidationAttempts, falls back to raw text archiving.
-func (c *Consolidator) Consolidate(
- ctx context.Context,
- messages []chat.Message,
-) ([]chat.Message, error) {
- if len(messages) <= 3 {
- return messages, nil
- }
-
- systemMsg := messages[0]
-
- // Find the current user query — the last message with role "user".
- // Everything from this point onward (user query + assistant tool_calls +
- // tool results) is the active turn and must be preserved intact.
- lastUserIdx := 0
- for i := len(messages) - 1; i >= 1; i-- {
- if messages[i].Role == "user" {
- lastUserIdx = i
- break
- }
- }
- if lastUserIdx <= 1 {
- return messages, nil
- }
-
- history := messages[1:lastUserIdx]
- tail := messages[lastUserIdx:]
-
- if len(history) < 2 {
- return messages, nil
- }
-
- targetTokens := int(float64(c.maxTokens) * c.threshold * 0.6) // aim for 60% of threshold
-
- tailTokens := 0
- for i := range tail {
- tailTokens += c.estimator.EstimateMessage(&tail[i])
- }
-
- keepFromEnd := c.findKeepBoundary(history, targetTokens, &systemMsg, tailTokens)
-
- if keepFromEnd >= len(history) {
- return messages, nil
- }
-
- toConsolidate := history[:len(history)-keepFromEnd]
- toKeep := history[len(history)-keepFromEnd:]
-
- summary, err := c.summarizeWithRetry(ctx, toConsolidate)
- if err != nil {
- logger.Warnf(ctx, "[MemoryConsolidator] LLM summarization failed after retries, "+
- "falling back to raw archive: %v", err)
- summary = c.rawArchive(toConsolidate)
- }
-
- summaryMsg := chat.Message{
- Role: "system",
- Content: fmt.Sprintf(
- "[Memory Summary - %d earlier messages consolidated]\n\n%s",
- len(toConsolidate), summary,
- ),
- }
-
- result := make([]chat.Message, 0, 2+len(toKeep)+len(tail))
- result = append(result, systemMsg)
- result = append(result, summaryMsg)
- result = append(result, toKeep...)
- result = append(result, tail...)
-
- logger.Infof(ctx, "[MemoryConsolidator] Consolidated %d messages → summary (%d chars), "+
- "keeping %d history + %d current-turn messages",
- len(toConsolidate), len(summary), len(toKeep), len(tail))
-
- return result, nil
-}
-
-// findKeepBoundary determines how many messages from the end of history to keep.
-// Returns the count of messages to keep (from the end), respecting tool_call/tool_result boundaries.
-// tailTokens is the token cost of the current-turn tail that is always preserved.
-func (c *Consolidator) findKeepBoundary(
- history []chat.Message,
- targetTokens int,
- systemMsg *chat.Message,
- tailTokens int,
-) int {
- budget := targetTokens -
- c.estimator.EstimateMessage(systemMsg) -
- tailTokens -
- 500 // reserve for summary message
-
- if budget <= 0 {
- return 0
- }
-
- tokens := 0
- keepCount := 0
- i := len(history) - 1
-
- for i >= 0 {
- msg := history[i]
- msgTokens := c.estimator.EstimateMessage(&msg)
-
- if msg.Role == "tool" {
- groupTokens := msgTokens
- groupSize := 1
- j := i - 1
- for j >= 0 && history[j].Role == "tool" {
- groupTokens += c.estimator.EstimateMessage(&history[j])
- groupSize++
- j--
- }
- if j >= 0 && history[j].Role == "assistant" {
- groupTokens += c.estimator.EstimateMessage(&history[j])
- groupSize++
- }
-
- if tokens+groupTokens > budget {
- break
- }
- tokens += groupTokens
- keepCount += groupSize
- i -= groupSize
- } else {
- if tokens+msgTokens > budget {
- break
- }
- tokens += msgTokens
- keepCount++
- i--
- }
- }
-
- return keepCount
-}
-
-// summarizeWithRetry attempts LLM summarization with retries.
-func (c *Consolidator) summarizeWithRetry(
- ctx context.Context,
- messages []chat.Message,
-) (string, error) {
- prompt := c.buildConsolidationPrompt(messages)
- var lastErr error
-
- for attempt := 1; attempt <= maxConsolidationAttempts; attempt++ {
- summarizeCtx, cancel := context.WithTimeout(ctx, consolidationTimeout)
- summarizeCtx = types.WithLLMCallMetadata(summarizeCtx, "agent_memory_consolidation", "")
-
- resp, err := c.chatModel.Chat(summarizeCtx, []chat.Message{
- {Role: "system", Content: consolidationSystemPrompt},
- {Role: "user", Content: prompt},
- }, &chat.ChatOptions{
- Temperature: 0.3, // low temperature for factual summarization
- MaxTokens: 2000,
- })
- cancel()
-
- if err != nil {
- lastErr = err
- logger.Warnf(ctx, "[MemoryConsolidator] Summarization attempt %d/%d failed: %v",
- attempt, maxConsolidationAttempts, err)
- continue
- }
-
- if resp != nil && resp.Content != "" {
- return resp.Content, nil
- }
- lastErr = fmt.Errorf("empty response from LLM")
- }
-
- return "", fmt.Errorf("summarization failed after %d attempts: %w",
- maxConsolidationAttempts, lastErr)
-}
-
-// buildConsolidationPrompt creates the prompt for LLM to summarize messages.
-func (c *Consolidator) buildConsolidationPrompt(messages []chat.Message) string {
- var sb strings.Builder
- sb.WriteString("Summarize the following conversation history, preserving:\n")
- sb.WriteString("1. Key facts and decisions made\n")
- sb.WriteString("2. Tool execution results and their outcomes\n")
- sb.WriteString("3. User's original intent and requirements\n")
- sb.WriteString("4. Any errors encountered and how they were resolved\n\n")
- sb.WriteString("Conversation to summarize:\n\n")
-
- for _, msg := range messages {
- switch msg.Role {
- case "user":
- sb.WriteString(fmt.Sprintf("**User**: %s\n\n", truncateForPrompt(msg.Content, 2000)))
- case "assistant":
- if len(msg.ToolCalls) > 0 {
- names := make([]string, len(msg.ToolCalls))
- for i, tc := range msg.ToolCalls {
- names[i] = tc.Function.Name
- }
- sb.WriteString(fmt.Sprintf("**Assistant** [called tools: %s]: %s\n\n",
- strings.Join(names, ", "), truncateForPrompt(msg.Content, 1000)))
- } else {
- sb.WriteString(fmt.Sprintf("**Assistant**: %s\n\n",
- truncateForPrompt(msg.Content, 2000)))
- }
- case "tool":
- sb.WriteString(fmt.Sprintf("**Tool [%s]**: %s\n\n",
- msg.Name, truncateForPrompt(msg.Content, 1000)))
- }
- }
-
- return sb.String()
-}
-
-// rawArchive creates a simple text dump of messages as fallback when LLM fails.
-func (c *Consolidator) rawArchive(messages []chat.Message) string {
- var sb strings.Builder
- sb.WriteString("Raw conversation archive (LLM summarization unavailable):\n\n")
-
- for _, msg := range messages {
- content := truncateForPrompt(msg.Content, 500)
- switch msg.Role {
- case "user":
- sb.WriteString(fmt.Sprintf("- User: %s\n", content))
- case "assistant":
- if len(msg.ToolCalls) > 0 {
- names := make([]string, len(msg.ToolCalls))
- for j, tc := range msg.ToolCalls {
- names[j] = tc.Function.Name
- }
- sb.WriteString(fmt.Sprintf("- Assistant [tools: %s]: %s\n",
- strings.Join(names, ","), content))
- } else {
- sb.WriteString(fmt.Sprintf("- Assistant: %s\n", content))
- }
- case "tool":
- sb.WriteString(fmt.Sprintf("- Tool[%s]: %s\n", msg.Name, content))
- }
- }
-
- return sb.String()
-}
-
-// truncateForPrompt truncates a string to maxLen characters for use in prompts.
-func truncateForPrompt(s string, maxLen int) string {
- runes := []rune(s)
- if len(runes) <= maxLen {
- return s
- }
- return string(runes[:maxLen]) + "..."
-}
-
-//nolint:lll // raw string literal used for prompt readability
-const consolidationSystemPrompt = "" +
- "You are a conversation summarizer. " +
- "Your task is to create a concise but comprehensive summary " +
- "of a conversation between a user and an AI assistant.\n\n" +
- "The summary should:\n" +
- "- Be written in the same language as the original conversation\n" +
- "- Preserve all key facts, numbers, and specific details\n" +
- "- Include the outcomes of any tool executions\n" +
- "- Note any errors or issues encountered\n" +
- "- Be structured with clear sections if the conversation covered multiple topics\n" +
- "- Be concise — aim for 30% or less of the original length\n\n" +
- "Output only the summary, no preamble or explanation."
diff --git a/internal/agent/memory/consolidator_test.go b/internal/agent/memory/consolidator_test.go
deleted file mode 100644
index 1c46c45a5..000000000
--- a/internal/agent/memory/consolidator_test.go
+++ /dev/null
@@ -1,374 +0,0 @@
-package memory
-
-import (
- "context"
- "strings"
- "testing"
-
- "github.com/Tencent/WeKnora/internal/agent/token"
- "github.com/Tencent/WeKnora/internal/models/chat"
- "github.com/Tencent/WeKnora/internal/types"
- "github.com/stretchr/testify/assert"
- "github.com/stretchr/testify/require"
-)
-
-// stubChat is a minimal chat.Chat implementation for testing consolidation.
-type stubChat struct {
- response string
- err error
-}
-
-func (s *stubChat) Chat(_ context.Context, _ []chat.Message, _ *chat.ChatOptions) (*types.ChatResponse, error) {
- if s.err != nil {
- return nil, s.err
- }
- return &types.ChatResponse{Content: s.response}, nil
-}
-
-func (s *stubChat) ChatStream(context.Context, []chat.Message, *chat.ChatOptions) (<-chan types.StreamResponse, error) {
- return nil, nil
-}
-
-func (s *stubChat) GetModelName() string { return "stub" }
-func (s *stubChat) GetModelID() string { return "stub" }
-
-func TestConsolidator_ShouldConsolidate(t *testing.T) {
- est, err := token.NewEstimator()
- assert.NoError(t, err)
-
- t.Run("below threshold returns false", func(t *testing.T) {
- c := NewConsolidator(nil, est, 100000, 0)
- messages := []chat.Message{
- {Role: "system", Content: "system prompt"},
- {Role: "user", Content: "hello"},
- {Role: "assistant", Content: "hi"},
- {Role: "user", Content: "current"},
- }
- tokens := est.EstimateMessages(messages)
- assert.False(t, c.ShouldConsolidate(tokens))
- })
-
- t.Run("over threshold returns true", func(t *testing.T) {
- c := NewConsolidator(nil, est, 10, 0) // very low threshold
- assert.True(t, c.ShouldConsolidate(100))
- })
-
- t.Run("disabled returns false", func(t *testing.T) {
- c := NewConsolidator(nil, est, 0, 0)
- assert.False(t, c.ShouldConsolidate(99999))
- })
-}
-
-func TestTruncateForPrompt(t *testing.T) {
- t.Run("short string unchanged", func(t *testing.T) {
- assert.Equal(t, "hello", truncateForPrompt("hello", 100))
- })
-
- t.Run("long string truncated", func(t *testing.T) {
- result := truncateForPrompt("hello world this is long", 10)
- assert.Equal(t, "hello worl...", result)
- })
-
- t.Run("CJK string truncated by rune", func(t *testing.T) {
- input := "你好世界测试数据中文字符串"
- result := truncateForPrompt(input, 5)
- assert.Equal(t, "你好世界测...", result)
- })
-}
-
-func TestRawArchive(t *testing.T) {
- est, err := token.NewEstimator()
- assert.NoError(t, err)
- c := NewConsolidator(nil, est, 100000, 0)
-
- messages := []chat.Message{
- {Role: "user", Content: "search for X"},
- {
- Role: "assistant", Content: "let me search",
- ToolCalls: []chat.ToolCall{
- {Function: chat.FunctionCall{Name: "knowledge_search"}},
- },
- },
- {Role: "tool", Content: "result data", Name: "knowledge_search"},
- }
-
- result := c.rawArchive(messages)
- assert.Contains(t, result, "Raw conversation archive")
- assert.Contains(t, result, "User: search for X")
- assert.Contains(t, result, "knowledge_search")
- assert.Contains(t, result, "Tool[knowledge_search]: result data")
-}
-
-func TestBuildConsolidationPrompt(t *testing.T) {
- est, err := token.NewEstimator()
- assert.NoError(t, err)
- c := NewConsolidator(nil, est, 100000, 0)
-
- messages := []chat.Message{
- {Role: "user", Content: "find info about AI"},
- {Role: "assistant", Content: "searching...", ToolCalls: []chat.ToolCall{
- {Function: chat.FunctionCall{Name: "web_search"}},
- }},
- {Role: "tool", Content: "results here", Name: "web_search"},
- }
-
- prompt := c.buildConsolidationPrompt(messages)
- assert.Contains(t, prompt, "**User**: find info about AI")
- assert.Contains(t, prompt, "web_search")
- assert.Contains(t, prompt, "**Tool [web_search]**: results here")
-}
-
-// ---------- Consolidate() 核心流程测试 ----------
-
-func TestConsolidate_TooFewMessages(t *testing.T) {
- est, err := token.NewEstimator()
- require.NoError(t, err)
- c := NewConsolidator(&stubChat{response: "summary"}, est, 100, 0)
-
- msgs := []chat.Message{
- {Role: "system", Content: "sys"},
- {Role: "user", Content: "hi"},
- {Role: "assistant", Content: "hello"},
- }
- result, err := c.Consolidate(context.Background(), msgs)
- require.NoError(t, err)
- assert.Equal(t, msgs, result, "<=3 messages should be returned unchanged")
-}
-
-func TestConsolidate_Round1_UserQueryAtEnd(t *testing.T) {
- est, err := token.NewEstimator()
- require.NoError(t, err)
-
- // Use a stub that returns a known summary.
- c := NewConsolidator(&stubChat{response: "summary of old history"}, est, 200, 0)
-
- long := strings.Repeat("old context data ", 200)
- msgs := []chat.Message{
- {Role: "system", Content: "You are a helpful assistant"},
- {Role: "user", Content: long},
- {Role: "assistant", Content: long},
- {Role: "user", Content: long},
- {Role: "assistant", Content: long},
- {Role: "user", Content: "current question"}, // last user = current query
- }
-
- result, err := c.Consolidate(context.Background(), msgs)
- require.NoError(t, err)
-
- // System prompt is preserved.
- assert.Equal(t, "system", result[0].Role)
- assert.Equal(t, "You are a helpful assistant", result[0].Content)
-
- // The current user query (last user message) must be preserved at the tail.
- last := result[len(result)-1]
- assert.Equal(t, "user", last.Role)
- assert.Equal(t, "current question", last.Content)
-
- // A summary message must have been inserted.
- assert.Equal(t, "system", result[1].Role)
- assert.Contains(t, result[1].Content, "Memory Summary")
-
- // Total message count should be fewer than original.
- assert.Less(t, len(result), len(msgs))
-}
-
-func TestConsolidate_Round2Plus_UserQueryNotAtEnd(t *testing.T) {
- est, err := token.NewEstimator()
- require.NoError(t, err)
-
- c := NewConsolidator(&stubChat{response: "consolidated history"}, est, 300, 0)
-
- longContent := strings.Repeat("verbose content ", 200)
-
- // Simulates Agent Round 2+:
- // [system, ...old_history..., user_query, assistant+tools, tool_results]
- // The user query is NOT the last message.
- msgs := []chat.Message{
- {Role: "system", Content: "You are a helpful assistant"},
- // --- old history (from previous turns) ---
- {Role: "user", Content: longContent},
- {Role: "assistant", Content: longContent},
- {Role: "user", Content: longContent},
- {Role: "assistant", Content: longContent, ToolCalls: []chat.ToolCall{
- {ID: "old_call", Function: chat.FunctionCall{Name: "search", Arguments: `{}`}},
- }},
- {Role: "tool", Content: longContent, ToolCallID: "old_call", Name: "search"},
- // --- current turn ---
- {Role: "user", Content: "what is the weather today?"}, // current user query
- {Role: "assistant", Content: "let me check", ToolCalls: []chat.ToolCall{
- {ID: "call_1", Function: chat.FunctionCall{Name: "weather", Arguments: `{"city":"beijing"}`}},
- }},
- {Role: "tool", Content: "sunny, 25°C", ToolCallID: "call_1", Name: "weather"},
- }
-
- result, err := c.Consolidate(context.Background(), msgs)
- require.NoError(t, err)
-
- // System prompt preserved.
- assert.Equal(t, "system", result[0].Role)
-
- // The entire current turn tail must be intact (user query + assistant + tool).
- // Find the user query in result.
- userQueryIdx := -1
- for i, m := range result {
- if m.Role == "user" && m.Content == "what is the weather today?" {
- userQueryIdx = i
- break
- }
- }
- require.NotEqual(t, -1, userQueryIdx, "current user query must be preserved")
-
- // After user query: assistant with tool_calls, then tool result.
- require.Greater(t, len(result), userQueryIdx+2)
- assert.Equal(t, "assistant", result[userQueryIdx+1].Role)
- assert.Equal(t, "let me check", result[userQueryIdx+1].Content)
- assert.Len(t, result[userQueryIdx+1].ToolCalls, 1)
-
- assert.Equal(t, "tool", result[userQueryIdx+2].Role)
- assert.Equal(t, "sunny, 25°C", result[userQueryIdx+2].Content)
-
- // Summary message exists.
- hasSummary := false
- for _, m := range result {
- if m.Role == "system" && strings.Contains(m.Content, "Memory Summary") {
- hasSummary = true
- break
- }
- }
- assert.True(t, hasSummary, "should contain a memory summary message")
-
- // Message count reduced.
- assert.Less(t, len(result), len(msgs))
-}
-
-func TestConsolidate_Round2Plus_MultipleToolCallsPreserved(t *testing.T) {
- est, err := token.NewEstimator()
- require.NoError(t, err)
-
- c := NewConsolidator(&stubChat{response: "summary"}, est, 300, 0)
-
- longContent := strings.Repeat("filler ", 300)
- msgs := []chat.Message{
- {Role: "system", Content: "sys"},
- // old history
- {Role: "user", Content: longContent},
- {Role: "assistant", Content: longContent},
- // current turn with parallel tool calls
- {Role: "user", Content: "do two things"},
- {Role: "assistant", Content: "ok", ToolCalls: []chat.ToolCall{
- {ID: "c1", Function: chat.FunctionCall{Name: "toolA", Arguments: `{}`}},
- {ID: "c2", Function: chat.FunctionCall{Name: "toolB", Arguments: `{}`}},
- }},
- {Role: "tool", Content: "resultA", ToolCallID: "c1", Name: "toolA"},
- {Role: "tool", Content: "resultB", ToolCallID: "c2", Name: "toolB"},
- }
-
- result, err := c.Consolidate(context.Background(), msgs)
- require.NoError(t, err)
-
- // All three current-turn messages after the user query must be present.
- var toolNames []string
- for _, m := range result {
- if m.Role == "tool" {
- toolNames = append(toolNames, m.Name)
- }
- }
- assert.Contains(t, toolNames, "toolA")
- assert.Contains(t, toolNames, "toolB")
-
- // User query preserved.
- found := false
- for _, m := range result {
- if m.Role == "user" && m.Content == "do two things" {
- found = true
- }
- }
- assert.True(t, found)
-}
-
-func TestConsolidate_NoUserMessage_ReturnUnchanged(t *testing.T) {
- est, err := token.NewEstimator()
- require.NoError(t, err)
-
- c := NewConsolidator(&stubChat{response: "summary"}, est, 100, 0)
-
- // Edge case: no user message at all (shouldn't happen normally but be defensive).
- msgs := []chat.Message{
- {Role: "system", Content: "sys"},
- {Role: "assistant", Content: "hello"},
- {Role: "assistant", Content: "world"},
- {Role: "assistant", Content: "more"},
- }
-
- result, err := c.Consolidate(context.Background(), msgs)
- require.NoError(t, err)
- assert.Equal(t, msgs, result, "no user message → return unchanged")
-}
-
-func TestConsolidate_LLMFailure_FallsBackToRawArchive(t *testing.T) {
- est, err := token.NewEstimator()
- require.NoError(t, err)
-
- failChat := &stubChat{err: assert.AnError}
- c := NewConsolidator(failChat, est, 200, 0)
-
- longContent := strings.Repeat("data ", 300)
- msgs := []chat.Message{
- {Role: "system", Content: "sys"},
- {Role: "user", Content: longContent},
- {Role: "assistant", Content: longContent},
- {Role: "user", Content: longContent},
- {Role: "assistant", Content: longContent},
- {Role: "user", Content: "current"},
- {Role: "assistant", Content: "thinking", ToolCalls: []chat.ToolCall{
- {ID: "c1", Function: chat.FunctionCall{Name: "t1"}},
- }},
- {Role: "tool", Content: "res", ToolCallID: "c1", Name: "t1"},
- }
-
- result, err := c.Consolidate(context.Background(), msgs)
- require.NoError(t, err)
-
- // Should still have a summary (raw archive fallback).
- hasSummary := false
- for _, m := range result {
- if m.Role == "system" && strings.Contains(m.Content, "Memory Summary") {
- hasSummary = true
- assert.Contains(t, m.Content, "Raw conversation archive",
- "should be a raw archive when LLM fails")
- }
- }
- assert.True(t, hasSummary)
-
- // Current turn tail must still be preserved.
- last := result[len(result)-1]
- assert.Equal(t, "tool", last.Role)
-
- userFound := false
- for _, m := range result {
- if m.Role == "user" && m.Content == "current" {
- userFound = true
- }
- }
- assert.True(t, userFound, "current user query must survive even on LLM failure")
-}
-
-func TestConsolidate_OnlyCurrentTurn_NothingToConsolidate(t *testing.T) {
- est, err := token.NewEstimator()
- require.NoError(t, err)
- c := NewConsolidator(&stubChat{response: "summary"}, est, 100, 0)
-
- // Only system + user + assistant + tool → history between system and user is empty.
- msgs := []chat.Message{
- {Role: "system", Content: "sys"},
- {Role: "user", Content: "hello"},
- {Role: "assistant", Content: "let me help", ToolCalls: []chat.ToolCall{
- {ID: "c1", Function: chat.FunctionCall{Name: "t1"}},
- }},
- {Role: "tool", Content: "done", ToolCallID: "c1", Name: "t1"},
- }
-
- result, err := c.Consolidate(context.Background(), msgs)
- require.NoError(t, err)
- assert.Equal(t, msgs, result, "nothing to consolidate → unchanged")
-}
diff --git a/internal/agent/observe.go b/internal/agent/observe.go
index 289406174..fd3c004a1 100644
--- a/internal/agent/observe.go
+++ b/internal/agent/observe.go
@@ -3,10 +3,12 @@ package agent
import (
"context"
"encoding/json"
+ "errors"
"fmt"
"strings"
"time"
+ "github.com/Tencent/WeKnora/internal/agent/compaction"
agenttoken "github.com/Tencent/WeKnora/internal/agent/token"
agenttools "github.com/Tencent/WeKnora/internal/agent/tools"
"github.com/Tencent/WeKnora/internal/common"
@@ -18,69 +20,205 @@ import (
)
const (
- minCurrentTurnToolTokens = 8 * 1024
- maxCurrentTurnToolTokens = 32 * 1024
- currentTurnToolTokenFraction = 5 // 20%
+ minToolResultTokens = 8 * 1024
+ maxToolResultTokens = 32 * 1024
+ toolResultTokenFraction = 5 // 20%
+
+ // minFreedFraction is the reciprocal of the share of the context a
+ // compaction must reclaim to count as having worked. Below it, the
+ // summarization call costs more than the room it bought.
+ minFreedFraction = 20 // 5%
)
-// manageContextWindow consolidates or compresses messages if approaching the token limit.
-// currentTokens is the caller's best estimate of the current context size (using
-// API-reported Usage when available, falling back to BPE estimation).
-func (e *AgentEngine) manageContextWindow(ctx context.Context, messages []chat.Message, round, currentTokens int) []chat.Message {
- var trimmed bool
- messages, trimmed = trimCurrentTurnToolResults(messages, e.tokenEstimator, currentTurnToolResultBudget(e.config.MaxContextTokens))
- if trimmed {
- currentTokens = e.tokenEstimator.EstimateMessages(messages)
- logger.Infof(ctx, "[Agent][Round-%d] Trimmed current-turn tool results to token budget", round)
+// manageContextWindow summarizes older conversation away when the context has
+// grown past the threshold. The bool reports whether the messages changed, so
+// the caller knows when its token estimate is stale.
+//
+// currentTokens is the caller's best estimate of the current context size
+// (API-reported Usage when available, BPE estimation of messages otherwise).
+func (e *AgentEngine) manageContextWindow(
+ ctx context.Context, messages []chat.Message, round, currentTokens int,
+) ([]chat.Message, bool) {
+ settings := e.compactor.Settings()
+ if !settings.ShouldCompact(currentTokens) {
+ return messages, false
}
- if e.config.MaxContextTokens <= 0 {
- return messages
+
+ logger.Infof(ctx, "[Agent][Round-%d] Context at %d tokens, over the %d threshold "+
+ "(window=%d, reserved=%d, keep_recent=%d); compacting",
+ round, currentTokens, settings.Threshold(), settings.MaxContextTokens,
+ settings.ReserveTokens, settings.KeepRecentTokens)
+
+ changed := false
+ if compacted, ok := e.runCompaction(ctx, messages, round, compaction.ReasonThreshold); ok {
+ messages, changed = compacted, true
+ currentTokens = e.tokenEstimator.EstimateMessages(messages)
+ if !settings.ShouldCompact(currentTokens) {
+ return messages, true
+ }
}
- beforeLen := len(messages)
+ // Still over budget after compaction means the weight is inside the
+ // keep-recent window, which the cut point cannot reach — one tool result
+ // large enough to matter on its own. Trimming those is lossy, so it stays
+ // a fallback rather than a routine step.
+ trimmed, ok := e.trimToolResults(ctx, messages, round, settings)
+ return trimmed, changed || ok
+}
- if e.memoryConsolidator != nil && e.memoryConsolidator.ShouldConsolidate(currentTokens) {
- logger.Infof(ctx, "[Agent][Round-%d] Token threshold exceeded (est=%d), consolidating memory",
- round, currentTokens)
- consolidated, consolidateErr := e.memoryConsolidator.Consolidate(ctx, messages)
- if consolidateErr != nil {
- logger.Warnf(ctx, "[Agent][Round-%d] Memory consolidation failed: %v, "+
- "falling back to simple compression", round, consolidateErr)
+// runCompaction performs one compaction and reports whether the context
+// actually got smaller. A false return means no further attempt this turn will
+// help either, and the caller must not keep retrying: a compaction that frees
+// nothing still costs a full summarization round-trip.
+func (e *AgentEngine) runCompaction(
+ ctx context.Context, messages []chat.Message, round int, reason compaction.Reason,
+) ([]chat.Message, bool) {
+ if e.compactor == nil {
+ return messages, false
+ }
+ // The exhausted mark is tied to a message count rather than a bare flag:
+ // once the loop appends new rounds there is new history to summarize, and
+ // the earlier "nothing to compact" no longer describes the context.
+ if e.compactionExhaustedAt > 0 && len(messages) <= e.compactionExhaustedAt {
+ return messages, false
+ }
+
+ result, err := e.compactor.Compact(ctx, messages, reason)
+ if err != nil {
+ if errors.Is(err, compaction.ErrNothingToCompact) {
+ logger.Infof(ctx, "[Agent][Round-%d] Nothing outside the keep-recent budget; "+
+ "skipping compaction", round)
} else {
- messages = consolidated
- currentTokens = e.tokenEstimator.EstimateMessages(messages)
+ logger.Warnf(ctx, "[Agent][Round-%d] Compaction failed: %v", round, err)
}
+ e.compactionExhaustedAt = len(messages)
+ return messages, false
+ }
+ // "Freed something" is too weak a test. A compaction that returns 240 of
+ // 26,700 tokens counts as progress by that rule, so the loop keeps paying
+ // for a summarization every round while the context stays where it was.
+ if result.Freed() < result.TokensBefore/minFreedFraction {
+ logger.Warnf(ctx, "[Agent][Round-%d] Compaction freed too little (%d → %d tokens); "+
+ "not attempting again at this size", round, result.TokensBefore, result.TokensAfter)
+ e.compactionExhaustedAt = len(messages)
+ return messages, false
}
- messages = agenttoken.CompressContext(messages, e.tokenEstimator, e.config.MaxContextTokens, currentTokens)
+ logger.Infof(ctx, "[Agent][Round-%d] Compacted (%s): %d → %d tokens, %d → %d messages "+
+ "(split_turn=%v, degraded=%v)",
+ round, result.Reason, result.TokensBefore, result.TokensAfter,
+ result.MessagesBefore, result.MessagesAfter, result.SplitTurn, result.Degraded)
+ // Where the surviving tokens went. If the retained tail is far larger than
+ // keep_recent, the cut point could not reach past one oversized message.
+ logger.Debugf(ctx, "[Agent][Round-%d][ctx] post-compaction: summary=%d tail=%d "+
+ "(keep_recent=%d) | %s",
+ round, e.tokenEstimator.EstimateString(result.Summary),
+ result.TokensAfter-e.tokenEstimator.EstimateString(result.Summary),
+ e.compactor.Settings().KeepRecentTokens,
+ e.breakdownContext(result.Messages, nil))
+ common.PipelineInfo(ctx, "Agent", "context_compacted", map[string]interface{}{
+ "round": round,
+ "reason": string(result.Reason),
+ "tokens_before": result.TokensBefore,
+ "tokens_after": result.TokensAfter,
+ "degraded": result.Degraded,
+ })
+ e.emitContextCompacted(ctx, result, round)
+
+ // The usage baseline described the pre-compaction context; keeping it
+ // would have the next round estimate against history that no longer
+ // exists and compact again immediately.
+ e.lastUsage = types.TokenUsage{}
+ e.lastSentMsgCount = 0
+
+ return result.Messages, true
+}
- if len(messages) < beforeLen {
- logger.Infof(ctx, "[Agent][Round-%d] Context managed: %d → %d messages (max_tokens=%d)",
- round, beforeLen, len(messages), e.config.MaxContextTokens)
+func (e *AgentEngine) emitContextCompacted(
+ ctx context.Context, result *compaction.Result, round int,
+) {
+ _ = e.eventBus.Emit(ctx, event.Event{
+ ID: generateEventID("compaction"),
+ Type: event.EventContextCompacted,
+ SessionID: e.sessionID,
+ Data: event.ContextCompactedData{
+ Reason: string(result.Reason),
+ Round: round,
+ TokensBefore: result.TokensBefore,
+ TokensAfter: result.TokensAfter,
+ MessagesBefore: result.MessagesBefore,
+ MessagesAfter: result.MessagesAfter,
+ Summary: result.Summary,
+ Degraded: result.Degraded,
+ SplitTurn: result.SplitTurn,
+ },
+ })
+}
+
+// responseHitContextLimit reports whether the response was shaped by a full
+// context window rather than by the completion budget we asked for.
+func (e *AgentEngine) responseHitContextLimit(response *types.ChatResponse) bool {
+ window := 0
+ if e.config != nil {
+ window = e.config.MaxContextTokens
}
+ return compaction.ResponseHitContextLimit(response, window, e.getCompletionTokenBudget())
+}
- return messages
+// forceCompaction compacts regardless of the threshold, for the case where the
+// provider has already told us the window is full and the estimate that let us
+// get here is the thing not to be trusted.
+func (e *AgentEngine) forceCompaction(
+ ctx context.Context, messages []chat.Message, round int,
+) []chat.Message {
+ compacted, ok := e.runCompaction(ctx, messages, round, compaction.ReasonOverflow)
+ if !ok {
+ trimmed, _ := e.trimToolResults(ctx, messages, round, e.compactor.Settings())
+ return trimmed
+ }
+ return compacted
+}
+
+// trimToolResults replaces tool output with previews until it fits a fraction
+// of the window. It is the last resort: unlike compaction, what it removes is
+// gone without a summary standing in for it.
+func (e *AgentEngine) trimToolResults(
+ ctx context.Context, messages []chat.Message, round int, settings compaction.Settings,
+) ([]chat.Message, bool) {
+ trimmed, ok := trimToolResultsToBudget(
+ messages, e.tokenEstimator, toolResultBudget(settings.MaxContextTokens),
+ )
+ if !ok {
+ return messages, false
+ }
+ logger.Infof(ctx, "[Agent][Round-%d] Trimmed tool results to the token budget", round)
+ return trimmed, true
}
-func currentTurnToolResultBudget(maxContextTokens int) int {
+func toolResultBudget(maxContextTokens int) int {
if maxContextTokens <= 0 {
- return maxCurrentTurnToolTokens
+ return maxToolResultTokens
}
- budget := maxContextTokens / currentTurnToolTokenFraction
- if budget < minCurrentTurnToolTokens {
- return minCurrentTurnToolTokens
+ budget := maxContextTokens / toolResultTokenFraction
+ if budget < minToolResultTokens {
+ return minToolResultTokens
}
- if budget > maxCurrentTurnToolTokens {
- return maxCurrentTurnToolTokens
+ if budget > maxToolResultTokens {
+ return maxToolResultTokens
}
return budget
}
-// trimCurrentTurnToolResults returns a message copy for the next model call.
+// trimToolResultsToBudget returns a message copy for the next model call.
// It never mutates ToolResult objects used by SSE, diagnostics, or persistence.
-// Assistant tool-call messages remain untouched so every compacted tool result
+// Assistant tool-call messages remain untouched so every trimmed tool result
// retains its provider-required call/result pairing.
-func trimCurrentTurnToolResults(
+//
+// Every tool result is a candidate. Scoping this to the current turn was how
+// the old implementation defined "recent", but after compaction the retained
+// window is all recent by construction, and the one result big enough to
+// require trimming is as likely to sit at its head as its tail.
+func trimToolResultsToBudget(
messages []chat.Message,
estimator *agenttoken.Estimator,
budget int,
@@ -89,20 +227,9 @@ func trimCurrentTurnToolResults(
return messages, false
}
- lastUser := -1
- for i := len(messages) - 1; i >= 0; i-- {
- if messages[i].Role == "user" {
- lastUser = i
- break
- }
- }
- if lastUser < 0 {
- return messages, false
- }
-
var toolIndexes []int
total := 0
- for i := lastUser + 1; i < len(messages); i++ {
+ for i := range messages {
if messages[i].Role == "tool" {
toolIndexes = append(toolIndexes, i)
total += estimator.EstimateMessage(&messages[i])
diff --git a/internal/agent/observe_test.go b/internal/agent/observe_test.go
index e92035803..2c9949798 100644
--- a/internal/agent/observe_test.go
+++ b/internal/agent/observe_test.go
@@ -16,22 +16,19 @@ import (
"github.com/stretchr/testify/require"
)
-func TestCurrentTurnToolResultBudgetBounds(t *testing.T) {
- assert.Equal(t, maxCurrentTurnToolTokens, currentTurnToolResultBudget(0))
- assert.Equal(t, minCurrentTurnToolTokens, currentTurnToolResultBudget(10_000))
- assert.Equal(t, 20_000, currentTurnToolResultBudget(100_000))
- assert.Equal(t, maxCurrentTurnToolTokens, currentTurnToolResultBudget(1_000_000))
+func TestToolResultBudgetBounds(t *testing.T) {
+ assert.Equal(t, maxToolResultTokens, toolResultBudget(0))
+ assert.Equal(t, minToolResultTokens, toolResultBudget(10_000))
+ assert.Equal(t, 20_000, toolResultBudget(100_000))
+ assert.Equal(t, maxToolResultTokens, toolResultBudget(1_000_000))
}
-func TestTrimCurrentTurnToolResultsKeepsNewestAndPairing(t *testing.T) {
+func TestTrimToolResultsKeepsNewestAndPairing(t *testing.T) {
estimator, err := agenttoken.NewEstimator()
require.NoError(t, err)
messages := []chat.Message{
- {Role: "user", Content: "old turn"},
- {Role: "tool", Name: "old", ToolCallID: "old-call", Content: strings.Repeat("historical ", 1000)},
- {Role: "assistant", Content: "old answer"},
- {Role: "user", Content: "current turn"},
+ {Role: "user", Content: "the question"},
{
Role: "assistant",
ToolCalls: []chat.ToolCall{
@@ -44,25 +41,28 @@ func TestTrimCurrentTurnToolResultsKeepsNewestAndPairing(t *testing.T) {
{Role: "tool", Name: "two", ToolCallID: "call-2", Content: strings.Repeat("delta epsilon zeta ", 1000)},
{Role: "tool", Name: "three", ToolCallID: "call-3", Content: strings.Repeat("newest result ", 100)},
}
- latestCost := estimator.EstimateMessage(&messages[7])
- markerOne := messages[5]
+ latestCost := estimator.EstimateMessage(&messages[4])
+ markerOne := messages[2]
markerOne.Content = compactedToolResultMarker(markerOne.Content)
- markerTwo := messages[6]
+ markerTwo := messages[3]
markerTwo.Content = compactedToolResultMarker(markerTwo.Content)
budget := latestCost + estimator.EstimateMessage(&markerOne) + estimator.EstimateMessage(&markerTwo)
- trimmed, changed := trimCurrentTurnToolResults(messages, estimator, budget)
+ trimmed, changed := trimToolResultsToBudget(messages, estimator, budget)
require.True(t, changed)
- assert.Equal(t, messages[1].Content, trimmed[1].Content, "historical results are handled separately")
- assert.Contains(t, trimmed[5].Content, "Tool result compacted")
- assert.Contains(t, trimmed[6].Content, "Tool result compacted")
- assert.Equal(t, messages[7].Content, trimmed[7].Content, "newest result should be kept in full")
- assert.Equal(t, messages[4].ToolCalls, trimmed[4].ToolCalls, "assistant tool-call pairing must remain intact")
- assert.Equal(t, strings.Repeat("alpha beta gamma ", 1000), messages[5].Content, "input messages must not be mutated")
+ assert.Contains(t, trimmed[2].Content, "Tool result compacted")
+ assert.Contains(t, trimmed[3].Content, "Tool result compacted")
+ assert.Equal(t, messages[4].Content, trimmed[4].Content, "newest result should be kept in full")
+ assert.Equal(t, messages[1].ToolCalls, trimmed[1].ToolCalls, "assistant tool-call pairing must remain intact")
+ assert.Equal(t,
+ strings.Repeat("alpha beta gamma ", 1000),
+ messages[2].Content,
+ "input messages must not be mutated",
+ )
total := 0
- for _, idx := range []int{5, 6, 7} {
+ for _, idx := range []int{2, 3, 4} {
total += estimator.EstimateMessage(&trimmed[idx])
}
assert.LessOrEqual(t, total, budget)
@@ -399,27 +399,116 @@ func TestIsLengthFinishReason(t *testing.T) {
assert.False(t, isLengthFinishReason("tool_calls"))
}
-func TestAnnotateLengthTruncatedToolErrors(t *testing.T) {
- step := &types.AgentStep{
- ToolCalls: []types.ToolCall{
- {Name: "write_sandbox_file", Result: &types.ToolResult{Success: false, Error: "required parameter 'path' is missing"}},
- {Name: "ok", Result: &types.ToolResult{Success: true, Output: "wrote"}},
- },
+func newEngineWithTool(t *testing.T, name string) (*AgentEngine, *countingTool) {
+ t.Helper()
+ engine := newTestEngine(t, &mockChat{})
+ engine.toolRegistry = agenttools.NewToolRegistry()
+ tool := newCountingTool(name)
+ engine.toolRegistry.RegisterTool(tool)
+ return engine, tool
+}
+
+// "length" alone does not mean the window is full — it usually means the model
+// used the budget we gave it. Retrying those would burn a round reproducing the
+// same truncation, so only a response that stopped short of its own budget
+// counts as something compaction can fix.
+func TestResponseHitContextLimitOnlyWhenShortOfItsOwnBudget(t *testing.T) {
+ engine := newTestEngine(t, &mockChat{}, withMaxCompletionTokens(8192))
+
+ stoppedShort := &types.ChatResponse{
+ FinishReason: "length",
+ Usage: types.TokenUsage{CompletionTokens: 120},
}
- annotateLengthTruncatedToolErrors("length", step.ToolCalls)
- assert.Contains(t, step.ToolCalls[0].Result.Error, "finish_reason=length")
- assert.Contains(t, step.ToolCalls[0].Result.Error, "smaller payload")
- assert.NotContains(t, step.ToolCalls[0].Result.Error, "`path`")
- assert.Equal(t, "wrote", step.ToolCalls[1].Result.Output)
-
- annotateLengthTruncatedToolErrors("length", step.ToolCalls)
- assert.Equal(t, 1, strings.Count(step.ToolCalls[0].Result.Error, "finish_reason=length"))
-
- okStep := &types.AgentStep{
- ToolCalls: []types.ToolCall{
- {Result: &types.ToolResult{Success: false, Error: "nope"}},
- },
+ require.True(t, engine.responseHitContextLimit(stoppedShort))
+
+ usedFullBudget := &types.ChatResponse{
+ FinishReason: "length",
+ Usage: types.TokenUsage{CompletionTokens: 8192},
}
- annotateLengthTruncatedToolErrors("stop", okStep.ToolCalls)
- assert.Equal(t, "nope", okStep.ToolCalls[0].Result.Error)
+ require.False(t, engine.responseHitContextLimit(usedFullBudget))
+
+ // Without usage there is nothing to compare against, so this must not
+ // classify every ordinary truncation as an overflow.
+ require.False(t, engine.responseHitContextLimit(&types.ChatResponse{FinishReason: "length"}))
+
+ require.False(t, engine.responseHitContextLimit(&types.ChatResponse{
+ FinishReason: "stop",
+ Usage: types.TokenUsage{CompletionTokens: 10},
+ }))
+ require.False(t, engine.responseHitContextLimit(nil))
+}
+
+// A response cut off at the completion-token cap must not have any of its tool
+// calls executed: the arguments stop mid-serialization, and a truncated
+// write_sandbox_file lands a half-written file while still reporting success.
+func TestExecuteToolCalls_LengthFinish_RefusesEveryCallWithoutExecuting(t *testing.T) {
+ engine, tool := newEngineWithTool(t, "write_sandbox_file")
+
+ step := &types.AgentStep{}
+ engine.executeToolCalls(
+ context.Background(),
+ &types.ChatResponse{
+ FinishReason: "length",
+ ToolCalls: []types.LLMToolCall{
+ {ID: "call-1", Function: types.FunctionCall{
+ Name: "write_sandbox_file", Arguments: `{"path":"/workspace/output/a.html","content":"<htm`,
+ }},
+ },
+ },
+ step, 0, "sess-1", "msg-1",
+ )
+
+ assert.Equal(t, 0, tool.calls, "a truncated call must never reach the tool")
+ require.Len(t, step.ToolCalls, 1)
+ assert.False(t, step.ToolCalls[0].Result.Success)
+ assert.Contains(t, step.ToolCalls[0].Result.Error, "was not executed")
+ assert.Contains(t, step.ToolCalls[0].Result.Error, "smaller calls")
+}
+
+// A stream that breaks mid-argument never reports finish_reason=length, so the
+// refusal has to come from the repair step noticing it closed the payload off.
+func TestExecuteToolCalls_TruncatedArgsWithoutFinishReason_Refuses(t *testing.T) {
+ engine, tool := newEngineWithTool(t, "write_sandbox_file")
+
+ step := &types.AgentStep{}
+ engine.executeToolCalls(
+ context.Background(),
+ &types.ChatResponse{
+ ToolCalls: []types.LLMToolCall{
+ {ID: "call-1", Function: types.FunctionCall{
+ Name: "write_sandbox_file", Arguments: `{"path":"/workspace/output/a.html","content":"<html><body`,
+ }},
+ },
+ },
+ step, 0, "sess-1", "msg-1",
+ )
+
+ assert.Equal(t, 0, tool.calls)
+ require.Len(t, step.ToolCalls, 1)
+ assert.False(t, step.ToolCalls[0].Result.Success)
+ assert.Contains(t, step.ToolCalls[0].Result.Error, "was not executed")
+}
+
+// Well-formed arguments must still run — the refusal keys on truncation, not on
+// having gone through the repair path at all.
+func TestExecuteToolCalls_CompleteArgs_StillExecute(t *testing.T) {
+ engine, tool := newEngineWithTool(t, "write_sandbox_file")
+
+ step := &types.AgentStep{}
+ engine.executeToolCalls(
+ context.Background(),
+ &types.ChatResponse{
+ FinishReason: "tool_calls",
+ ToolCalls: []types.LLMToolCall{
+ {ID: "call-1", Function: types.FunctionCall{
+ Name: "write_sandbox_file", Arguments: `{"path":"/workspace/output/a.html","content":"<html>"}`,
+ }},
+ },
+ },
+ step, 0, "sess-1", "msg-1",
+ )
+
+ assert.Equal(t, 1, tool.calls)
+ require.Len(t, step.ToolCalls, 1)
+ assert.True(t, step.ToolCalls[0].Result.Success)
}
diff --git a/internal/agent/prompts.go b/internal/agent/prompts.go
index 0e13b2629..088988f8a 100644
--- a/internal/agent/prompts.go
+++ b/internal/agent/prompts.go
@@ -277,29 +277,26 @@ func formatSkillsMetadata(skillsMetadata []*skills.SkillMetadata, shellExecEnabl
builder.WriteString("path inside a script resolves there, not inside the skill; ")
builder.WriteString("`$WEKNORA_SKILL_DIR` is how a script reaches its own files\n")
builder.WriteString(sandboxArtifactReferenceGuidance())
- builder.WriteString(" - Each skill keeps its dependencies to itself (virtualenv or node_modules); ")
- builder.WriteString("this tool already runs scripts the right way. A bare `python3 -c` / `node -e` ")
- builder.WriteString("sees none of them, so never conclude from that that a skill cannot run. ")
- builder.WriteString("The skill tree is frozen after install — do not run install_deps.py, ")
- builder.WriteString("chown, ensurepip, or pip into `/opt/weknora/tenant/skills`. ")
- builder.WriteString("On-demand extras: `python3 -m pip install --target /workspace/.skill-packages/<skill> <package>`, ")
- builder.WriteString("then execute_skill_script; or ask the user to reinstall the skill so extras are baked in\n")
+ builder.WriteString(" - Every script needing a skill's packages runs through this tool, including ")
+ builder.WriteString("one you wrote yourself to `/workspace`. Do not rebuild the environment by hand ")
+ builder.WriteString("with `PYTHONPATH=... python3` or a skill's `.venv/bin/python`: system `python3` ")
+ builder.WriteString("cannot see what the skill baked in at install time, so that route only makes you ")
+ builder.WriteString("reinstall what was already there. A failed import under `python3 -c` / `node -e` ")
+ builder.WriteString("says nothing about whether the skill runs\n")
+ builder.WriteString(" - The skill tree is frozen after install — do not run install_deps.py, chown, ")
+ builder.WriteString("ensurepip, or pip into `/opt/weknora/tenant/skills`. Only once a run reports a ")
+ builder.WriteString("package missing: `python3 -m pip install --target ")
+ builder.WriteString("/workspace/.skill-packages/<skill> <package>`, then execute_skill_script, which ")
+ builder.WriteString("puts that directory on the path for you\n")
if shellExecEnabled {
- builder.WriteString("- `shell_exec(command, work_dir, timeout_sec, max_output_bytes, max_stderr_bytes, env)`: Freely execute shell commands and explore the current session's isolated Cube sandbox\n")
- builder.WriteString(" - Every command already starts in `/workspace`, so use relative paths ")
- builder.WriteString("(`ls -la output/`) and do not prefix `cd /workspace &&`. A `cd` inside one ")
- builder.WriteString("command does not carry over to the next; pass `work_dir` when a command ")
- builder.WriteString("must run elsewhere\n")
- builder.WriteString(" - Use `find` and `ls` to discover files; use `cat`, `head`, `tail`, and `sed` to inspect text; use `grep` and `awk` to search and process content; use `file` for an unknown type\n")
- builder.WriteString(" - Do not `ls` / `find` / `cat` / `file` a skill under `/opt/weknora/tenant/skills` to discover scripts. `read_skill(skill_name)` already lists them; that tree also contains `.venv` / `node_modules`\n")
- builder.WriteString(" - Use shell pipelines, redirects, scripts, package managers, compilers, and other installed commands whenever they are the most direct way to complete the task\n")
- builder.WriteString(" - Do not inspect skill-generated office files with `python3 -c` (system Python has no python-docx/pptx). Write a short script with `write_sandbox_file` and run it with `execute_skill_script`; do not paste the same code into `.venv/bin/python -c`\n")
- builder.WriteString(" - To change a few lines of a file you already wrote, call `edit_sandbox_file` instead of rewriting the whole file\n")
- builder.WriteString(" - Python strings: never nest ASCII `\"` inside `\"...\"` (or `'` inside `'...'`). Use the other quote, and 「」 for Chinese quotation\n")
- builder.WriteString(" - Increase `max_output_bytes` up to 65536 per stream for large text output, or use `sed`/`head`/`tail` for targeted sections\n")
- builder.WriteString(" - Binary output is suppressed; write binary results under `/workspace/output` so ArtifactCollector attaches them for download\n")
- builder.WriteString(" - Session state persists across later `shell_exec` and `execute_skill_script` calls\n")
- builder.WriteString(" - Non-zero exit codes are normal results, not tool errors — inspect stderr and decide what to do next\n")
+ // Only the inventory line. How to drive the shell — working directory,
+ // output limits, exit-code semantics, which scripts do not belong here —
+ // is all in shell_exec's own description, which ships with the tools on
+ // every request and so is never further away than this paragraph.
+ builder.WriteString("- `shell_exec(command, work_dir, timeout_sec, max_output_bytes, max_stderr_bytes, env)`: ")
+ builder.WriteString("Freely execute shell commands and explore the current session's isolated Cube ")
+ builder.WriteString("sandbox. Read its tool description before the first call — it says which work ")
+ builder.WriteString("belongs here and which belongs to `execute_skill_script`\n")
}
return builder.String()
diff --git a/internal/agent/prompts_shell_test.go b/internal/agent/prompts_shell_test.go
index ed6854cdb..0d1051c52 100644
--- a/internal/agent/prompts_shell_test.go
+++ b/internal/agent/prompts_shell_test.go
@@ -13,26 +13,31 @@ func TestFormatSkillsMetadataIncludesShellGuidanceOnlyWhenEnabled(t *testing.T)
enabled := formatSkillsMetadata(metadata, true)
require.Contains(t, enabled, "shell_exec")
- for _, command := range []string{"find", "ls", "cat", "head", "tail", "sed", "grep", "awk"} {
- assert.Contains(t, enabled, command)
- }
assert.Contains(t, enabled, "Freely execute shell commands")
- assert.Contains(t, enabled, "Binary output is suppressed")
- assert.Contains(t, enabled, "use `file` for an unknown type")
- assert.NotContains(t, enabled, "do not `apt-get install file`")
- assert.Contains(t, enabled, "write_sandbox_file")
- assert.Contains(t, enabled, "edit_sandbox_file")
- assert.Contains(t, enabled, "python3 -c")
+
+ // Cross-tool routing is what this section is for, so the skill-environment
+ // rules stay: which tool runs a script, and where an on-demand package goes.
assert.Contains(t, enabled, "execute_skill_script")
assert.Contains(t, enabled, "/workspace/...")
assert.Contains(t, enabled, "do not `list_sandbox_files`")
assert.Contains(t, enabled, "read_skill(skill_name, file_path)")
assert.Contains(t, enabled, ".skill-packages")
assert.Contains(t, enabled, "install_deps.py")
- assert.Contains(t, enabled, "never nest ASCII")
- assert.Contains(t, enabled, "Every command already starts in `/workspace`")
- assert.Contains(t, enabled, "do not prefix `cd /workspace &&`")
+ // How to drive one tool belongs to that tool's description, which ships with
+ // every request anyway. Repeating it here costs the tokens twice and lets
+ // the two copies drift; TestShellExecDescriptionOwnsItsMechanics covers the
+ // other half of this split.
+ for _, mechanic := range []string{
+ "never nest ASCII",
+ "do not prefix `cd /workspace &&`",
+ "Binary output is suppressed",
+ "use `file` for an unknown type",
+ "Increase `max_output_bytes`",
+ "Non-zero exit codes are normal",
+ } {
+ assert.NotContains(t, enabled, mechanic)
+ }
disabled := formatSkillsMetadata(metadata, false)
assert.NotContains(t, disabled, "shell_exec")
diff --git a/internal/agent/think.go b/internal/agent/think.go
index 91004c0f0..7a240f159 100644
--- a/internal/agent/think.go
+++ b/internal/agent/think.go
@@ -4,8 +4,11 @@ import (
"context"
"fmt"
"strings"
+ "sync"
+ "sync/atomic"
"time"
+ "github.com/Tencent/WeKnora/internal/agent/compaction"
agenttools "github.com/Tencent/WeKnora/internal/agent/tools"
"github.com/Tencent/WeKnora/internal/common"
"github.com/Tencent/WeKnora/internal/event"
@@ -34,9 +37,20 @@ func (e *AgentEngine) streamLLMToEventBus(
) (*streamLLMResult, error) {
logger.Debugf(ctx, "[Agent][Stream] Starting LLM stream with %d messages", len(messages))
- llmCtx, llmCancel := context.WithTimeout(ctx, e.getLLMCallTimeout())
+ // No wall-clock deadline here: a round that streams a large tool-call
+ // payload (a whole file body inside write_sandbox_file) legitimately runs
+ // for minutes while producing output the entire time. Cutting it off by
+ // total elapsed time discards the half-assembled call. What must be caught
+ // is a stream that stops producing, which the watchdog below handles.
+ // The provider transport still applies its own overall ceiling.
+ llmCtx, llmCancel := context.WithCancel(ctx)
defer llmCancel()
+ // Seeded before the request goes out so the watchdog also bounds
+ // time-to-first-token, not just the gaps between chunks.
+ var lastChunkAt atomic.Int64
+ lastChunkAt.Store(time.Now().UnixNano())
+
// Model-context encoding owns codec ordering and temporary-handle lifecycle.
messages = e.modelContext.EncodeMessages(messages)
prefixFingerprint := chat.PromptPrefixFingerprint(messages, opts)
@@ -54,7 +68,12 @@ func (e *AgentEngine) streamLLMToEventBus(
answerDecoder := e.modelContext.StreamDecoder()
thinkingDecoder := e.modelContext.StreamDecoder()
+ stallTimeout := e.getLLMStallTimeout()
+ stalled, stopWatchdog := watchStreamStall(ctx, llmCancel, stallTimeout, &lastChunkAt)
+ defer stopWatchdog()
+
for chunk := range stream {
+ lastChunkAt.Store(time.Now().UnixNano())
chunkCount++
if chunkCount == 1 {
firstChunkTime = time.Now()
@@ -63,9 +82,18 @@ func (e *AgentEngine) streamLLMToEventBus(
// Capture error messages from the stream (e.g., "context deadline exceeded")
// but do NOT append them to result.Content — they would leak to the user
- // as if they were part of the LLM answer.
+ // as if they were part of the LLM answer. The tool calls and finish
+ // reason riding along on the error chunk are what the provider had
+ // assembled when the stream broke; keeping them lets the caller log and
+ // reason about a partial call instead of seeing a clean empty response.
if chunk.ResponseType == types.ResponseTypeError {
result.StreamError = chunk.Content
+ if len(chunk.ToolCalls) > 0 {
+ result.ToolCalls = chunk.ToolCalls
+ }
+ if chunk.FinishReason != "" {
+ result.FinishReason = chunk.FinishReason
+ }
continue
}
if chunk.ResponseType == types.ResponseTypeThinking {
@@ -138,6 +166,13 @@ func (e *AgentEngine) streamLLMToEventBus(
len(orphans), orphans)
}
+ // The watchdog cancels the provider context, so the stream surfaces a
+ // generic cancellation. Restate it as a stall so the retry path and the
+ // logs name the actual condition.
+ if stalled.Load() {
+ result.StreamError = fmt.Sprintf("LLM stream stalled: no output for %s", stallTimeout)
+ }
+
// Stream diagnostic summary: helps identify non-streaming patterns
streamDuration := time.Duration(0)
if !firstChunkTime.IsZero() {
@@ -148,15 +183,60 @@ func (e *AgentEngine) streamLLMToEventBus(
chunkCount, len(result.Content), len(result.ToolCalls),
streamDuration.Milliseconds(), responseTypeCounts)
- // If the stream produced an error and no usable content/tool calls,
- // surface it as a Go error so the caller can retry or degrade gracefully.
- if result.StreamError != "" && result.Content == "" && len(result.ToolCalls) == 0 {
+ // A stream that ended on an error never delivered a finish reason, so
+ // everything collected is a partial response — a cut-off preamble, a
+ // half-serialized tool call. Always surface it as a Go error so the caller
+ // retries or degrades. Returning it as success once let a 238-character
+ // preamble stand in as the final answer while a 30 KB write_sandbox_file
+ // call was silently dropped.
+ if result.StreamError != "" {
return result, fmt.Errorf("LLM stream error: %s", result.StreamError)
}
return result, nil
}
+// watchStreamStall cancels an LLM stream that stops producing output for
+// stallTimeout. It deliberately does not bound total duration: a round that
+// streams a large tool-call payload keeps producing for minutes and must be
+// left alone. Returns the stall flag and a stop function the caller must defer.
+func watchStreamStall(
+ ctx context.Context,
+ cancel context.CancelFunc,
+ stallTimeout time.Duration,
+ lastChunkAt *atomic.Int64,
+) (*atomic.Bool, func()) {
+ stalled := &atomic.Bool{}
+ done := make(chan struct{})
+
+ go func() {
+ // Poll well inside the window so the detected gap stays close to the
+ // configured timeout instead of rounding up to twice it.
+ ticker := time.NewTicker(stallTimeout / 4)
+ defer ticker.Stop()
+ for {
+ select {
+ case <-done:
+ return
+ case <-ticker.C:
+ idle := time.Since(time.Unix(0, lastChunkAt.Load()))
+ if idle < stallTimeout {
+ continue
+ }
+ logger.Errorf(ctx,
+ "[Agent][Stream] No output for %s (stall timeout %s); cancelling LLM stream",
+ idle.Truncate(time.Second), stallTimeout)
+ stalled.Store(true)
+ cancel()
+ return
+ }
+ }
+ }()
+
+ var once sync.Once
+ return stalled, func() { once.Do(func() { close(done) }) }
+}
+
// streamThinkingToEventBus streams the thinking process through EventBus
func (e *AgentEngine) streamThinkingToEventBus(
ctx context.Context,
@@ -165,7 +245,7 @@ func (e *AgentEngine) streamThinkingToEventBus(
iteration int,
sessionID string,
) (*types.ChatResponse, error) {
- budget := e.getCompletionTokenBudget()
+ budget := e.clampCompletionBudgetToContext(e.tokenEstimator.EstimateMessages(messages))
logger.Debugf(ctx, "[Agent][Thinking] Iteration-%d: temp=%.2f, tools=%d, thinking=%v, max_tokens=%d",
iteration+1, e.config.Temperature, len(tools), e.config.Thinking, budget)
@@ -378,11 +458,16 @@ func (e *AgentEngine) streamThinkingToEventBus(
// and handles graceful degradation when prior tool results exist.
// Returns nil response (with state.IsComplete=true) when graceful degradation succeeds.
// Returns a non-nil error only when the call fails irrecoverably.
+// callLLMWithRetry runs one ReAct round's LLM call with retry and graceful
+// degradation. messagesPtr is a pointer because an overflow recovery compacts
+// the history in place: the caller has to keep the compacted list, or the next
+// round rebuilds the request that was just rejected.
func (e *AgentEngine) callLLMWithRetry(
- ctx context.Context, messages []chat.Message, tools []chat.Tool,
+ ctx context.Context, messagesPtr *[]chat.Message, tools []chat.Tool,
state *types.AgentState, query string, iteration int, sessionID string,
) (*types.ChatResponse, error) {
round := iteration + 1
+ messages := *messagesPtr
// Log message summary; only detail the tail messages to avoid repeating what prior rounds already logged
const maxDetailMsgs = 4
@@ -425,6 +510,28 @@ func (e *AgentEngine) callLLMWithRetry(
messages = agenttools.SanitizeMessages(messages)
response, err := e.streamThinkingToEventBus(ctx, messages, tools, iteration, sessionID)
+
+ // A rejected-for-size request is neither transient nor fatal, and reading
+ // it as either is wrong in a specific way: retried unchanged it fails
+ // identically every time, and surfaced as an error it ends a turn that a
+ // compaction would have rescued. It gets its own one-shot recovery.
+ if err != nil && !e.overflowRecovered && compaction.IsOverflowError(err) {
+ e.overflowRecovered = true
+ logger.Warnf(ctx, "[Agent][Round-%d] Provider rejected the request as too large; "+
+ "compacting and retrying once: %v", round, err)
+ // The engine's copy stays unsanitized. Sanitizing merges consecutive
+ // same-role messages, and the summary is a `user` message that can end
+ // up adjacent to a real one — merging them folds live conversation
+ // into the summary envelope, where the next compaction cannot read it
+ // back out. The provider gets the sanitized view; the engine keeps the
+ // structured one.
+ compacted := e.forceCompaction(ctx, messages, round)
+ *messagesPtr = compacted
+ messages = agenttools.SanitizeMessages(compacted)
+ e.lastSentMsgCount = len(compacted)
+ response, err = e.streamThinkingToEventBus(ctx, messages, tools, iteration, sessionID)
+ }
+
if err != nil && isTransientError(err) {
// Retry transient errors (timeout, rate limit, server errors) up to maxLLMRetries times
for retry := 1; retry <= maxLLMRetries; retry++ {
diff --git a/internal/agent/token/compress.go b/internal/agent/token/compress.go
deleted file mode 100644
index fa8d47264..000000000
--- a/internal/agent/token/compress.go
+++ /dev/null
@@ -1,107 +0,0 @@
-package token
-
-import (
- "github.com/Tencent/WeKnora/internal/models/chat"
-)
-
-// DefaultContextThresholdRatio is the ratio of context window usage that triggers compression.
-// When message tokens exceed MaxContextTokens * threshold, old messages are trimmed.
-const DefaultContextThresholdRatio = 0.8
-
-// CompressContext trims older history messages to bring total token count below
-// the threshold. It preserves:
-// - The system prompt (first message)
-// - The current turn: user query (last user message) and all subsequent
-// assistant/tool messages
-// - tool_call / tool_result message pairs (never splits them)
-//
-// currentTokens is the caller's best estimate of the current context size.
-func CompressContext(
- messages []chat.Message,
- estimator *Estimator,
- maxTokens int,
- currentTokens int,
-) []chat.Message {
- if maxTokens <= 0 || len(messages) <= 2 {
- return messages
- }
-
- threshold := int(float64(maxTokens) * DefaultContextThresholdRatio)
- if currentTokens <= threshold {
- return messages
- }
-
- systemMsg := messages[0]
-
- // Find the current user query — the last message with role "user".
- lastUserIdx := len(messages) - 1
- for i := len(messages) - 1; i >= 1; i-- {
- if messages[i].Role == "user" {
- lastUserIdx = i
- break
- }
- }
-
- history := messages[1:lastUserIdx]
- tail := messages[lastUserIdx:]
-
- if len(history) == 0 {
- return messages
- }
-
- groups := groupToolMessages(history)
-
- tokensToFree := currentTokens - threshold
- freed := 0
- removeUpTo := 0
-
- for i, group := range groups {
- groupTokens := 0
- for _, msg := range group {
- groupTokens += estimator.EstimateMessage(&msg)
- }
- freed += groupTokens
- removeUpTo = i + 1
- if freed >= tokensToFree {
- break
- }
- }
-
- remaining := make([]chat.Message, 0, len(messages))
- remaining = append(remaining, systemMsg)
- for i := removeUpTo; i < len(groups); i++ {
- remaining = append(remaining, groups[i]...)
- }
- remaining = append(remaining, tail...)
-
- return remaining
-}
-
-// groupToolMessages groups middle messages into logical units:
-// - An assistant message with tool_calls + its corresponding tool result messages = one group
-// - A standalone message (user, assistant without tool_calls) = one group
-//
-// This ensures tool_call/tool_result pairs are never split during compression.
-func groupToolMessages(messages []chat.Message) [][]chat.Message {
- var groups [][]chat.Message
- i := 0
- for i < len(messages) {
- msg := messages[i]
-
- // If this is an assistant message with tool_calls, group it with following tool results
- if msg.Role == "assistant" && len(msg.ToolCalls) > 0 {
- group := []chat.Message{msg}
- i++
- // Collect all following tool result messages
- for i < len(messages) && messages[i].Role == "tool" {
- group = append(group, messages[i])
- i++
- }
- groups = append(groups, group)
- } else {
- groups = append(groups, []chat.Message{msg})
- i++
- }
- }
- return groups
-}
diff --git a/internal/agent/token/estimator.go b/internal/agent/token/estimator.go
index 076bab5be..e51efd718 100644
--- a/internal/agent/token/estimator.go
+++ b/internal/agent/token/estimator.go
@@ -29,6 +29,14 @@ import (
const (
perMessageOverhead = 3
perConversationTail = 3
+ perToolCallOverhead = 4
+ perToolDefOverhead = 8
+
+ // estimatedImageTokens is the assumed cost of one image. Providers bill
+ // images by tile count, so neither the URL nor the base64 blob is any
+ // guide: a short https:// link and a megabyte data URI can cost the same.
+ // 1200 tokens is ~4800 characters at the usual 4-chars-per-token heuristic.
+ estimatedImageTokens = 1200
)
// Estimator counts tokens for messages and strings using BPE tokenization.
@@ -71,17 +79,62 @@ func (e *Estimator) EstimateString(s string) int {
}
// EstimateMessage returns the token count for a single message.
+//
+// Every field that goes out on the wire has to be counted here, including the
+// ones that are easy to forget. Reasoning content is the expensive one:
+// thinking models (DeepSeek V3.2/V4, MiMo) require the previous turns'
+// reasoning_content to be sent back verbatim, and it is typically several times
+// longer than the visible reply. Omitting it made a 130k context measure as
+// 26k — compaction then cut in the wrong place, freed almost nothing, and ran
+// again the next round. Reasoning content is counted alongside text and tool
+// calls for that reason.
func (e *Estimator) EstimateMessage(msg *chat.Message) int {
tokens := perMessageOverhead
tokens += e.EstimateString(msg.Role)
tokens += e.EstimateString(msg.Content)
tokens += e.EstimateString(msg.Name)
+ tokens += e.EstimateString(msg.ToolCallID)
+ tokens += e.EstimateString(msg.ReasoningContent)
+ tokens += e.estimateImageParts(msg)
for _, tc := range msg.ToolCalls {
tokens += e.EstimateString(tc.Function.Name)
tokens += e.EstimateString(tc.Function.Arguments)
- tokens += 4
+ tokens += perToolCallOverhead
}
return tokens
}
+
+// estimateImageParts counts multimodal content. MultiContent is the assembled
+// representation actually sent to the provider, so when it is present the raw
+// Images list is the same pictures counted a second time.
+func (e *Estimator) estimateImageParts(msg *chat.Message) int {
+ if len(msg.MultiContent) == 0 {
+ return len(msg.Images) * estimatedImageTokens
+ }
+ tokens := 0
+ for _, part := range msg.MultiContent {
+ if part.ImageURL != nil || part.Type == "image_url" {
+ tokens += estimatedImageTokens
+ continue
+ }
+ tokens += e.EstimateString(part.Text)
+ }
+ return tokens
+}
+
+// EstimateTools returns the token cost of the tool schemas sent with every
+// request. They are part of the prompt the provider bills. They are not part
+// of the compaction trigger, which estimates messages only; use this for
+// diagnostics and request-budget clamping, not for ShouldCompact.
+func (e *Estimator) EstimateTools(tools []chat.Tool) int {
+ total := 0
+ for _, tool := range tools {
+ total += e.EstimateString(tool.Function.Name)
+ total += e.EstimateString(tool.Function.Description)
+ total += e.EstimateString(string(tool.Function.Parameters))
+ total += perToolDefOverhead
+ }
+ return total
+}
diff --git a/internal/agent/token/estimator_test.go b/internal/agent/token/estimator_test.go
index 4837fe894..f8f73c0df 100644
--- a/internal/agent/token/estimator_test.go
+++ b/internal/agent/token/estimator_test.go
@@ -1,14 +1,12 @@
package token
import (
- "encoding/json"
"fmt"
"strings"
"testing"
"github.com/Tencent/WeKnora/internal/models/chat"
"github.com/stretchr/testify/assert"
- "github.com/stretchr/testify/require"
)
func TestEstimator(t *testing.T) {
@@ -82,252 +80,63 @@ func TestEstimator(t *testing.T) {
})
}
-func TestCompressContext(t *testing.T) {
+// Thinking models (DeepSeek V3.2/V4, MiMo) require prior reasoning_content to
+// be sent back verbatim, and it typically dwarfs the visible reply. Leaving it
+// out of the estimate made a 130k context measure as 26k, so compaction cut in
+// the wrong place, freed almost nothing, and ran again every round.
+func TestEstimateMessageCountsReasoningContent(t *testing.T) {
e, err := NewEstimator()
- require.NoError(t, err)
+ assert.NoError(t, err)
- t.Run("no compression needed", func(t *testing.T) {
- messages := []chat.Message{
- {Role: "system", Content: "system prompt"},
- {Role: "user", Content: "hello"},
- }
- tokens := e.EstimateMessages(messages)
- result := CompressContext(messages, e, 100000, tokens)
- assert.Equal(t, messages, result)
- })
-
- t.Run("preserves system and last message", func(t *testing.T) {
- messages := []chat.Message{
- {Role: "system", Content: "system prompt"},
- {Role: "user", Content: strings.Repeat("old message ", 1000)},
- {Role: "assistant", Content: strings.Repeat("old response ", 1000)},
- {Role: "user", Content: "current query"},
- }
- tokens := e.EstimateMessages(messages)
- result := CompressContext(messages, e, 100, tokens)
- require.GreaterOrEqual(t, len(result), 2)
- assert.Equal(t, "system", result[0].Role)
- assert.Equal(t, "current query", result[len(result)-1].Content)
- })
+ reasoning := strings.Repeat("let me think about this step by step. ", 200)
+ plain := chat.Message{Role: "assistant", Content: "short answer"}
+ thinking := chat.Message{Role: "assistant", Content: "short answer", ReasoningContent: reasoning}
- t.Run("keeps tool_call and tool_result paired", func(t *testing.T) {
- messages := []chat.Message{
- {Role: "system", Content: "system prompt"},
- {Role: "user", Content: strings.Repeat("x", 500)},
- {Role: "assistant", Content: strings.Repeat("y", 500)},
- {Role: "assistant", Content: "thinking", ToolCalls: []chat.ToolCall{
- {ID: "call_1", Function: chat.FunctionCall{Name: "search", Arguments: `{"q":"test"}`}},
- }},
- {Role: "tool", Content: strings.Repeat("result ", 100), ToolCallID: "call_1", Name: "search"},
- {Role: "user", Content: "what did you find?"},
- }
-
- tokens := e.EstimateMessages(messages)
- result := CompressContext(messages, e, 200, tokens)
-
- b, _ := json.Marshal(result)
- fmt.Println(string(b))
-
- for i, msg := range result {
- if msg.Role == "tool" {
- require.Greater(t, i, 0)
- assert.Equal(t, "assistant", result[i-1].Role)
- assert.Greater(t, len(result[i-1].ToolCalls), 0)
- }
- }
- })
-
- t.Run("zero maxTokens returns unchanged", func(t *testing.T) {
- messages := []chat.Message{
- {Role: "system", Content: "system"},
- {Role: "user", Content: "hello"},
- }
- result := CompressContext(messages, e, 0, 0)
- assert.Equal(t, messages, result)
- })
-
- t.Run("two messages returns unchanged", func(t *testing.T) {
- messages := []chat.Message{
- {Role: "system", Content: "system"},
- {Role: "user", Content: "hello"},
- }
- result := CompressContext(messages, e, 1, 999)
- assert.Equal(t, messages, result)
- })
-
- t.Run("round2+: user query not at end, preserves current turn tail", func(t *testing.T) {
- longText := strings.Repeat("filler content ", 200)
- messages := []chat.Message{
- {Role: "system", Content: "system prompt"},
- // old history
- {Role: "user", Content: longText},
- {Role: "assistant", Content: longText},
- {Role: "user", Content: longText},
- {Role: "assistant", Content: longText},
- // current turn
- {Role: "user", Content: "current question"},
- {Role: "assistant", Content: "let me search", ToolCalls: []chat.ToolCall{
- {ID: "c1", Function: chat.FunctionCall{Name: "search", Arguments: `{"q":"test"}`}},
- }},
- {Role: "tool", Content: "search results", ToolCallID: "c1", Name: "search"},
- }
-
- tokens := e.EstimateMessages(messages)
- result := CompressContext(messages, e, 300, tokens)
-
- // System prompt preserved.
- assert.Equal(t, "system", result[0].Role)
- assert.Equal(t, "system prompt", result[0].Content)
-
- // Current turn tail must be fully intact.
- userIdx := -1
- for i, m := range result {
- if m.Role == "user" && m.Content == "current question" {
- userIdx = i
- break
- }
- }
- require.NotEqual(t, -1, userIdx, "user query must be preserved")
- require.Greater(t, len(result), userIdx+2, "assistant + tool must follow")
- assert.Equal(t, "assistant", result[userIdx+1].Role)
- assert.Equal(t, "let me search", result[userIdx+1].Content)
- assert.Equal(t, "tool", result[userIdx+2].Role)
- assert.Equal(t, "search results", result[userIdx+2].Content)
-
- // Should be shorter than original (old history trimmed).
- assert.Less(t, len(result), len(messages))
- })
-
- t.Run("round2+: multiple tool results after user query all preserved", func(t *testing.T) {
- longText := strings.Repeat("data ", 300)
- messages := []chat.Message{
- {Role: "system", Content: "sys"},
- {Role: "user", Content: longText},
- {Role: "assistant", Content: longText},
- // current turn with parallel tool calls
- {Role: "user", Content: "do things"},
- {Role: "assistant", Content: "ok", ToolCalls: []chat.ToolCall{
- {ID: "c1", Function: chat.FunctionCall{Name: "t1"}},
- {ID: "c2", Function: chat.FunctionCall{Name: "t2"}},
- }},
- {Role: "tool", Content: "res1", ToolCallID: "c1", Name: "t1"},
- {Role: "tool", Content: "res2", ToolCallID: "c2", Name: "t2"},
- }
-
- tokens := e.EstimateMessages(messages)
- result := CompressContext(messages, e, 200, tokens)
-
- // Both tool results must be present.
- var toolNames []string
- for _, m := range result {
- if m.Role == "tool" {
- toolNames = append(toolNames, m.Name)
- }
- }
- assert.Contains(t, toolNames, "t1")
- assert.Contains(t, toolNames, "t2")
-
- // User query preserved.
- found := false
- for _, m := range result {
- if m.Content == "do things" {
- found = true
- }
- }
- assert.True(t, found)
- })
-
- t.Run("round2+: no history between system and user query returns unchanged", func(t *testing.T) {
- messages := []chat.Message{
- {Role: "system", Content: "sys"},
- {Role: "user", Content: "hello"},
- {Role: "assistant", Content: "thinking", ToolCalls: []chat.ToolCall{
- {ID: "c1", Function: chat.FunctionCall{Name: "t1"}},
- }},
- {Role: "tool", Content: "done", ToolCallID: "c1", Name: "t1"},
- }
- tokens := e.EstimateMessages(messages)
- result := CompressContext(messages, e, 10, tokens)
- assert.Equal(t, messages, result, "no history to trim → unchanged")
- })
-
- t.Run("no user message at all returns unchanged", func(t *testing.T) {
- messages := []chat.Message{
- {Role: "system", Content: "sys"},
- {Role: "assistant", Content: strings.Repeat("x", 1000)},
- {Role: "assistant", Content: strings.Repeat("y", 1000)},
- }
- tokens := e.EstimateMessages(messages)
- result := CompressContext(messages, e, 10, tokens)
- // lastUserIdx defaults to len-1 (last msg), history = messages[1:last] = [assistant]
- // This still does its best—the important thing is it doesn't panic.
- assert.NotNil(t, result)
- })
-
- t.Run("round2+: tool pair in history never split", func(t *testing.T) {
- longText := strings.Repeat("verbose ", 200)
- messages := []chat.Message{
- {Role: "system", Content: "sys"},
- // old turn 1
- {Role: "user", Content: "old query 1"},
- {Role: "assistant", Content: longText, ToolCalls: []chat.ToolCall{
- {ID: "old1", Function: chat.FunctionCall{Name: "old_tool"}},
- }},
- {Role: "tool", Content: longText, ToolCallID: "old1", Name: "old_tool"},
- // old turn 2
- {Role: "user", Content: "old query 2"},
- {Role: "assistant", Content: "short reply"},
- // current turn
- {Role: "user", Content: "current"},
- {Role: "assistant", Content: "working", ToolCalls: []chat.ToolCall{
- {ID: "new1", Function: chat.FunctionCall{Name: "new_tool"}},
- }},
- {Role: "tool", Content: "result", ToolCallID: "new1", Name: "new_tool"},
- }
-
- tokens := e.EstimateMessages(messages)
- result := CompressContext(messages, e, 300, tokens)
-
- // Verify no orphaned tool message: every "tool" msg must be preceded by
- // an assistant with tool_calls.
- for i, m := range result {
- if m.Role == "tool" {
- require.Greater(t, i, 0, "tool message at index 0 is impossible")
- prev := result[i-1]
- isPairedTool := prev.Role == "tool"
- isPairedAssistant := prev.Role == "assistant" && len(prev.ToolCalls) > 0
- assert.True(t, isPairedTool || isPairedAssistant,
- "tool message at %d must be preceded by assistant+tool_calls or another tool, got %s", i, prev.Role)
- }
- }
- })
+ assert.Greater(t, e.EstimateMessage(&thinking), e.EstimateMessage(&plain)+1000,
+ "reasoning content must be counted, it is sent on the wire")
+ assert.InDelta(t, e.EstimateString(reasoning),
+ e.EstimateMessage(&thinking)-e.EstimateMessage(&plain), 2)
}
-func TestGroupToolMessages(t *testing.T) {
- t.Run("standalone messages", func(t *testing.T) {
- messages := []chat.Message{
- {Role: "user", Content: "hello"},
- {Role: "assistant", Content: "hi"},
- }
- groups := groupToolMessages(messages)
- assert.Len(t, groups, 2)
- })
+// Providers bill images by tile count, so neither a short https:// URL nor a
+// megabyte data URI says anything useful about the cost.
+func TestEstimateMessageCountsImages(t *testing.T) {
+ e, err := NewEstimator()
+ assert.NoError(t, err)
+
+ withImages := chat.Message{Role: "user", Content: "what is this", Images: []string{"https://x/a.png"}}
+ assert.Greater(t, e.EstimateMessage(&withImages), estimatedImageTokens)
+
+ multi := chat.Message{Role: "user", MultiContent: []chat.MessageContentPart{
+ {Type: "text", Text: "describe"},
+ {Type: "image_url", ImageURL: &chat.ImageURL{URL: "data:image/png;base64,AAAA"}},
+ }}
+ assert.Greater(t, e.EstimateMessage(&multi), estimatedImageTokens)
+
+ // MultiContent is the representation actually sent; counting Images too
+ // would bill the same picture twice.
+ both := chat.Message{
+ Role: "user",
+ Images: []string{"https://x/a.png"},
+ MultiContent: multi.MultiContent,
+ }
+ assert.Equal(t, e.EstimateMessage(&multi), e.EstimateMessage(&both))
+}
- t.Run("tool call with results grouped", func(t *testing.T) {
- messages := []chat.Message{
- {Role: "user", Content: "search for X"},
- {Role: "assistant", Content: "thinking", ToolCalls: []chat.ToolCall{
- {ID: "call_1", Function: chat.FunctionCall{Name: "search"}},
- {ID: "call_2", Function: chat.FunctionCall{Name: "fetch"}},
- }},
- {Role: "tool", Content: "result1", ToolCallID: "call_1"},
- {Role: "tool", Content: "result2", ToolCallID: "call_2"},
- {Role: "user", Content: "thanks"},
- }
- groups := groupToolMessages(messages)
- assert.Len(t, groups, 3)
- assert.Len(t, groups[1], 3)
- b, _ := json.Marshal(groups)
- fmt.Println(string(b))
- })
+// Tool schemas are part of the billed prompt but never appear in the message
+// list, so omitting them biases every estimate low by a constant.
+func TestEstimateTools(t *testing.T) {
+ e, err := NewEstimator()
+ assert.NoError(t, err)
+
+ assert.Zero(t, e.EstimateTools(nil))
+ tools := []chat.Tool{{
+ Type: "function",
+ Function: chat.FunctionDef{
+ Name: "shell_exec",
+ Description: strings.Repeat("run a shell command in the sandbox. ", 20),
+ Parameters: []byte(`{"type":"object","properties":{"command":{"type":"string"}}}`),
+ },
+ }}
+ assert.Greater(t, e.EstimateTools(tools), 100)
}
diff --git a/internal/agent/tools/file_mutation_queue.go b/internal/agent/tools/file_mutation_queue.go
new file mode 100644
index 000000000..5175e54c7
--- /dev/null
+++ b/internal/agent/tools/file_mutation_queue.go
@@ -0,0 +1,88 @@
+package tools
+
+// Serialize mutations that target the same sandbox file.
+//
+// write_sandbox_file in append mode and edit_sandbox_file are both
+// read-modify-write against a remote filesystem that exposes no atomic
+// primitive. When the model emits several tool calls in one response the
+// engine may run them concurrently, and two calls touching one path then read
+// the same bytes and the second write silently discards the first — the failure
+// looks like the model's own output going missing, which is unfalsifiable from
+// the logs.
+//
+// Serialize per path, so unrelated files still run concurrently. A global lock
+// would be correct too, but it would erase the point of parallel tool calls
+// for the workload that uses them most.
+
+import (
+ "sync"
+ "sync/atomic"
+)
+
+// sandboxFileMutationEpoch counts completed sandbox file mutations across the
+// process. read_sandbox_file caches a downloaded file to serve pages from, and
+// this is what lets that cache notice a write.
+//
+// Stat alone is not enough to detect a change: a same-length replacement
+// (flipping a digit, say) leaves the size identical, and mtime resolution is
+// one second on some backends, so an edit and a re-read in the same second can
+// look untouched. A counter cannot miss that.
+//
+// It is global rather than per path, which over-invalidates — writing file B
+// drops a cached file A. That costs one re-download in a case that barely
+// happens (paging a file while writing another) and buys a counter that needs
+// no bookkeeping and cannot grow.
+var sandboxFileMutationEpoch atomic.Uint64
+
+// sandboxMutationEpoch reads the current value, for a cache to record and
+// later compare against.
+func sandboxMutationEpoch() uint64 { return sandboxFileMutationEpoch.Load() }
+
+type fileMutationQueue struct {
+ mu sync.Mutex
+ locks map[string]*fileMutationLock
+}
+
+type fileMutationLock struct {
+ mu sync.Mutex
+ // refs keeps the entry alive while callers are queued on it, so the map
+ // does not accumulate one lock per file ever written in the process.
+ refs int
+}
+
+var sandboxFileMutations = &fileMutationQueue{locks: map[string]*fileMutationLock{}}
+
+// lockFile blocks until this key is free and returns the release function.
+func (q *fileMutationQueue) lockFile(key string) func() {
+ q.mu.Lock()
+ entry, ok := q.locks[key]
+ if !ok {
+ entry = &fileMutationLock{}
+ q.locks[key] = entry
+ }
+ entry.refs++
+ q.mu.Unlock()
+
+ entry.mu.Lock()
+
+ return func() {
+ entry.mu.Unlock()
+ q.mu.Lock()
+ entry.refs--
+ if entry.refs == 0 {
+ delete(q.locks, key)
+ }
+ q.mu.Unlock()
+ }
+}
+
+// lockSandboxFile serializes mutations to one file within one session. Paths
+// are already cleaned and absolute by the time callers reach this. Releasing
+// the lock marks the mutation done, which is what invalidates read caches.
+func lockSandboxFile(sessionID, filePath string) func() {
+ release := sandboxFileMutations.lockFile(sessionID + "\x00" + filePath)
+ return func() {
+ sandboxFileMutationEpoch.Add(1)
+ release()
+ }
+}
diff --git a/internal/agent/tools/file_mutation_queue_test.go b/internal/agent/tools/file_mutation_queue_test.go
new file mode 100644
index 000000000..2bb40e814
--- /dev/null
+++ b/internal/agent/tools/file_mutation_queue_test.go
@@ -0,0 +1,120 @@
+package tools
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "strings"
+ "sync"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/sandbox"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+// slowSink widens the read-modify-write window so an unserialized append
+// reliably loses content instead of only doing so under unlucky timing.
+type slowSink struct {
+ mu sync.Mutex
+ files map[string][]byte
+}
+
+func (s *slowSink) StatSessionFile(_ context.Context, _, filePath string) (*sandbox.RemoteStatEntry, error) {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ data, ok := s.files[filePath]
+ if !ok {
+ return nil, fmt.Errorf("no such file: %s", filePath)
+ }
+ return &sandbox.RemoteStatEntry{Path: filePath, Type: sandbox.RemoteEntryFile, Size: int64(len(data))}, nil
+}
+
+func (s *slowSink) ReadSessionFile(_ context.Context, _, filePath string) ([]byte, error) {
+ s.mu.Lock()
+ data, ok := s.files[filePath]
+ out := append([]byte(nil), data...)
+ s.mu.Unlock()
+ if !ok {
+ return nil, fmt.Errorf("no such file: %s", filePath)
+ }
+ // The real backend round-trips over the network here.
+ time.Sleep(time.Millisecond)
+ return out, nil
+}
+
+func (s *slowSink) WriteSessionWorkspaceFile(_ context.Context, _, filePath string, content []byte) error {
+ time.Sleep(time.Millisecond)
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ if s.files == nil {
+ s.files = map[string][]byte{}
+ }
+ s.files[filePath] = append([]byte(nil), content...)
+ return nil
+}
+
+// The engine runs a response's tool calls in parallel, and append is
+// read-modify-write against a backend with no atomic append. Without
+// serialization the second write overwrites the first from a stale base, and
+// the symptom is the model's own output silently going missing.
+func TestConcurrentAppendsToSameFileDoNotLoseContent(t *testing.T) {
+ const path = "/workspace/output/deck.html"
+ sink := &slowSink{}
+ tool := NewWriteSandboxFileTool(sink, 0)
+
+ first, err := tool.Execute(sandboxFileTestContext(), mustWriteSandboxArgs(path, "start"))
+ require.NoError(t, err)
+ require.True(t, first.Success, first.Error)
+
+ const appenders = 8
+ var wg sync.WaitGroup
+ for i := 0; i < appenders; i++ {
+ wg.Add(1)
+ go func(i int) {
+ defer wg.Done()
+ result, err := tool.Execute(sandboxFileTestContext(), json.RawMessage(
+ fmt.Sprintf(`{"path":%q,"content":"|%d","mode":"append"}`, path, i),
+ ))
+ assert.NoError(t, err)
+ assert.True(t, result.Success, result.Error)
+ }(i)
+ }
+ wg.Wait()
+
+ final := string(sink.files[path])
+ assert.True(t, strings.HasPrefix(final, "start"))
+ for i := 0; i < appenders; i++ {
+ assert.Contains(t, final, fmt.Sprintf("|%d", i),
+ "append %d was overwritten by a concurrent write", i)
+ }
+}
+
+// Different paths must still run concurrently: serializing every mutation
+// would remove the point of executing tool calls in parallel.
+func TestMutationsToDifferentFilesDoNotBlockEachOther(t *testing.T) {
+ release := lockSandboxFile("session-1", "/workspace/a.txt")
+ defer release()
+
+ done := make(chan struct{})
+ go func() {
+ lockSandboxFile("session-1", "/workspace/b.txt")()
+ close(done)
+ }()
+
+ select {
+ case <-done:
+ case <-time.After(2 * time.Second):
+ t.Fatal("a held lock on one path blocked an unrelated path")
+ }
+}
+
+// The lock table must not grow one entry per file ever touched.
+func TestFileMutationQueueReleasesEntries(t *testing.T) {
+ queue := &fileMutationQueue{locks: map[string]*fileMutationLock{}}
+ for i := 0; i < 100; i++ {
+ queue.lockFile(fmt.Sprintf("/workspace/%d.txt", i))()
+ }
+ assert.Empty(t, queue.locks)
+}
diff --git a/internal/agent/tools/json_repair.go b/internal/agent/tools/json_repair.go
index 1ef16e49b..ead4ac961 100644
--- a/internal/agent/tools/json_repair.go
+++ b/internal/agent/tools/json_repair.go
@@ -18,9 +18,21 @@ import (
// Returns the repaired JSON string. If repair is not possible,
// returns the original string unchanged (caller should handle parse errors).
func RepairJSON(s string) string {
+ repaired, _ := RepairJSONDetail(s)
+ return repaired
+}
+
+// RepairJSONDetail is RepairJSON that also reports whether the payload had to
+// be closed off to parse — an unterminated string or an unbalanced bracket.
+// That only happens when the provider stopped emitting mid-argument, so the
+// values now parse but are partial: `content` holds half a file, `query` holds
+// half a sentence. Callers must refuse such a call rather than run it.
+// Escape and trailing-comma fixes are ordinary malformations, not truncation,
+// and do not set the flag.
+func RepairJSONDetail(s string) (string, bool) {
s = strings.TrimSpace(s)
if s == "" {
- return "{}"
+ return "{}", false
}
// Must start with { for object
@@ -29,7 +41,7 @@ func RepairJSON(s string) string {
if strings.Contains(s, ":") || strings.Contains(s, "=") {
s = "{" + s + "}"
} else {
- return s
+ return s, false
}
}
@@ -44,9 +56,7 @@ func RepairJSON(s string) string {
s = fixTrailingCommas(s)
// Balance brackets and braces
- s = balanceBrackets(s)
-
- return s
+ return balanceBrackets(s)
}
// fixInvalidEscapes turns invalid JSON string escapes into literal backslash
@@ -205,8 +215,9 @@ func findNextNonSpace(runes []rune, start int) int {
return -1
}
-// balanceBrackets appends missing closing brackets/braces.
-func balanceBrackets(s string) string {
+// balanceBrackets appends missing closing brackets/braces, reporting whether
+// anything had to be appended.
+func balanceBrackets(s string) (string, bool) {
var stack []rune
inString := false
escaped := false
@@ -240,15 +251,19 @@ func balanceBrackets(s string) string {
}
}
+ closed := false
+
// Close unclosed string if needed
if inString {
s += `"`
+ closed = true
}
// Append missing closers in reverse order
for i := len(stack) - 1; i >= 0; i-- {
s += string(stack[i])
+ closed = true
}
- return s
+ return s, closed
}
diff --git a/internal/agent/tools/sandbox_edit.go b/internal/agent/tools/sandbox_edit.go
index 8944601f3..37ac308e2 100644
--- a/internal/agent/tools/sandbox_edit.go
+++ b/internal/agent/tools/sandbox_edit.go
@@ -8,7 +8,10 @@
// Design notes:
// - Same writable roots as write_sandbox_file: /workspace except
// /workspace/input.
-// - Default is a unique match (Cursor-style). replace_all=true replaces
+// - One input shape: every change is an entry in edits[]. Each entry resolves
+// against the original content, so a batch is order-independent and
+// overlaps are rejected rather than silently corrupting the file.
+// - Default is a unique match (Cursor-style). Per-entry replace_all replaces
// every occurrence. 0 matches or an ambiguous match without replace_all
// fail without writing.
// - Result is path + replacement count + size; contents are not echoed.
@@ -19,6 +22,7 @@ import (
"encoding/json"
"fmt"
"path"
+ "sort"
"strings"
"github.com/Tencent/WeKnora/internal/logger"
@@ -30,7 +34,8 @@ import (
// editSandboxMissingFieldHint is appended when schema validation fails
// (typically a truncated call that omitted path or old_string).
const editSandboxMissingFieldHint = "\nIf the previous call was truncated, retry with a complete JSON object: " +
- "put `path` first, then `old_string` and `new_string`. Do not send the whole file — this tool replaces a snippet."
+ "put `path` first, then `edits` as an array of {old_string, new_string}. " +
+ "Do not send the whole file — this tool replaces snippets."
// SandboxFileEditor reads then writes a session workspace file. Production
// uses *sandbox.SessionBoundManager via SessionFileStore.
@@ -47,10 +52,19 @@ var editSandboxFileTool = BaseTool{
## Usage
- Use this after ` + "`write_sandbox_file`" + ` (or a previous edit) when only a
few lines need to change — a wrong output path, a typo, a constant.
+- Every change goes in ` + "`edits`" + `, an array of
+ ` + "`{old_string, new_string}`" + ` — an array of one for a single change.
+- Changing several places in one file: send them all in ONE call. Do not call
+ this tool once per change.
- ` + "`old_string`" + ` must match the file exactly, including whitespace and
quotes. Include a few surrounding lines so the match is unique.
-- Default: the snippet must occur exactly once. Set ` + "`replace_all=true`" + `
- only when you intentionally want every occurrence changed.
+- Every ` + "`old_string`" + ` is matched against the ORIGINAL file, not against
+ the result of earlier entries, so entries must not overlap. If two changes
+ touch the same lines, merge them into one entry.
+- Keep each ` + "`old_string`" + ` as small as it can be while staying unique; do
+ not pad with unchanged lines to bridge distant edits.
+- Default: each snippet must occur exactly once. Set ` + "`replace_all`" + ` on an
+ entry only when you intentionally want every occurrence of it changed.
- Do NOT call ` + "`write_sandbox_file`" + ` with the full file to fix one line.
- ` + pythonQuoteGuidance + `
@@ -72,7 +86,7 @@ var editSandboxFileTool = BaseTool{
themselves.
## Size Handling
-- The file (and the result) must stay within 262144 bytes.
+` + fmt.Sprintf("- The file (and the result) must stay within %d bytes.", maxWriteSandboxBytes) + `
## Returns
- The path, how many replacements were made, and the new byte count.
@@ -80,12 +94,50 @@ var editSandboxFileTool = BaseTool{
schema: utils.GenerateSchema[EditSandboxFileInput](),
}
+// SandboxEdit is one targeted replacement.
+type SandboxEdit struct {
+ OldString string `json:"old_string" jsonschema:"Exact text to find, unique in the file and not overlapping any other edit in this call."` //nolint:lll // one-line struct tag
+ NewString string `json:"new_string" jsonschema:"Replacement text. Use an empty string to delete the matched text."`
+ ReplaceAll bool `json:"replace_all,omitempty" jsonschema:"If true, replace every occurrence of this old_string instead of requiring it to be unique."` //nolint:lll // one-line struct tag
+}
+
+// sandboxEditList tolerates the shapes models actually emit for an array
+// parameter: the array itself, a single object, or the array serialized as a
+// JSON string. Rejecting those would spend a round on a formatting mistake the
+// model cannot see, when the intent is unambiguous.
+type sandboxEditList []SandboxEdit
+
+func (l *sandboxEditList) UnmarshalJSON(data []byte) error {
+ var asArray []SandboxEdit
+ if err := json.Unmarshal(data, &asArray); err == nil {
+ *l = asArray
+ return nil
+ }
+
+ var single SandboxEdit
+ if err := json.Unmarshal(data, &single); err == nil {
+ *l = sandboxEditList{single}
+ return nil
+ }
+
+ var asString string
+ if err := json.Unmarshal(data, &asString); err == nil {
+ return l.UnmarshalJSON([]byte(asString))
+ }
+
+ return fmt.Errorf("edits must be an array of {old_string, new_string} objects")
+}
+
// EditSandboxFileInput defines the input parameters for edit_sandbox_file.
+//
+// There is deliberately one shape. A flat old_string/new_string pair alongside
+// edits[] would save a model a dozen bytes on a one-line fix and cost it a
+// choice it can get wrong, plus a rule about which of the two replace_all
+// attaches to. Every replacement goes in edits[], and a single-element array is
+// the ordinary way to change one thing.
type EditSandboxFileInput struct {
- Path string `json:"path" jsonschema:"Absolute sandbox path of an existing text file under /workspace (not /workspace/input)."`
- OldString string `json:"old_string" jsonschema:"Exact text to find. Include enough surrounding lines so the match is unique unless replace_all is true."`
- NewString string `json:"new_string" jsonschema:"Replacement text. Use an empty string to delete the matched text."`
- ReplaceAll bool `json:"replace_all,omitempty" jsonschema:"If true, replace every occurrence. If false (default), old_string must match exactly once."`
+ Path string `json:"path" jsonschema:"Absolute sandbox path of an existing text file under /workspace (not /workspace/input)."` //nolint:lll // one-line struct tag
+ Edits sandboxEditList `json:"edits" jsonschema:"Replacements to apply, as an array even for a single change. Each old_string is matched against the original file, not against the result of earlier edits, so they must not overlap. Send every change to one file in one call rather than calling the tool repeatedly."` //nolint:lll // one-line struct tag
}
// EditSandboxFileTool applies an exact string replacement to a sandbox file.
@@ -146,6 +198,10 @@ func (t *EditSandboxFileTool) Execute(ctx context.Context, args json.RawMessage)
}, nil
}
+ // This tool is read-modify-write, so it has to hold the path against
+ // concurrent siblings for the whole span, not just the write.
+ defer lockSandboxFile(sessionID, clean)()
+
stat, err := t.editor.StatSessionFile(ctx, sessionID, clean)
if err != nil {
return &types.ToolResult{
@@ -192,7 +248,7 @@ func (t *EditSandboxFileTool) Execute(ctx context.Context, args json.RawMessage)
}, nil
}
- updated, replacements, err := applySandboxEdit(string(raw), input.OldString, input.NewString, input.ReplaceAll)
+ updated, replacements, err := applySandboxEdits(string(raw), input.Edits)
if err != nil {
return &types.ToolResult{
Success: false,
@@ -271,27 +327,127 @@ func (t *EditSandboxFileTool) Cleanup(ctx context.Context) error {
return nil
}
-// applySandboxEdit performs an exact string replacement. replaceAll=false
-// requires a unique match.
-func applySandboxEdit(content, oldString, newString string, replaceAll bool) (string, int, error) {
- if oldString == "" {
- return "", 0, fmt.Errorf("old_string is required; copy the exact text to change, including whitespace")
+// applySandboxEdits applies every edit against the ORIGINAL content and splices
+// the results together.
+//
+// Matching against the original rather than against the running result is what
+// makes a batch predictable: the model wrote all of the old_strings while
+// looking at one version of the file, so that is the version they have to be
+// resolved in. It also turns overlap into a detectable error instead of silent
+// corruption, since two edits claiming the same bytes show up as intersecting
+// ranges before anything is written.
+func applySandboxEdits(content string, edits []SandboxEdit) (string, int, error) {
+ if len(edits) == 0 {
+ return "", 0, fmt.Errorf(
+ "edits is required: an array of {old_string, new_string}, " +
+ "with one entry even for a single change")
}
- if oldString == newString {
- return "", 0, fmt.Errorf("old_string and new_string are identical; no change would be made")
+ multi := len(edits) > 1
+
+ type span struct {
+ start, end int
+ index int
+ newString string
}
- n := strings.Count(content, oldString)
- if n == 0 {
- return "", 0, fmt.Errorf("old_string was not found in the file. Copy the exact text (including whitespace) from the file")
+ spans := make([]span, 0, len(edits))
+
+ for i, e := range edits {
+ if err := validateSandboxEdit(e, i, multi); err != nil {
+ return "", 0, err
+ }
+ found := indexAllNonOverlapping(content, e.OldString)
+ if len(found) == 0 {
+ return "", 0, notFoundSandboxEditError(i, multi)
+ }
+ if len(found) > 1 && !e.ReplaceAll {
+ return "", 0, ambiguousSandboxEditError(i, multi, len(found))
+ }
+ for _, start := range found {
+ spans = append(spans, span{
+ start: start,
+ end: start + len(e.OldString),
+ index: i,
+ newString: e.NewString,
+ })
+ }
}
- if n > 1 && !replaceAll {
- return "", 0, fmt.Errorf(
- "old_string matched %d times. Include more surrounding context so it is unique, or set replace_all=true",
- n,
- )
+
+ sort.Slice(spans, func(a, b int) bool { return spans[a].start < spans[b].start })
+ for i := 1; i < len(spans); i++ {
+ if spans[i].start < spans[i-1].end {
+ return "", 0, overlappingSandboxEditError(spans[i-1].index, spans[i].index)
+ }
+ }
+
+ var b strings.Builder
+ prev := 0
+ for _, s := range spans {
+ b.WriteString(content[prev:s.start])
+ b.WriteString(s.newString)
+ prev = s.end
+ }
+ b.WriteString(content[prev:])
+
+ return b.String(), len(spans), nil
+}
+
+// indexAllNonOverlapping returns the start offset of every occurrence of sub,
+// counting the same way strings.Count does: after a match, scanning resumes
+// past it rather than one byte in.
+func indexAllNonOverlapping(content, sub string) []int {
+ var found []int
+ for offset := 0; ; {
+ i := strings.Index(content[offset:], sub)
+ if i < 0 {
+ return found
+ }
+ found = append(found, offset+i)
+ offset += i + len(sub)
+ }
+}
+
+func validateSandboxEdit(e SandboxEdit, index int, multi bool) error {
+ if e.OldString == "" {
+ if multi {
+ return fmt.Errorf(
+ "edits[%d].old_string is required; copy the exact text to change, including whitespace",
+ index,
+ )
+ }
+ return fmt.Errorf("old_string is required; copy the exact text to change, including whitespace")
}
- if replaceAll {
- return strings.ReplaceAll(content, oldString, newString), n, nil
+ if e.OldString == e.NewString {
+ if multi {
+ return fmt.Errorf("edits[%d].old_string and new_string are identical; no change would be made", index)
+ }
+ return fmt.Errorf("old_string and new_string are identical; no change would be made")
}
- return strings.Replace(content, oldString, newString, 1), 1, nil
+ return nil
+}
+
+func notFoundSandboxEditError(index int, multi bool) error {
+ if multi {
+ return fmt.Errorf(
+ "edits[%d].old_string was not found in the file. Copy the exact text (including whitespace) from the file",
+ index)
+ }
+ return fmt.Errorf("old_string was not found in the file. Copy the exact text (including whitespace) from the file")
+}
+
+func ambiguousSandboxEditError(index int, multi bool, occurrences int) error {
+ if multi {
+ return fmt.Errorf(
+ "edits[%d].old_string matched %d times. Include more surrounding context so it is unique, "+
+ "or set replace_all on that entry",
+ index, occurrences)
+ }
+ return fmt.Errorf(
+ "old_string matched %d times. Include more surrounding context so it is unique, or set replace_all",
+ occurrences)
+}
+
+func overlappingSandboxEditError(a, b int) error {
+ return fmt.Errorf(
+ "edits[%d] and edits[%d] cover overlapping text. Merge them into one edit that spans both changes",
+ a, b)
}
diff --git a/internal/agent/tools/sandbox_edit_test.go b/internal/agent/tools/sandbox_edit_test.go
index dfcbbef62..d04dea5e6 100644
--- a/internal/agent/tools/sandbox_edit_test.go
+++ b/internal/agent/tools/sandbox_edit_test.go
@@ -58,6 +58,14 @@ func (f *fakeSandboxFileEditor) WriteSessionWorkspaceFile(_ context.Context, _,
return nil
}
+// applySandboxEdit exercises a one-entry batch, which is what most of these
+// cases are about.
+func applySandboxEdit(content, oldString, newString string, replaceAll bool) (string, int, error) {
+ return applySandboxEdits(content, []SandboxEdit{
+ {OldString: oldString, NewString: newString, ReplaceAll: replaceAll},
+ })
+}
+
func TestApplySandboxEditUniqueAndReplaceAll(t *testing.T) {
content := "a = '/home/user/Desktop/deck.pptx'\nprint(a)\n"
@@ -94,6 +102,142 @@ func TestApplySandboxEditUniqueAndReplaceAll(t *testing.T) {
assert.Contains(t, err.Error(), "old_string is required")
}
+// Every edit resolves against the original content, so a batch is
+// order-independent: an entry cannot be shifted or swallowed by one that
+// happens to be applied before it.
+func TestApplySandboxEditsResolvesAgainstOriginal(t *testing.T) {
+ content := "alpha\nbeta\ngamma\n"
+
+ updated, n, err := applySandboxEdits(content, []SandboxEdit{
+ {OldString: "gamma", NewString: "GAMMA"},
+ {OldString: "alpha", NewString: "ALPHA"},
+ })
+
+ require.NoError(t, err)
+ assert.Equal(t, 2, n)
+ assert.Equal(t, "ALPHA\nbeta\nGAMMA\n", updated)
+}
+
+// Two edits claiming the same bytes would corrupt the file silently, so the
+// batch is refused with the indices that collide.
+func TestApplySandboxEditsRejectsOverlap(t *testing.T) {
+ content := "the quick brown fox\n"
+
+ _, _, err := applySandboxEdits(content, []SandboxEdit{
+ {OldString: "quick brown", NewString: "slow"},
+ {OldString: "brown fox", NewString: "grey wolf"},
+ })
+
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), "overlapping")
+ assert.Contains(t, err.Error(), "edits[0]")
+ assert.Contains(t, err.Error(), "edits[1]")
+}
+
+// A failed entry must not leave the file half-edited, and the error has to say
+// which entry to fix.
+func TestApplySandboxEditsFailsWholeBatchWithIndex(t *testing.T) {
+ content := "alpha\nbeta\n"
+
+ _, _, err := applySandboxEdits(content, []SandboxEdit{
+ {OldString: "alpha", NewString: "ALPHA"},
+ {OldString: "nowhere", NewString: "x"},
+ })
+
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), "edits[1]")
+ assert.Contains(t, err.Error(), "not found")
+}
+
+// replace_all lives on the entry, so one batch can mix a global rename with
+// edits that must still be unique.
+func TestApplySandboxEditsMixesReplaceAllWithUniqueEntries(t *testing.T) {
+ content := "tmp = 1\nprint(tmp)\nuse(tmp)\nNAME = 'x'\n"
+
+ updated, n, err := applySandboxEdits(content, []SandboxEdit{
+ {OldString: "tmp", NewString: "total", ReplaceAll: true},
+ {OldString: "NAME = 'x'", NewString: "NAME = 'y'"},
+ })
+
+ require.NoError(t, err)
+ assert.Equal(t, 4, n)
+ assert.Equal(t, "total = 1\nprint(total)\nuse(total)\nNAME = 'y'\n", updated)
+
+ // An entry that matches several times without replace_all is still refused,
+ // and the error points at the entry to fix.
+ _, _, err = applySandboxEdits(content, []SandboxEdit{
+ {OldString: "NAME = 'x'", NewString: "NAME = 'y'"},
+ {OldString: "tmp", NewString: "total"},
+ })
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), "edits[1]")
+ assert.Contains(t, err.Error(), "replace_all")
+}
+
+// A replace_all expansion has to take part in overlap detection like any other
+// span, or it could quietly consume text another entry is claiming.
+func TestApplySandboxEditsDetectsOverlapAgainstReplaceAll(t *testing.T) {
+ _, _, err := applySandboxEdits("foo bar\nfoo baz\n", []SandboxEdit{
+ {OldString: "foo", NewString: "qux", ReplaceAll: true},
+ {OldString: "foo baz", NewString: "nope"},
+ })
+
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), "overlapping")
+}
+
+func TestApplySandboxEditsRequiresAtLeastOneEntry(t *testing.T) {
+ _, _, err := applySandboxEdits("alpha\n", nil)
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), "edits is required")
+}
+
+// Models emit array parameters as a bare object or as a JSON string often
+// enough that rejecting those spends a round on a formatting slip the model
+// cannot see.
+func TestSandboxEditListAcceptsModelShapes(t *testing.T) {
+ var asArray EditSandboxFileInput
+ require.NoError(t, json.Unmarshal([]byte(
+ `{"path":"/workspace/a.py","edits":[{"old_string":"a","new_string":"b"}]}`), &asArray))
+ assert.Len(t, asArray.Edits, 1)
+
+ var asObject EditSandboxFileInput
+ require.NoError(t, json.Unmarshal([]byte(
+ `{"path":"/workspace/a.py","edits":{"old_string":"a","new_string":"b"}}`), &asObject))
+ require.Len(t, asObject.Edits, 1)
+ assert.Equal(t, "a", asObject.Edits[0].OldString)
+
+ var asString EditSandboxFileInput
+ require.NoError(t, json.Unmarshal([]byte(
+ `{"path":"/workspace/a.py","edits":"[{\"old_string\":\"a\",\"new_string\":\"b\"}]"}`), &asString))
+ require.Len(t, asString.Edits, 1)
+ assert.Equal(t, "b", asString.Edits[0].NewString)
+}
+
+// End to end: one call, several changes, one write.
+func TestEditSandboxFileAppliesBatchInOneWrite(t *testing.T) {
+ editor := &fakeSandboxFileEditor{
+ files: map[string][]byte{
+ "/workspace/run.py": []byte("SRC = '/tmp/in'\nDST = '/tmp/out'\nDEBUG = True\n"),
+ },
+ }
+
+ result, err := NewEditSandboxFileTool(editor).Execute(sandboxFileTestContext(), json.RawMessage(
+ `{"path":"/workspace/run.py","edits":[`+
+ `{"old_string":"'/tmp/in'","new_string":"'/workspace/input'"},`+
+ `{"old_string":"DEBUG = True","new_string":"DEBUG = False"}]}`))
+
+ require.NoError(t, err)
+ require.True(t, result.Success, result.Error)
+ assert.Equal(t, 2, result.Data["replacements"])
+ assert.Equal(t, 1, editor.writes)
+
+ final := string(editor.files["/workspace/run.py"])
+ assert.Contains(t, final, "SRC = '/workspace/input'")
+ assert.Contains(t, final, "DEBUG = False")
+ assert.Contains(t, final, "DST = '/tmp/out'")
+}
+
func TestEditSandboxFileReplacesUniqueSnippet(t *testing.T) {
path := "/workspace/output/generate_wifi_ppt.py"
original := "from pptx import Presentation\n" +
@@ -229,15 +373,14 @@ func TestEditSandboxFileRegistryHintsWhenPathMissing(t *testing.T) {
}
func mustEditSandboxArgs(path, oldString, newString string, replaceAll bool) json.RawMessage {
- payload := map[string]any{
- "path": path,
- "old_string": oldString,
- "new_string": newString,
- }
+ edit := map[string]any{"old_string": oldString, "new_string": newString}
if replaceAll {
- payload["replace_all"] = true
+ edit["replace_all"] = true
}
- raw, err := json.Marshal(payload)
+ raw, err := json.Marshal(map[string]any{
+ "path": path,
+ "edits": []any{edit},
+ })
if err != nil {
panic(err)
}
diff --git a/internal/agent/tools/sandbox_read.go b/internal/agent/tools/sandbox_read.go
index 3b13030af..3b11c3491 100644
--- a/internal/agent/tools/sandbox_read.go
+++ b/internal/agent/tools/sandbox_read.go
@@ -11,9 +11,10 @@
// - Directory guardrail: path must sit underneath /workspace, matching
// what this session may write. Skills that need to peek outside it
// should print via stdout.
-// - Stat-first size cap: files over 64 KiB are never downloaded. The
-// model receives metadata and uses shell_exec with sed/head/tail/grep/awk
-// to inspect only the relevant text section.
+// - Paginated reads: a page is bounded by a line count, a byte budget, and
+// the registry's rune budget, and a partial page ends with the offset to
+// continue from. Files over 8 MiB are never downloaded; the model gets
+// metadata and uses shell_exec with sed/head/tail/grep/awk instead.
// - Binary handling: binary bytes are never returned or base64-encoded into
// model/client data. ArtifactCollector remains the download path.
package tools
@@ -24,6 +25,9 @@ import (
"fmt"
"path"
"strings"
+ "sync"
+ "time"
+ "unicode/utf8"
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/sandbox"
@@ -31,11 +35,26 @@ import (
"github.com/Tencent/WeKnora/internal/utils"
)
-// A read larger than this is refused before ReadSessionFile is called. The
-// caller may request a smaller ceiling, but never raise this hard limit.
const (
+ // How much of the file one call may put in front of the model. This bounds
+ // context, not I/O: a larger file is paginated, not refused. The caller may
+ // lower it but never raise it.
defaultReadSandboxMaxBytes int64 = 64 * 1024
maxReadSandboxMaxBytes int64 = 64 * 1024
+
+ // The line ceiling for one page, so a file of many short lines does not
+ // arrive as thousands of nearly empty rows.
+ defaultReadSandboxMaxLines = 2000
+
+ // Room left for the header, the fences, and the continuation hint when
+ // sizing a page against the registry's output budget.
+ readSandboxPageOverhead = 512
+
+ // How large a file may be and still be downloaded to serve a page. This is
+ // the I/O bound, and it matches what write_sandbox_file can build by
+ // appending: a file the agent can write but can never read back is a dead
+ // end, and shell_exec is not registered in every deployment.
+ maxReadSandboxDownloadBytes int64 = maxSandboxFileBytes
)
// Tool schema
@@ -74,10 +93,14 @@ var readSandboxFileTool = BaseTool{
` + "`write_sandbox_file`" + `. Reads outside ` + "`/workspace`" + ` are rejected.
## Size Handling
-- Files larger than 64 KiB are NOT downloaded or returned.
-- For large text, use ` + "`shell_exec`" + ` with ` + "`sed -n`" + `, ` + "`head`" + `,
- ` + "`tail`" + `, ` + "`grep`" + `, or ` + "`awk`" + ` to inspect a targeted section.
-- ` + "`max_bytes`" + ` may lower the refusal threshold but cannot exceed 65536.
+- One call returns at most 2000 lines, and as much text as fits this agent's
+ tool-output budget. A larger file is paginated, not refused.
+- A partial page ends with the exact ` + "`offset`" + ` to continue from. Repeat
+ the call with it until the file is exhausted; do not guess the offset.
+- ` + "`max_bytes`" + ` may lower the per-call byte budget but cannot exceed 65536.
+- Files larger than 8 MiB are not downloaded at all; use ` + "`shell_exec`" + `
+ with ` + "`sed -n`" + `, ` + "`head`" + `, ` + "`tail`" + `, ` + "`grep`" + `, or
+ ` + "`awk`" + ` to inspect a targeted section.
## Binary Files
- Binary bytes are never returned to the model or embedded as base64.
@@ -91,9 +114,14 @@ type ReadSandboxFileInput struct {
// Path is the absolute path inside the sandbox to read. Required.
// Must sit underneath /workspace.
Path string `json:"path" jsonschema:"Absolute path under /workspace: an artifact, an attachment, or a file you wrote yourself. Get paths from list_sandbox_files or sandbox_attachments."` //nolint:lll // one-line struct tag
- // MaxBytes is the largest file the tool may download. Zero uses 64 KiB;
- // callers may lower but never raise the hard 64 KiB ceiling.
- MaxBytes int64 `json:"max_bytes,omitempty" jsonschema:"Optional maximum file size to read. Defaults to 65536 bytes and is hard-capped at 65536. Larger files are not downloaded; use shell_exec with sed/head/tail/grep/awk."`
+ // Offset is the 1-indexed line to start the page at. Zero means the
+ // beginning, so an unset field reads the file from the top.
+ Offset int `json:"offset,omitempty" jsonschema:"Line number to start reading from, 1-indexed. Omit to read from the start. When a previous call reported it returned a partial page, pass the offset it gave you to continue."` //nolint:lll // one-line struct tag
+ // Limit caps the lines in one page. Zero uses defaultReadSandboxMaxLines.
+ Limit int `json:"limit,omitempty" jsonschema:"Maximum number of lines to return. Defaults to 2000."`
+ // MaxBytes caps the bytes one call returns. Zero uses 64 KiB; callers may
+ // lower but never raise the hard 64 KiB ceiling.
+ MaxBytes int64 `json:"max_bytes,omitempty" jsonschema:"Optional maximum bytes to return in this call. Defaults to 65536 and is hard-capped at 65536. This paginates the file rather than refusing it."` //nolint:lll // one-line struct tag
}
// ReadSandboxFileTool exposes SandboxFileSource.ReadSessionFile as a
@@ -101,6 +129,66 @@ type ReadSandboxFileInput struct {
type ReadSandboxFileTool struct {
BaseTool
source SandboxFileSource
+
+ mu sync.Mutex
+ cached *readCacheEntry
+}
+
+// readCacheEntry holds the last file downloaded, so consecutive pages of one
+// file do not each pull it again.
+type readCacheEntry struct {
+ sessionID string
+ path string
+ size int64
+ modTime time.Time
+ epoch uint64
+ data []byte
+}
+
+// readWithCache returns the file contents, reusing the previous download when
+// nothing indicates the file changed.
+//
+// A page is cut out of the whole file, and none of the sandbox backends expose
+// a range read — RemoteClient.ReadFile takes a path and returns everything. So
+// without this, every page downloads the file again: paging a 1 MB artifact at
+// roughly 23 KB per page is 45 full downloads and, worse, 45 round trips. The
+// backends have no range read, so the only way to page is to keep the last
+// download and slice it.
+//
+// One slot rather than a map: paging walks a single file, and a slot bounds
+// what is held to one file instead of to every file the turn happened to read.
+// The tool instance lives for one agent run, so nothing outlives the turn.
+func (t *ReadSandboxFileTool) readWithCache(
+ ctx context.Context, sessionID, filePath string, stat *sandbox.RemoteStatEntry,
+) ([]byte, error) {
+ epoch := sandboxMutationEpoch()
+
+ t.mu.Lock()
+ hit := t.cached
+ t.mu.Unlock()
+
+ if hit != nil && hit.sessionID == sessionID && hit.path == filePath &&
+ hit.size == stat.Size && hit.modTime.Equal(stat.ModTime) && hit.epoch == epoch {
+ return hit.data, nil
+ }
+
+ data, err := t.source.ReadSessionFile(ctx, sessionID, filePath)
+ if err != nil {
+ return nil, err
+ }
+
+ t.mu.Lock()
+ t.cached = &readCacheEntry{
+ sessionID: sessionID,
+ path: filePath,
+ size: stat.Size,
+ modTime: stat.ModTime,
+ epoch: epoch,
+ data: data,
+ }
+ t.mu.Unlock()
+
+ return data, nil
}
// NewReadSandboxFileTool constructs the tool. `source` MUST NOT be nil:
@@ -210,13 +298,13 @@ func (t *ReadSandboxFileTool) Execute(ctx context.Context, args json.RawMessage)
),
}, nil
}
- if stat.Size > maxBytes {
+ if stat.Size > maxReadSandboxDownloadBytes {
logger.Infof(ctx, "[Tool][ReadSandboxFile] refused oversize file: session=%s path=%s size=%d limit=%d",
- sessionID, clean, stat.Size, maxBytes)
- return oversizedSandboxFileResult(sessionID, clean, rootDir, stat.Size, maxBytes), nil
+ sessionID, clean, stat.Size, maxReadSandboxDownloadBytes)
+ return oversizedSandboxFileResult(sessionID, clean, rootDir, stat.Size), nil
}
- data, err := t.source.ReadSessionFile(ctx, sessionID, clean)
+ data, err := t.readWithCache(ctx, sessionID, clean, stat)
if err != nil {
logger.Warnf(ctx, "[Tool][ReadSandboxFile] read failed: session=%s path=%s err=%v",
sessionID, clean, err)
@@ -227,60 +315,194 @@ func (t *ReadSandboxFileTool) Execute(ctx context.Context, args json.RawMessage)
}
total := int64(len(data))
- // The file may have grown between Stat and Read. Do not return a prefix
- // from a full oversized download as if it were an intentional partial read.
- if total > maxBytes {
+ // The file may have grown between Stat and Read.
+ if total > maxReadSandboxDownloadBytes {
logger.Warnf(ctx, "[Tool][ReadSandboxFile] file grew during read: session=%s path=%s size=%d limit=%d",
- sessionID, clean, total, maxBytes)
- return oversizedSandboxFileResult(sessionID, clean, rootDir, total, maxBytes), nil
+ sessionID, clean, total, maxReadSandboxDownloadBytes)
+ return oversizedSandboxFileResult(sessionID, clean, rootDir, total), nil
}
binary := isBinaryShellOutput(string(data))
+ resultData := map[string]interface{}{
+ "session_id": sessionID,
+ "path": clean,
+ "root": rootDir,
+ "size": total,
+ "binary": binary,
+ }
+
// Build LLM-facing output. Text is inlined only once in Output; binary
// bytes are suppressed and represented by metadata.
var b strings.Builder
- b.WriteString(fmt.Sprintf("=== Sandbox file: %s ===\n\n", clean))
- b.WriteString(fmt.Sprintf("size=%d bytes, returned=%d bytes\n", total, len(data)))
-
- resultData := map[string]interface{}{
- "session_id": sessionID,
- "path": clean,
- "root": rootDir,
- "size": total,
- "returned_bytes": len(data),
- "truncated": false,
- "binary": binary,
- }
+ fmt.Fprintf(&b, "=== Sandbox file: %s ===\n\n", clean)
if binary {
+ fmt.Fprintf(&b, "size=%d bytes, returned=0 bytes\n", total)
b.WriteString("binary file — content suppressed; use the artifact attachment to download it.\n")
- } else {
- b.WriteString("\n```\n")
- b.Write(data)
- if len(data) > 0 && data[len(data)-1] != '\n' {
- b.WriteString("\n")
- }
- b.WriteString("```\n")
+ resultData["returned_bytes"] = 0
+ resultData["truncated"] = false
+ logger.Infof(ctx, "[Tool][ReadSandboxFile] session=%s path=%s size=%d binary", sessionID, clean, total)
+ return &types.ToolResult{Success: true, Output: b.String(), Data: resultData}, nil
}
- logger.Infof(ctx, "[Tool][ReadSandboxFile] session=%s path=%s size=%d returned=%d binary=%v",
- sessionID, clean, total, len(data), binary)
+ // The registry truncates any output past its rune ceiling by deleting the
+ // MIDDLE and keeping head and tail. On a page that would be the worst
+ // possible outcome: the continuation hint lives at the tail, so it would
+ // survive and certify "lines 1-2000 shown" while a slab out of the middle
+ // was silently dropped. Sizing the page against the same budget the
+ // registry enforces means that truncation never fires here.
+ //
+ // The two budgets are also in different units, and the mismatch runs
+ // opposite to intuition: 64 KiB of CJK is ~22k runes and fits, while 64 KiB
+ // of ASCII is 65k runes and does not.
+ maxRunes := max(OutputBudget(ctx)-readSandboxPageOverhead, 1)
+ page := paginateSandboxFile(string(data), input.Offset, input.Limit, maxBytes, maxRunes)
+
+ // A line wider than the whole byte budget cannot be paged around: every
+ // retry would land on the same line and return the same nothing. Name the
+ // escape hatch instead of letting the model rediscover the wall.
+ if page.lineTooLarge {
+ fmt.Fprintf(&b,
+ "size=%d bytes, returned=0 bytes\n\n"+
+ "[Line %d is %d bytes, over the %d byte budget for one call. "+
+ "Use shell_exec: sed -n '%dp' %s | head -c %d]\n",
+ total, page.startLine, page.lineBytes, maxBytes, page.startLine, clean, maxBytes,
+ )
+ resultData["returned_bytes"] = 0
+ resultData["truncated"] = true
+ resultData["total_lines"] = page.totalLines
+ return &types.ToolResult{Success: true, Output: b.String(), Data: resultData}, nil
+ }
- return &types.ToolResult{
- Success: true,
- Output: b.String(),
- Data: resultData,
- }, nil
+ fmt.Fprintf(&b, "size=%d bytes, returned=%d bytes\n", total, len(page.text))
+ b.WriteString("\n```\n")
+ b.WriteString(page.text)
+ if page.text != "" && !strings.HasSuffix(page.text, "\n") {
+ b.WriteString("\n")
+ }
+ b.WriteString("```\n")
+
+ // The continuation hint rides on the result rather than the system prompt:
+ // it reaches the model at the moment it is actionable, and it carries the
+ // exact offset so continuing does not require arithmetic.
+ if page.nextOffset > 0 {
+ fmt.Fprintf(&b,
+ "\n[Showing lines %d-%d of %d. Use offset=%d to continue.]\n",
+ page.startLine, page.endLine, page.totalLines, page.nextOffset,
+ )
+ } else if page.startLine > 1 {
+ fmt.Fprintf(&b,
+ "\n[Showing lines %d-%d of %d — end of file.]\n",
+ page.startLine, page.endLine, page.totalLines,
+ )
+ }
+
+ resultData["returned_bytes"] = len(page.text)
+ resultData["truncated"] = page.nextOffset > 0
+ resultData["total_lines"] = page.totalLines
+ resultData["start_line"] = page.startLine
+ resultData["end_line"] = page.endLine
+ if page.nextOffset > 0 {
+ resultData["next_offset"] = page.nextOffset
+ }
+
+ logger.Infof(ctx, "[Tool][ReadSandboxFile] session=%s path=%s size=%d lines=%d-%d/%d returned=%d",
+ sessionID, clean, total, page.startLine, page.endLine, page.totalLines, len(page.text))
+
+ return &types.ToolResult{Success: true, Output: b.String(), Data: resultData}, nil
+}
+
+// sandboxFilePage is one window of a file's lines plus what the model needs to
+// ask for the next one.
+type sandboxFilePage struct {
+ text string
+ startLine int // 1-indexed, inclusive
+ endLine int // 1-indexed, inclusive
+ totalLines int
+ nextOffset int // 0 once the page reaches the end of the file
+
+ // lineTooLarge marks the case where a single line exceeds the byte budget,
+ // so paging cannot make progress at all.
+ lineTooLarge bool
+ lineBytes int
+}
+
+// paginateSandboxFile returns the window of content starting at the 1-indexed
+// offset, bounded by a line count, a byte budget, and a rune budget. Whichever
+// bound is hit first ends the page.
+//
+// Pages always break at a line boundary, which is what keeps them UTF-8 safe:
+// 0x0A cannot occur inside a multi-byte sequence, so splitting on newlines can
+// never cut a rune in half no matter where the byte budget lands.
+func paginateSandboxFile(content string, offset, limit int, maxBytes int64, maxRunes int) sandboxFilePage {
+ if offset <= 0 {
+ offset = 1
+ }
+ if limit <= 0 {
+ limit = defaultReadSandboxMaxLines
+ }
+ if maxRunes <= 0 {
+ maxRunes = int(maxBytes)
+ }
+
+ lines := strings.Split(content, "\n")
+ // A trailing newline terminates the last line; it does not begin an empty
+ // one. Without this a file of N lines reports N+1 and the final page is
+ // always blank.
+ if n := len(lines); n > 0 && lines[n-1] == "" {
+ lines = lines[:n-1]
+ }
+ total := len(lines)
+
+ if offset > total {
+ return sandboxFilePage{startLine: offset, endLine: offset - 1, totalLines: total}
+ }
+
+ start := offset - 1
+ var b strings.Builder
+ var usedBytes int64
+ var usedRunes int
+ end := start
+ for ; end < total && end-start < limit; end++ {
+ costBytes := int64(len(lines[end])) + 1
+ costRunes := utf8.RuneCountInString(lines[end]) + 1
+ if usedBytes+costBytes > maxBytes || usedRunes+costRunes > maxRunes {
+ if end == start {
+ return sandboxFilePage{
+ startLine: offset,
+ totalLines: total,
+ lineTooLarge: true,
+ lineBytes: len(lines[end]),
+ }
+ }
+ break
+ }
+ b.WriteString(lines[end])
+ b.WriteByte('\n')
+ usedBytes += costBytes
+ usedRunes += costRunes
+ }
+
+ page := sandboxFilePage{
+ text: b.String(),
+ startLine: offset,
+ endLine: end,
+ totalLines: total,
+ }
+ if end < total {
+ page.nextOffset = end + 1
+ }
+ return page
}
-func oversizedSandboxFileResult(sessionID, filePath, rootDir string, size, limit int64) *types.ToolResult {
+func oversizedSandboxFileResult(sessionID, filePath, rootDir string, size int64) *types.ToolResult {
output := fmt.Sprintf(
"=== Sandbox file too large to read: %s ===\n\n"+
"size=%d bytes, limit=%d bytes, returned=0 bytes\n\n"+
"The file was not downloaded. Use shell_exec with sed -n, head, tail, grep, or awk "+
"to inspect only the relevant text section. Binary files remain available through the artifact attachment.\n",
- filePath, size, limit,
+ filePath, size, maxReadSandboxDownloadBytes,
)
return &types.ToolResult{
Success: true,
@@ -290,7 +512,7 @@ func oversizedSandboxFileResult(sessionID, filePath, rootDir string, size, limit
"path": filePath,
"root": rootDir,
"size": size,
- "limit": limit,
+ "limit": maxReadSandboxDownloadBytes,
"returned_bytes": 0,
"truncated": true,
"read_refused": true,
diff --git a/internal/agent/tools/sandbox_read_test.go b/internal/agent/tools/sandbox_read_test.go
index f64024af1..73027cdd8 100644
--- a/internal/agent/tools/sandbox_read_test.go
+++ b/internal/agent/tools/sandbox_read_test.go
@@ -6,6 +6,8 @@ import (
"fmt"
"strings"
"testing"
+ "time"
+ "unicode/utf8"
"github.com/Tencent/WeKnora/internal/sandbox"
"github.com/stretchr/testify/assert"
@@ -42,9 +44,15 @@ func sandboxFileTestContext() context.Context {
return WithToolExecContext(context.Background(), &ToolExecContext{SessionID: "session-1"})
}
+// Past the download ceiling the file is never fetched: paging it would mean
+// pulling megabytes over the wire for every page.
func TestReadSandboxFileRefusesOversizeBeforeRead(t *testing.T) {
source := &fakeSandboxFileSource{
- stat: &sandbox.RemoteStatEntry{Path: "/workspace/output/large.txt", Type: sandbox.RemoteEntryFile, Size: maxReadSandboxMaxBytes + 1},
+ stat: &sandbox.RemoteStatEntry{
+ Path: "/workspace/output/large.txt",
+ Type: sandbox.RemoteEntryFile,
+ Size: maxReadSandboxDownloadBytes + 1,
+ },
data: []byte("must not be read"),
}
@@ -58,10 +66,252 @@ func TestReadSandboxFileRefusesOversizeBeforeRead(t *testing.T) {
assert.Equal(t, 1, source.statCalls)
assert.Zero(t, source.readCalls)
assert.Equal(t, true, result.Data["read_refused"])
- assert.Equal(t, int64(maxReadSandboxMaxBytes+1), result.Data["size"])
+ assert.Equal(t, maxReadSandboxDownloadBytes+1, result.Data["size"])
assert.Contains(t, result.Output, "shell_exec")
}
+// A file over the per-call byte budget but under the download ceiling is
+// paginated. write_sandbox_file can build such a file by appending, so
+// refusing to read it back would strand the agent's own output.
+func TestReadSandboxFilePaginatesOverBudgetFile(t *testing.T) {
+ var content strings.Builder
+ const lines = 400
+ for i := 1; i <= lines; i++ {
+ content.WriteString(strings.Repeat("x", 200))
+ content.WriteString("\n")
+ }
+ source := &fakeSandboxFileSource{
+ stat: &sandbox.RemoteStatEntry{
+ Path: "/workspace/output/deck.html",
+ Type: sandbox.RemoteEntryFile,
+ Size: int64(content.Len()),
+ },
+ data: []byte(content.String()),
+ }
+ tool := NewReadSandboxFileTool(source)
+
+ // Follow the offsets the way the model would, and reassemble. The property
+ // that matters is that paging recovers the file exactly: no gap between
+ // consecutive pages, and no line served twice.
+ var seen []string
+ offset, pages := 1, 0
+ for {
+ pages++
+ require.Less(t, pages, 50, "paging is not making progress")
+
+ result, err := tool.Execute(sandboxFileTestContext(), json.RawMessage(
+ fmt.Sprintf(`{"path":"/workspace/output/deck.html","offset":%d}`, offset)))
+ require.NoError(t, err)
+ require.True(t, result.Success)
+ assert.Equal(t, lines, result.Data["total_lines"])
+ assert.Equal(t, offset, result.Data["start_line"])
+
+ body := strings.SplitN(result.Output, "```\n", 2)[1]
+ body = strings.TrimSuffix(strings.SplitN(body, "\n```", 2)[0], "\n")
+ seen = append(seen, strings.Split(body, "\n")...)
+
+ if result.Data["truncated"] != true {
+ assert.Contains(t, result.Output, "end of file")
+ assert.NotContains(t, result.Data, "next_offset")
+ break
+ }
+ next := result.Data["next_offset"].(int)
+ assert.Contains(t, result.Output, fmt.Sprintf("Use offset=%d to continue.", next))
+ assert.Equal(t, result.Data["end_line"].(int)+1, next, "pages must not skip a line")
+ offset = next
+ }
+
+ assert.Greater(t, pages, 1, "the file was supposed to need several pages")
+ assert.Len(t, seen, lines)
+ assert.Equal(t, strings.TrimSuffix(content.String(), "\n"), strings.Join(seen, "\n"))
+}
+
+// Paging cannot make progress when one line exceeds the whole budget, so the
+// result has to name the escape hatch instead of returning an empty page the
+// model will retry forever.
+func TestReadSandboxFileReportsUnpageableLine(t *testing.T) {
+ content := []byte(strings.Repeat("y", int(maxReadSandboxMaxBytes)+10) + "\n")
+ source := &fakeSandboxFileSource{
+ stat: &sandbox.RemoteStatEntry{
+ Path: "/workspace/output/min.js",
+ Type: sandbox.RemoteEntryFile,
+ Size: int64(len(content)),
+ },
+ data: content,
+ }
+
+ result, err := NewReadSandboxFileTool(source).Execute(sandboxFileTestContext(),
+ json.RawMessage(`{"path":"/workspace/output/min.js"}`))
+
+ require.NoError(t, err)
+ require.True(t, result.Success)
+ assert.Equal(t, 0, result.Data["returned_bytes"])
+ assert.Contains(t, result.Output, "Line 1 is")
+ assert.Contains(t, result.Output, "sed -n '1p'")
+}
+
+// The registry truncates over-budget output by deleting the MIDDLE and keeping
+// head and tail. A page must never reach that path: the continuation hint sits
+// at the tail, so it would survive and vouch for lines that were silently
+// dropped out of the middle. The page therefore has to be sized against the
+// same rune budget the registry enforces.
+//
+// ASCII is the case that breaks, not CJK: 64 KiB of Chinese is ~22k runes and
+// fits under the ceiling, while 64 KiB of ASCII is 65k runes and does not.
+func TestReadSandboxFilePageSurvivesRegistryTruncation(t *testing.T) {
+ var content strings.Builder
+ for i := 0; i < 1500; i++ {
+ content.WriteString(strings.Repeat("x", 200))
+ content.WriteString("\n")
+ }
+ source := &fakeSandboxFileSource{
+ stat: &sandbox.RemoteStatEntry{
+ Path: "/workspace/output/big.txt",
+ Type: sandbox.RemoteEntryFile,
+ Size: int64(content.Len()),
+ },
+ data: []byte(content.String()),
+ }
+
+ registry := NewToolRegistry()
+ registry.RegisterTool(NewReadSandboxFileTool(source))
+
+ result, err := registry.ExecuteTool(sandboxFileTestContext(),
+ ToolReadSandboxFile, json.RawMessage(`{"path":"/workspace/output/big.txt"}`))
+
+ require.NoError(t, err)
+ require.True(t, result.Success)
+ assert.NotContains(t, result.Output, "output truncated",
+ "the page was over the registry ceiling, so its middle was cut away")
+ assert.LessOrEqual(t, utf8.RuneCountInString(result.Output), DefaultMaxToolOutput)
+ assert.Contains(t, result.Output, "to continue.")
+}
+
+// No sandbox backend exposes a range read, so a page is cut out of a whole
+// download. Without a cache, paging a file means downloading it once per page.
+func TestReadSandboxFilePagingDownloadsTheFileOnce(t *testing.T) {
+ var content strings.Builder
+ for i := 0; i < 1500; i++ {
+ content.WriteString(strings.Repeat("x", 200))
+ content.WriteString("\n")
+ }
+ source := &fakeSandboxFileSource{
+ stat: &sandbox.RemoteStatEntry{
+ Path: "/workspace/output/big.txt",
+ Type: sandbox.RemoteEntryFile,
+ Size: int64(content.Len()),
+ ModTime: time.Unix(1700000000, 0),
+ },
+ data: []byte(content.String()),
+ }
+ tool := NewReadSandboxFileTool(source)
+
+ offset := 1
+ for pages := 0; ; pages++ {
+ require.Less(t, pages, 50, "paging is not making progress")
+ result, err := tool.Execute(sandboxFileTestContext(), json.RawMessage(
+ fmt.Sprintf(`{"path":"/workspace/output/big.txt","offset":%d}`, offset)))
+ require.NoError(t, err)
+ require.True(t, result.Success)
+ if result.Data["truncated"] != true {
+ break
+ }
+ offset = result.Data["next_offset"].(int)
+ }
+
+ assert.Equal(t, 1, source.readCalls, "each page re-downloaded the whole file")
+ assert.Greater(t, source.statCalls, 1, "every page must still stat, to notice a change")
+}
+
+// The cache must never outlive the file it describes. Stat alone cannot see a
+// same-length replacement within one mtime tick, so a completed mutation
+// invalidates regardless of what stat reports.
+func TestReadSandboxFileCacheIsDroppedAfterAMutation(t *testing.T) {
+ stat := &sandbox.RemoteStatEntry{
+ Path: "/workspace/run.py",
+ Type: sandbox.RemoteEntryFile,
+ Size: 9,
+ ModTime: time.Unix(1700000000, 0),
+ }
+ source := &fakeSandboxFileSource{stat: stat, data: []byte("DEBUG = 1")}
+ tool := NewReadSandboxFileTool(source)
+ args := json.RawMessage(`{"path":"/workspace/run.py"}`)
+
+ first, err := tool.Execute(sandboxFileTestContext(), args)
+ require.NoError(t, err)
+ require.True(t, first.Success)
+ assert.Contains(t, first.Output, "DEBUG = 1")
+
+ // Cached: same session, path, size and mtime, and nothing was written.
+ _, err = tool.Execute(sandboxFileTestContext(), args)
+ require.NoError(t, err)
+ assert.Equal(t, 1, source.readCalls)
+
+ // A same-length edit leaves size and mtime untouched, which is exactly the
+ // case stat cannot detect.
+ lockSandboxFile("session-1", "/workspace/run.py")()
+ source.data = []byte("DEBUG = 0")
+
+ third, err := tool.Execute(sandboxFileTestContext(), args)
+ require.NoError(t, err)
+ assert.Equal(t, 2, source.readCalls, "a completed mutation must drop the cache")
+ assert.Contains(t, third.Output, "DEBUG = 0")
+}
+
+// Pages break at line boundaries, which is what makes them UTF-8 safe: 0x0A
+// cannot appear inside a multi-byte sequence, so no byte budget can land
+// mid-rune.
+func TestPaginateSandboxFileNeverSplitsARune(t *testing.T) {
+ var content strings.Builder
+ for i := 0; i < 100; i++ {
+ content.WriteString("这是一行中文文本,用来测试分页边界")
+ content.WriteString("\n")
+ }
+
+ // A budget that lands in the middle of a line, and so inside a rune if the
+ // split were done on raw bytes.
+ page := paginateSandboxFile(content.String(), 1, 0, 55, 1000)
+
+ assert.True(t, utf8.ValidString(page.text))
+ assert.Positive(t, page.nextOffset)
+ assert.True(t, strings.HasSuffix(page.text, "\n"))
+}
+
+// The rune budget binds independently of the byte budget, so ASCII content
+// stops at the rune ceiling even with bytes to spare.
+func TestPaginateSandboxFileHonoursTheRuneBudget(t *testing.T) {
+ content := strings.Repeat(strings.Repeat("a", 100)+"\n", 50)
+
+ page := paginateSandboxFile(content, 1, 0, 1<<20, 250)
+
+ assert.LessOrEqual(t, utf8.RuneCountInString(page.text), 250)
+ assert.Positive(t, page.nextOffset)
+}
+
+// A trailing newline terminates the last line rather than starting an empty
+// one; counting it would report N+1 lines and hand out a blank final page.
+func TestPaginateSandboxFileLineCounting(t *testing.T) {
+ page := paginateSandboxFile("a\nb\nc\n", 0, 0, 1024, 1024)
+ assert.Equal(t, 3, page.totalLines)
+ assert.Equal(t, 1, page.startLine)
+ assert.Equal(t, 3, page.endLine)
+ assert.Zero(t, page.nextOffset)
+ assert.Equal(t, "a\nb\nc\n", page.text)
+
+ // Without a trailing newline the final line still counts.
+ assert.Equal(t, 3, paginateSandboxFile("a\nb\nc", 0, 0, 1024, 1024).totalLines)
+
+ // The line limit ends the page before the byte budget does.
+ limited := paginateSandboxFile("a\nb\nc\n", 1, 2, 1024, 1024)
+ assert.Equal(t, "a\nb\n", limited.text)
+ assert.Equal(t, 3, limited.nextOffset)
+
+ // An offset past the end yields nothing rather than an error.
+ beyond := paginateSandboxFile("a\nb\n", 9, 0, 1024, 1024)
+ assert.Empty(t, beyond.text)
+ assert.Zero(t, beyond.nextOffset)
+}
+
func TestReadSandboxFileReturnsSmallTextOnlyInOutput(t *testing.T) {
content := []byte("hello sandbox\n")
source := &fakeSandboxFileSource{
diff --git a/internal/agent/tools/sandbox_write.go b/internal/agent/tools/sandbox_write.go
index d63165d65..abe433b9d 100644
--- a/internal/agent/tools/sandbox_write.go
+++ b/internal/agent/tools/sandbox_write.go
@@ -27,22 +27,72 @@ import (
"github.com/Tencent/WeKnora/internal/utils"
)
+// maxWriteSandboxBytes is the absolute ceiling on one write. It is a resource
+// guard, not a claim about what the model can emit: the real limit on a single
+// call is the round's completion-token budget, which is usually far smaller.
+// See writeBudgetBytes.
const maxWriteSandboxBytes = 256 * 1024
+// maxSandboxFileBytes bounds the file a sequence of appends can build up. One
+// call still cannot carry more than maxWriteSandboxBytes; this only stops an
+// unbounded append loop from filling the sandbox.
+const maxSandboxFileBytes = 8 * 1024 * 1024
+
+// bytesPerCompletionToken converts the round's completion-token budget into
+// the byte length the model can actually fit in `content`.
+//
+// Deliberately pessimistic. A CJK character is one token and three UTF-8
+// bytes; ASCII source runs three to four bytes per token; JSON string escaping
+// inflates both. Advertising a size the model cannot reach is exactly the
+// failure this replaces — the model plans a 256KB write, gets cut off at the
+// token cap, and retries the same doomed call — so the number must err low.
+const bytesPerCompletionToken = 2
+
+// completionTokensReservedForCall covers everything in the response that is
+// not file content: the tool name, the path, JSON scaffolding, and any prose
+// the model emits before deciding to call the tool.
+const completionTokensReservedForCall = 512
+
+// writeBudgetBytes is the largest `content` a single call can carry given the
+// round's completion-token budget. A non-positive budget means the caller does
+// not know, in which case only the hard cap applies.
+func writeBudgetBytes(completionTokens int) int {
+ if completionTokens <= 0 {
+ return maxWriteSandboxBytes
+ }
+ usable := completionTokens - completionTokensReservedForCall
+ if usable < 1 {
+ usable = 1
+ }
+ return min(usable*bytesPerCompletionToken, maxWriteSandboxBytes)
+}
+
+// Write modes accepted by write_sandbox_file.
+const (
+ writeModeOverwrite = "overwrite"
+ writeModeAppend = "append"
+)
+
// writeSandboxMissingFieldHint is appended when schema validation fails
// (typically a truncated call that only sent `content`).
const writeSandboxMissingFieldHint = "\nIf the previous call was truncated, retry with a complete JSON object: " +
"put `path` first (e.g. /workspace/output/script.py), then `content`. Split large files."
-// SandboxFileSink is the write-side counterpart of SandboxFileSource.
+// SandboxFileSink is the file-store slice write_sandbox_file needs.
// Production uses *sandbox.SessionBoundManager via SessionFileStore.
+//
+// It is not write-only: append mode has to see the file that is already there.
+// The remote backends expose no atomic append, so this reads and rewrites the
+// whole file, which is what edit_sandbox_file already does.
type SandboxFileSink interface {
+ StatSessionFile(ctx context.Context, sessionID, filePath string) (*sandbox.RemoteStatEntry, error)
+ ReadSessionFile(ctx context.Context, sessionID, filePath string) ([]byte, error)
WriteSessionWorkspaceFile(ctx context.Context, sessionID, filePath string, content []byte) error
}
-var writeSandboxFileTool = BaseTool{
- name: ToolWriteSandboxFile,
- description: `Write a text file into the current session's sandbox.
+// writeSandboxFileDescription carries one %s, filled with the size guidance
+// derived from the round's completion-token budget.
+const writeSandboxFileDescription = `Write a text file into the current session's sandbox.
## Usage
- This is the way to create or overwrite a script, report, or other text
@@ -57,18 +107,34 @@ var writeSandboxFileTool = BaseTool{
scripts may live anywhere under ` + "`/workspace`" + ` except
` + "`/workspace/input`" + `.
- JSON arguments MUST include both ` + "`path`" + ` and ` + "`content`" + `.
- Emit ` + "`path`" + ` first. If a write would be huge, split it across
- multiple files instead of one giant ` + "`content`" + ` string.
+ Emit ` + "`path`" + ` first.
- ` + pythonQuoteGuidance + `
+## Large Files: Write In Chunks
+One call carries the whole file body inside its JSON arguments, so a big file
+does not fit in a single response — the output gets cut off mid-string and the
+call is refused. Build it up instead:
+
+1. First chunk: default mode (` + "`mode` omitted or `overwrite`" + `).
+2. Every later chunk: ` + "`mode: \"append\"`" + `, same ` + "`path`" + `.
+
+Keep each chunk to a few hundred lines. Split at a structural boundary (a
+closing tag, the end of a function) so the file is never left mid-token.
+Do NOT resend the earlier chunks — append adds to what is already on disk.
+The result reports the running total so you can tell how much has landed.
+
## When to Use
- Generating a Python/JS/HTML file the sandbox will execute next.
- Saving a long report or config that does not fit in a shell command.
- Overwriting a file you previously wrote in this session.
+- Continuing a file you are writing in chunks (` + "`mode: \"append\"`" + `).
## When NOT to Use
- To change a few lines of a file you already wrote, call
` + "`edit_sandbox_file`" + ` instead of sending the whole file again.
+- To recover from a truncated write: append the missing tail, or fix the
+ break with ` + "`edit_sandbox_file`" + `. Rewriting the whole file from the
+ top will truncate again at the same place.
- Do not write under ` + "`/workspace/input`" + `: that tree is reserved for
user-uploaded attachments and is read-only.
- Do not write binary bytes. Have a script produce binary artifacts under
@@ -80,17 +146,21 @@ var writeSandboxFileTool = BaseTool{
themselves are directories and cannot be used as the file path.
## Size Handling
-- Content is capped at 262144 bytes per call.
+- %s
## Returns
-- The absolute path and byte count. File contents are not echoed back.`,
- schema: utils.GenerateSchema[WriteSandboxFileInput](),
-}
+- The absolute path and the file's total byte count (for an append, also how
+ many bytes this call added). File contents are not echoed back.`
// WriteSandboxFileInput defines the input parameters for write_sandbox_file.
+//
+// The byte limit is deliberately absent from the `content` description: it
+// depends on the agent's per-round token budget and is stated in the tool
+// description, which is built per session.
type WriteSandboxFileInput struct {
Path string `json:"path" jsonschema:"Absolute sandbox path to write. Must sit under /workspace and must not sit under /workspace/input. Prefer /workspace/output for downloadable artifacts."`
- Content string `json:"content" jsonschema:"Full text contents of the file. Overwrites any existing file at path. Maximum 262144 bytes. Do not send binary bytes."`
+ Content string `json:"content" jsonschema:"Text to write. In overwrite mode this is the full file; in append mode it is only the next chunk. Keep near the per-call size stated in the tool description so the response is not cut off. Do not send binary bytes."` //nolint:lll // one-line struct tag
+ Mode string `json:"mode,omitempty" jsonschema:"How to apply content: 'overwrite' (default) replaces the file, 'append' adds to the end of an existing file. Use append to build a large file across several calls."` //nolint:lll // one-line struct tag
}
// WriteSandboxFileTool writes a text file into the session sandbox.
@@ -100,13 +170,49 @@ type WriteSandboxFileTool struct {
}
// NewWriteSandboxFileTool constructs the tool. `sink` MUST NOT be nil.
-func NewWriteSandboxFileTool(sink SandboxFileSink) *WriteSandboxFileTool {
+//
+// completionTokens is the agent's per-round completion-token budget, which is
+// what actually bounds how much the model can emit in one call. It shapes the
+// size guidance in the description; it is not enforced, for the reasons in
+// Execute. Pass 0 when it is not known.
+func NewWriteSandboxFileTool(sink SandboxFileSink, completionTokens int) *WriteSandboxFileTool {
return &WriteSandboxFileTool{
- BaseTool: writeSandboxFileTool,
- sink: sink,
+ BaseTool: BaseTool{
+ name: ToolWriteSandboxFile,
+ description: fmt.Sprintf(
+ writeSandboxFileDescription,
+ writeSizeGuidance(writeBudgetBytes(completionTokens)),
+ ),
+ schema: utils.GenerateSchema[WriteSandboxFileInput](),
+ },
+ sink: sink,
}
}
+// writeSizeGuidance states how much content one call should carry and why.
+//
+// The number is a forecast of what fits in one response, not a rule the tool
+// enforces — a call that lands intact is written whatever its size. The reason
+// to respect it is the real one: go far past it and the response gets cut off
+// mid-string, and a truncated call is refused before it ever reaches the tool.
+// A model told only a number treats it as arbitrary; told that its own response
+// length is the constraint, it splits the file instead of retrying.
+func writeSizeGuidance(maxBytes int) string {
+ if maxBytes >= maxWriteSandboxBytes {
+ return fmt.Sprintf(
+ "Keep `content` under about %d bytes per call. A larger file must be built "+
+ "with `mode: \"append\"`. The whole file is capped at %d bytes.",
+ maxBytes, maxSandboxFileBytes)
+ }
+ return fmt.Sprintf(
+ "Keep `content` under about %d bytes per call, because that is what fits in one "+
+ "response at this agent's token budget. Go much past it and the response is cut "+
+ "off mid-string, which makes the call unusable and it will be refused. Split "+
+ "anything longer across several calls with `mode: \"append\"`. The whole file is "+
+ "capped at %d bytes.",
+ maxBytes, maxSandboxFileBytes)
+}
+
// Execute writes the requested file into the current session's sandbox.
func (t *WriteSandboxFileTool) Execute(ctx context.Context, args json.RawMessage) (*types.ToolResult, error) {
logger.Infof(ctx, "[Tool][WriteSandboxFile] Execute started")
@@ -151,23 +257,66 @@ func (t *WriteSandboxFileTool) Execute(ctx context.Context, args json.RawMessage
}, nil
}
- content := []byte(input.Content)
- if len(content) > maxWriteSandboxBytes {
+ // Only the file-size limit is enforced here, deliberately not the per-call
+ // budget the description advertises.
+ //
+ // That budget is a forecast of what fits in one response, derived from
+ // token math whose bytes-per-token factor swings by 3x between ASCII and
+ // CJK. Content that reaches this point already arrived intact — a response
+ // cut off at the token cap was refused in act.go, and arguments closed by
+ // JSON repair were refused there too. Rejecting a complete payload for
+ // beating a wrong forecast discards work already paid for and forces the
+ // model to re-emit it in chunks, which costs strictly more and is more
+ // likely to truncate than the call that just succeeded. Nor would the check
+ // catch what it looks like it catches: a truncated write is usually SMALLER
+ // than the budget and passes straight through.
+ chunk := []byte(input.Content)
+ if len(chunk) > maxSandboxFileBytes {
return &types.ToolResult{
Success: false,
Error: fmt.Sprintf(
- "content too large (%d bytes; max %d). Split the work across files or shrink the script",
- len(content), maxWriteSandboxBytes,
+ "content is %d bytes, past the %d-byte file limit. Write the first part now "+
+ "and send the rest with mode=%q",
+ len(chunk), maxSandboxFileBytes, writeModeAppend,
),
}, nil
}
- if isBinaryShellOutput(string(content)) {
+ if isBinaryShellOutput(string(chunk)) {
return &types.ToolResult{
Success: false,
Error: "binary content is not accepted; write a text script and have it produce binary files under /workspace/output",
}, nil
}
+ mode, modeErr := normalizeWriteMode(input.Mode)
+ if modeErr != "" {
+ return &types.ToolResult{Success: false, Error: modeErr}, nil
+ }
+
+ // Held across the read and the write: an append that reads its base while
+ // a sibling call is mid-write appends to bytes that no longer exist.
+ defer lockSandboxFile(sessionID, clean)()
+
+ content := chunk
+ if mode == writeModeAppend {
+ existing, appendErr := t.readForAppend(ctx, sessionID, clean)
+ if appendErr != "" {
+ return &types.ToolResult{Success: false, Error: appendErr}, nil
+ }
+ if len(existing)+len(chunk) > maxSandboxFileBytes {
+ return &types.ToolResult{
+ Success: false,
+ Error: fmt.Sprintf(
+ "appending %d bytes would take %s past the %d-byte file limit (currently %d)",
+ len(chunk), clean, maxSandboxFileBytes, len(existing),
+ ),
+ }, nil
+ }
+ content = make([]byte, 0, len(existing)+len(chunk))
+ content = append(content, existing...)
+ content = append(content, chunk...)
+ }
+
if err := t.sink.WriteSessionWorkspaceFile(ctx, sessionID, clean, content); err != nil {
logger.Warnf(ctx, "[Tool][WriteSandboxFile] write failed: session=%s path=%s err=%v",
sessionID, clean, err)
@@ -177,10 +326,12 @@ func (t *WriteSandboxFileTool) Execute(ctx context.Context, args json.RawMessage
}, nil
}
- logger.Infof(ctx, "[Tool][WriteSandboxFile] session=%s path=%s bytes=%d",
- sessionID, clean, len(content))
+ logger.Infof(ctx, "[Tool][WriteSandboxFile] session=%s path=%s mode=%s chunk_bytes=%d total_bytes=%d",
+ sessionID, clean, mode, len(chunk), len(content))
- if hint := pythonScriptSyntaxHint(clean, input.Content, ToolEditSandboxFile); hint != "" {
+ // Check the whole file, not just this chunk: a chunk boundary lands in the
+ // middle of the source, so only the assembled result can be judged.
+ if hint := pythonScriptSyntaxHint(clean, string(content), ToolEditSandboxFile); hint != "" {
return &types.ToolResult{
Success: false,
Error: hint,
@@ -192,19 +343,24 @@ func (t *WriteSandboxFileTool) Execute(ctx context.Context, args json.RawMessage
"root": rootDir,
"name": path.Base(clean),
"size": len(content),
+ "mode": mode,
"syntax_error": true,
},
}, nil
}
+ sizeLine := fmt.Sprintf("bytes=%d", len(content))
+ if mode == writeModeAppend {
+ sizeLine = fmt.Sprintf("appended=%d, total_bytes=%d", len(chunk), len(content))
+ }
output := fmt.Sprintf(
- "=== Wrote sandbox file: %s ===\n\nbytes=%d\n\n"+
+ "=== Wrote sandbox file: %s ===\n\n%s\n\n"+
"If this script needs a skill's packages, run it with\n"+
"execute_skill_script(skill_name=<skill>, script_path=%s)\n"+
"so the skill's virtualenv is used. Independent scripts:\n"+
"shell_exec python3 %s\n\n"+
"User-facing artifacts should land under %s.\n",
- clean, len(content), clean, clean, sandbox.SessionOutputRoot,
+ clean, sizeLine, clean, clean, sandbox.SessionOutputRoot,
)
return &types.ToolResult{
Success: true,
@@ -216,10 +372,50 @@ func (t *WriteSandboxFileTool) Execute(ctx context.Context, args json.RawMessage
"root": rootDir,
"name": path.Base(clean),
"size": len(content),
+ "mode": mode,
+ "appended": len(chunk),
},
}, nil
}
+// normalizeWriteMode resolves the requested mode, returning a message for the
+// model when it is not one this tool knows.
+func normalizeWriteMode(requested string) (string, string) {
+ switch strings.ToLower(strings.TrimSpace(requested)) {
+ case "", writeModeOverwrite:
+ return writeModeOverwrite, ""
+ case writeModeAppend:
+ return writeModeAppend, ""
+ default:
+ return "", fmt.Sprintf("unknown mode %q; use %q (default) or %q",
+ requested, writeModeOverwrite, writeModeAppend)
+ }
+}
+
+// readForAppend returns the bytes an append must be added to. A missing file
+// is refused rather than quietly created: a stat or read that fails for any
+// other reason is indistinguishable from "not there yet", and creating the
+// file would drop everything written so far. Failing tells the model exactly
+// which call to repeat.
+func (t *WriteSandboxFileTool) readForAppend(
+ ctx context.Context, sessionID, filePath string,
+) ([]byte, string) {
+ stat, err := t.sink.StatSessionFile(ctx, sessionID, filePath)
+ if err != nil || stat == nil {
+ return nil, fmt.Sprintf(
+ "cannot append to %s: it does not exist yet (%v). Write the first chunk with mode=%q, then append the rest",
+ filePath, err, writeModeOverwrite)
+ }
+ if stat.Type != sandbox.RemoteEntryFile {
+ return nil, fmt.Sprintf("cannot append to %s: it is not a regular file", filePath)
+ }
+ existing, err := t.sink.ReadSessionFile(ctx, sessionID, filePath)
+ if err != nil {
+ return nil, fmt.Sprintf("cannot append to %s: reading the current contents failed: %v", filePath, err)
+ }
+ return existing, ""
+}
+
// Cleanup releases any resources.
func (t *WriteSandboxFileTool) Cleanup(ctx context.Context) error {
return nil
diff --git a/internal/agent/tools/sandbox_write_test.go b/internal/agent/tools/sandbox_write_test.go
index 65425792e..700001435 100644
--- a/internal/agent/tools/sandbox_write_test.go
+++ b/internal/agent/tools/sandbox_write_test.go
@@ -3,6 +3,7 @@ package tools
import (
"context"
"encoding/json"
+ "fmt"
"strings"
"testing"
@@ -16,13 +17,50 @@ type fakeSandboxFileSink struct {
content []byte
err error
calls int
+ // files backs stat/read so append tests can build a file across calls.
+ files map[string][]byte
+ statErr error
+ readErr error
}
func (f *fakeSandboxFileSink) WriteSessionWorkspaceFile(_ context.Context, _, filePath string, content []byte) error {
f.calls++
f.path = filePath
f.content = append([]byte(nil), content...)
- return f.err
+ if f.err != nil {
+ return f.err
+ }
+ if f.files == nil {
+ f.files = map[string][]byte{}
+ }
+ f.files[filePath] = append([]byte(nil), content...)
+ return nil
+}
+
+func (f *fakeSandboxFileSink) StatSessionFile(
+ _ context.Context, _, filePath string,
+) (*sandbox.RemoteStatEntry, error) {
+ if f.statErr != nil {
+ return nil, f.statErr
+ }
+ data, ok := f.files[filePath]
+ if !ok {
+ return nil, fmt.Errorf("no such file: %s", filePath)
+ }
+ return &sandbox.RemoteStatEntry{
+ Path: filePath, Type: sandbox.RemoteEntryFile, Size: int64(len(data)),
+ }, nil
+}
+
+func (f *fakeSandboxFileSink) ReadSessionFile(_ context.Context, _, filePath string) ([]byte, error) {
+ if f.readErr != nil {
+ return nil, f.readErr
+ }
+ data, ok := f.files[filePath]
+ if !ok {
+ return nil, fmt.Errorf("no such file: %s", filePath)
+ }
+ return append([]byte(nil), data...), nil
}
func TestWriteSandboxFileWritesTextUnderOutput(t *testing.T) {
@@ -30,7 +68,7 @@ func TestWriteSandboxFileWritesTextUnderOutput(t *testing.T) {
require.Greater(t, len(script), 8*1024)
sink := &fakeSandboxFileSink{}
- result, err := NewWriteSandboxFileTool(sink).Execute(
+ result, err := NewWriteSandboxFileTool(sink, 0).Execute(
sandboxFileTestContext(),
mustWriteSandboxArgs("/workspace/output/generate_ppt.py", script),
)
@@ -52,7 +90,7 @@ func TestWriteSandboxFileWritesTextUnderOutput(t *testing.T) {
func TestWriteSandboxFileFlagsNestedPythonQuotes(t *testing.T) {
script := "slides = [(\"这不是一个\"大干快上\"的夜晚\", False)]\n"
sink := &fakeSandboxFileSink{}
- result, err := NewWriteSandboxFileTool(sink).Execute(
+ result, err := NewWriteSandboxFileTool(sink, 0).Execute(
sandboxFileTestContext(),
mustWriteSandboxArgs("/workspace/output/generate_fortune_ppt.py", script),
)
@@ -67,7 +105,7 @@ func TestWriteSandboxFileFlagsNestedPythonQuotes(t *testing.T) {
func TestWriteSandboxFileAllowsWorkspaceScratch(t *testing.T) {
sink := &fakeSandboxFileSink{}
- result, err := NewWriteSandboxFileTool(sink).Execute(
+ result, err := NewWriteSandboxFileTool(sink, 0).Execute(
sandboxFileTestContext(),
mustWriteSandboxArgs("/workspace/scratch.py", "print(1)\n"),
)
@@ -80,7 +118,7 @@ func TestWriteSandboxFileAllowsWorkspaceScratch(t *testing.T) {
func TestWriteSandboxFileRefusesSessionInput(t *testing.T) {
sink := &fakeSandboxFileSink{}
- result, err := NewWriteSandboxFileTool(sink).Execute(
+ result, err := NewWriteSandboxFileTool(sink, 0).Execute(
sandboxFileTestContext(),
mustWriteSandboxArgs("/workspace/input/secret.txt", "nope"),
)
@@ -95,7 +133,7 @@ func TestWriteSandboxFileRefusesSessionInput(t *testing.T) {
func TestWriteSandboxFileRefusesDirectoryPaths(t *testing.T) {
sink := &fakeSandboxFileSink{}
for _, p := range []string{"/workspace", "/workspace/output", "/workspace/input"} {
- result, err := NewWriteSandboxFileTool(sink).Execute(
+ result, err := NewWriteSandboxFileTool(sink, 0).Execute(
sandboxFileTestContext(),
mustWriteSandboxArgs(p, "nope"),
)
@@ -108,7 +146,7 @@ func TestWriteSandboxFileRefusesDirectoryPaths(t *testing.T) {
func TestWriteSandboxFileRefusesBinaryAndOversize(t *testing.T) {
sink := &fakeSandboxFileSink{}
- binary, err := NewWriteSandboxFileTool(sink).Execute(
+ binary, err := NewWriteSandboxFileTool(sink, 0).Execute(
sandboxFileTestContext(),
mustWriteSandboxArgs("/workspace/output/x.bin", "pre\x00post"),
)
@@ -116,19 +154,154 @@ func TestWriteSandboxFileRefusesBinaryAndOversize(t *testing.T) {
require.False(t, binary.Success)
assert.Contains(t, binary.Error, "binary")
- oversize, err := NewWriteSandboxFileTool(sink).Execute(
+ // The file-size limit is a real resource bound, so it is enforced on the
+ // overwrite path too, not only when appending.
+ oversize, err := NewWriteSandboxFileTool(sink, 0).Execute(
sandboxFileTestContext(),
- mustWriteSandboxArgs("/workspace/output/big.py", strings.Repeat("a", maxWriteSandboxBytes+1)),
+ mustWriteSandboxArgs("/workspace/output/big.py", strings.Repeat("a", maxSandboxFileBytes+1)),
)
require.NoError(t, err)
require.False(t, oversize.Success)
- assert.Contains(t, oversize.Error, "too large")
+ assert.Contains(t, oversize.Error, "file limit")
assert.Zero(t, sink.calls)
}
+// The advertised limit has to track the agent's token budget. A tenant that
+// sets a small max_completion_tokens used to be told it could write 262144
+// bytes; the model planned for that, got cut off, and retried the identical
+// call forever.
+func TestWriteSandboxBudgetFollowsCompletionTokens(t *testing.T) {
+ // Unknown budget falls back to the hard cap and nothing else.
+ assert.Equal(t, maxWriteSandboxBytes, writeBudgetBytes(0))
+
+ // A budget large enough to reach the hard cap is clamped by it.
+ assert.Equal(t, maxWriteSandboxBytes, writeBudgetBytes(1_000_000))
+
+ // A small budget produces a proportionally small cap.
+ small := writeBudgetBytes(8192)
+ assert.Equal(t, (8192-completionTokensReservedForCall)*bytesPerCompletionToken, small)
+ assert.Less(t, small, maxWriteSandboxBytes)
+
+ // A budget smaller than the per-call reservation still leaves room to
+ // write something, so the model gets an actionable limit rather than 0.
+ assert.Positive(t, writeBudgetBytes(16))
+}
+
+// When the budget is the binding constraint the model must be told *why*,
+// otherwise it reads the number as arbitrary and argues with it.
+func TestWriteSandboxDescriptionExplainsABudgetDerivedLimit(t *testing.T) {
+ budgeted := NewWriteSandboxFileTool(&fakeSandboxFileSink{}, 8192).Description()
+ assert.Contains(t, budgeted, "token budget")
+ assert.Contains(t, budgeted, "append")
+ assert.NotContains(t, budgeted, "262144",
+ "the hard cap is not what bounds this agent, so quoting it would mislead")
+
+ uncapped := NewWriteSandboxFileTool(&fakeSandboxFileSink{}, 0).Description()
+ assert.Contains(t, uncapped, "262144")
+}
+
+// The advertised budget is a forecast, not a rule. Content that arrived intact
+// beat the forecast, which means the forecast was wrong — its bytes-per-token
+// factor swings by 3x between ASCII and CJK. Rejecting it would discard work
+// already paid for in tokens and force the model to re-emit the same bytes in
+// chunks, which costs more and is likelier to truncate than the call that just
+// succeeded. The genuinely truncated cases are refused in act.go, before the
+// tool ever runs.
+func TestWriteSandboxAcceptsContentOverTheAdvertisedBudget(t *testing.T) {
+ sink := &fakeSandboxFileSink{}
+ budget := writeBudgetBytes(8192)
+ content := strings.Repeat("a", budget+1)
+
+ result, err := NewWriteSandboxFileTool(sink, 8192).Execute(
+ sandboxFileTestContext(),
+ mustWriteSandboxArgs("/workspace/output/big.html", content),
+ )
+
+ require.NoError(t, err)
+ require.True(t, result.Success, result.Error)
+ assert.Equal(t, 1, sink.calls)
+ assert.Equal(t, content, string(sink.files["/workspace/output/big.html"]))
+}
+
+// The whole point of append: a file too large to fit in one response gets
+// built across calls, and later chunks must not resend what already landed.
+func TestWriteSandboxFileAppendBuildsFileAcrossCalls(t *testing.T) {
+ const path = "/workspace/output/deck.html"
+ sink := &fakeSandboxFileSink{}
+ tool := NewWriteSandboxFileTool(sink, 0)
+
+ first, err := tool.Execute(sandboxFileTestContext(), mustWriteSandboxArgs(path, "<html><body>"))
+ require.NoError(t, err)
+ require.True(t, first.Success, first.Error)
+
+ second, err := tool.Execute(sandboxFileTestContext(), json.RawMessage(
+ `{"path":"`+path+`","content":"<h1>hi</h1>","mode":"append"}`,
+ ))
+ require.NoError(t, err)
+ require.True(t, second.Success, second.Error)
+
+ third, err := tool.Execute(sandboxFileTestContext(), json.RawMessage(
+ `{"path":"`+path+`","content":"</body></html>","mode":"append"}`,
+ ))
+ require.NoError(t, err)
+ require.True(t, third.Success, third.Error)
+
+ assert.Equal(t, "<html><body><h1>hi</h1></body></html>", string(sink.files[path]))
+ // The running total is how the model knows how much has landed.
+ assert.Equal(t, len("<html><body><h1>hi</h1></body></html>"), third.Data["size"])
+ assert.Equal(t, len("</body></html>"), third.Data["appended"])
+ assert.Contains(t, third.Output, "total_bytes=")
+}
+
+// Appending to a file that is not there would silently drop every earlier
+// chunk, so it fails and names the mode to use for the first one instead.
+func TestWriteSandboxFileAppendRefusesMissingFile(t *testing.T) {
+ sink := &fakeSandboxFileSink{}
+ result, err := NewWriteSandboxFileTool(sink, 0).Execute(sandboxFileTestContext(), json.RawMessage(
+ `{"path":"/workspace/output/absent.html","content":"tail","mode":"append"}`,
+ ))
+
+ require.NoError(t, err)
+ require.False(t, result.Success)
+ assert.Zero(t, sink.calls)
+ assert.Contains(t, result.Error, "does not exist yet")
+ assert.Contains(t, result.Error, "overwrite")
+}
+
+func TestWriteSandboxFileRejectsUnknownMode(t *testing.T) {
+ sink := &fakeSandboxFileSink{}
+ result, err := NewWriteSandboxFileTool(sink, 0).Execute(sandboxFileTestContext(), json.RawMessage(
+ `{"path":"/workspace/output/a.txt","content":"x","mode":"prepend"}`,
+ ))
+
+ require.NoError(t, err)
+ require.False(t, result.Success)
+ assert.Zero(t, sink.calls)
+ assert.Contains(t, result.Error, "unknown mode")
+}
+
+// A chunk boundary lands mid-source, so the syntax check has to look at the
+// assembled file — judging the chunk alone would flag every valid split.
+func TestWriteSandboxFileAppendChecksSyntaxOfWholeFile(t *testing.T) {
+ const path = "/workspace/output/gen.py"
+ sink := &fakeSandboxFileSink{}
+ tool := NewWriteSandboxFileTool(sink, 0)
+
+ first, err := tool.Execute(sandboxFileTestContext(), mustWriteSandboxArgs(path, "title = \"这不是一个\""))
+ require.NoError(t, err)
+ require.True(t, first.Success, first.Error)
+
+ second, err := tool.Execute(sandboxFileTestContext(), json.RawMessage(
+ `{"path":"`+path+`","content":"大干快上\"的夜晚\"\n","mode":"append"}`,
+ ))
+ require.NoError(t, err)
+ require.False(t, second.Success, "the assembled file has the broken-quote pattern")
+ assert.Equal(t, true, second.Data["syntax_error"])
+}
+
func TestWriteSandboxFileRegistryHintsWhenPathMissing(t *testing.T) {
registry := NewToolRegistry()
- registry.RegisterTool(NewWriteSandboxFileTool(&fakeSandboxFileSink{}))
+ registry.RegisterTool(NewWriteSandboxFileTool(&fakeSandboxFileSink{}, 0))
result, err := registry.ExecuteTool(
sandboxFileTestContext(),
diff --git a/internal/agent/tools/shell_exec.go b/internal/agent/tools/shell_exec.go
index 0b37cdb9c..96b9940ff 100644
--- a/internal/agent/tools/shell_exec.go
+++ b/internal/agent/tools/shell_exec.go
@@ -155,6 +155,9 @@ var shellExecTool = BaseTool{
never into ` + "`/opt/weknora/tenant/skills`" + `. The skill venv is frozen after
install. ` + "`apt-get`" + ` is only for a system library this task actually needs,
not to recover from probing with a missing inspection command.
+- The sandbox is one long-lived session: files written and packages installed by
+ an earlier call are still there for later ` + "`shell_exec`" + ` and
+ ` + "`execute_skill_script`" + ` calls. Do not redo setup you already did.
## When to Use
- Whenever executing a command is the most direct way to complete the task.
@@ -163,13 +166,17 @@ var shellExecTool = BaseTool{
intermediate files for later commands or skills.
## When NOT to Use
-- DO NOT judge a skill's dependencies with a bare ` + "`python3 -c`" + ` or
- ` + "`node -e`" + `, and do NOT inspect a skill-generated docx/pptx/xlsx that way
- either: system ` + "`python3`" + ` has none of the skill's packages (` + "`docx`" + `,
- ` + "`pptx`" + `, pandas, …). Do not ` + "`pip install`" + ` them here, and do not
- paste the same program into ` + "`.venv/bin/python -c`" + `. Write the script
- with ` + "`write_sandbox_file`" + ` and run it with
- ` + "`execute_skill_script(skill_name=..., script_path=/workspace/output/... )`" + `.
+- DO NOT run ANY script that needs a skill's packages (` + "`docx`" + `,
+ ` + "`pptx`" + `, pandas, …) from here — generating a file counts, not just
+ inspecting one. System ` + "`python3`" + ` has none of them. Write the script with
+ ` + "`write_sandbox_file`" + ` and run it with
+ ` + "`execute_skill_script(skill_name=..., script_path=/workspace/output/... )`" + `,
+ which uses the skill's own interpreter and sets ` + "`PYTHONPATH`" + ` / ` + "`NODE_PATH`" + `
+ for you. Do NOT wire that environment by hand
+ (` + "`PYTHONPATH=... python3 script.py`" + `, or calling ` + "`.venv/bin/python`" + `
+ directly): the skill's interpreter already carries what was installed with it,
+ so the hand-wired version just makes you reinstall it. Also do not judge a
+ skill's dependencies with a bare ` + "`python3 -c`" + ` / ` + "`node -e`" + `.
` + "`read_skill`" + ` names the skill and how to reach its environment.
- DO NOT ` + "`chown`" + ` / ` + "`chmod`" + ` / ` + "`ensurepip`" + ` / ` + "`pip install`" + ` a skill
under ` + "`/opt/weknora/tenant/skills`" + `. That tree is read-only after install
@@ -193,7 +200,9 @@ var shellExecTool = BaseTool{
- ` + "`command`" + ` (required): the shell one-liner to run under ` + "`/bin/bash -l -c`" + `.
Supports pipes, redirects, ` + "`&&`" + ` / ` + "`||`" + ` chaining. Keep this short;
large scripts go through ` + "`write_sandbox_file`" + `; small edits go through
- ` + "`edit_sandbox_file`" + `.
+ ` + "`edit_sandbox_file`" + `. Watch the quoting: never nest an ASCII
+ ` + "`\"`" + ` inside ` + "`\"...\"`" + ` (or ` + "`'`" + ` inside ` + "`'...'`" + `) —
+ use the other quote, and 「」 for Chinese quotation marks.
- ` + "`work_dir`" + ` (optional): an absolute path under ` + "`/workspace`" + `,
defaulting to ` + "`/workspace`" + ` itself — omit it unless the command has to
run in another directory. Created on demand if it doesn't exist.
diff --git a/internal/agent/tools/shell_exec_test.go b/internal/agent/tools/shell_exec_test.go
index 94356fd95..069ea5043 100644
--- a/internal/agent/tools/shell_exec_test.go
+++ b/internal/agent/tools/shell_exec_test.go
@@ -234,6 +234,33 @@ func TestShellExecDescriptionSupportsGeneralExploration(t *testing.T) {
assert.NotContains(t, description, "If a 'command not found' error occurs, attempt to resolve it")
}
+// The system prompt used to repeat all of this in its shell_exec bullets. The
+// description ships with the tools on every request, so the second copy only
+// spent tokens twice and gave the two wordings room to drift. It was deleted
+// there (TestFormatSkillsMetadataIncludesShellGuidanceOnlyWhenEnabled asserts
+// it stays deleted), which makes this the only copy left.
+func TestShellExecDescriptionOwnsItsMechanics(t *testing.T) {
+ description := NewShellExecTool(&fakeShellExecutor{}, nil).Description()
+
+ for _, mechanic := range []string{
+ // Working directory, and why `cd /workspace &&` is dead weight.
+ "Every command already starts in",
+ "do NOT prefix",
+ "work_dir",
+ // Output budget and how a non-zero exit is meant to be read.
+ "max_output_bytes",
+ "non-zero on failure",
+ "is NOT a tool",
+ // Quoting, which decides whether a one-liner even parses.
+ "never nest an ASCII",
+ "「」",
+ // Session lifetime, so setup is not redone every call.
+ "one long-lived session",
+ } {
+ assert.Contains(t, description, mechanic, "moved out of the system prompt, must live here")
+ }
+}
+
func TestShellExecBoundsStdoutStderrErrorAndTotal(t *testing.T) {
executor := &fakeShellExecutor{result: &sandbox.ExecuteResult{
Stdout: strings.Repeat("o", 100*1024),
diff --git a/internal/agent/tools/skill_file.go b/internal/agent/tools/skill_file.go
index e375a00a9..3999d0e5c 100644
--- a/internal/agent/tools/skill_file.go
+++ b/internal/agent/tools/skill_file.go
@@ -312,8 +312,11 @@ func (t *EditSkillFileTool) Execute(ctx context.Context, args json.RawMessage) (
}, nil
}
- updated, replacements, err := applySandboxEdit(
- string(raw), input.OldString, input.NewString, input.ReplaceAll)
+ updated, replacements, err := applySandboxEdits(string(raw), []SandboxEdit{{
+ OldString: input.OldString,
+ NewString: input.NewString,
+ ReplaceAll: input.ReplaceAll,
+ }})
if err != nil {
return &types.ToolResult{Success: false, Error: err.Error()}, nil
}
diff --git a/internal/agent/tools/skill_file_tree_test.go b/internal/agent/tools/skill_file_tree_test.go
new file mode 100644
index 000000000..f7f8e3eb8
--- /dev/null
+++ b/internal/agent/tools/skill_file_tree_test.go
@@ -0,0 +1,70 @@
+package tools
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestFormatSkillFileTreeIndentsSharedDirectories(t *testing.T) {
+ t.Parallel()
+
+ got := formatSkillFileTree([]string{
+ "SKILL.md",
+ "LICENSE",
+ "scripts/generate_ppt.py",
+ "scripts/helpers/layout.py",
+ "docs/guide.md",
+ "scripts/office/validate.py",
+ })
+
+ want := strings.Join([]string{
+ "docs/",
+ " guide.md",
+ "scripts/",
+ " helpers/",
+ " layout.py",
+ " office/",
+ " validate.py",
+ " generate_ppt.py",
+ "LICENSE",
+ "",
+ }, "\n")
+ assert.Equal(t, want, got)
+
+ // The prefix is paid once; the old bullet list repeated `scripts/` on
+ // every line plus backticks and "(script - can be executed)".
+ assert.Equal(t, 1, strings.Count(got, "scripts/"))
+ assert.NotContains(t, got, "`")
+ assert.NotContains(t, got, "can be executed")
+}
+
+func TestFormatSkillFileTreeSkipsInstallAndCacheTrees(t *testing.T) {
+ t.Parallel()
+
+ got := formatSkillFileTree([]string{
+ "scripts/run.py",
+ ".venv/bin/python",
+ ".venv/lib/site.py",
+ "node_modules/pptx/index.js",
+ "scripts/__pycache__/run.cpython-312.pyc",
+ ".git/HEAD",
+ })
+ assert.Equal(t, "scripts/\n run.py\n", got)
+}
+
+func TestFormatSkillFileTreeEmptyWhenOnlySkillMd(t *testing.T) {
+ t.Parallel()
+
+ assert.Empty(t, formatSkillFileTree(nil))
+ assert.Empty(t, formatSkillFileTree([]string{"SKILL.md", "", "/"}))
+}
+
+func TestFormatSkillFileTreeAcceptsWindowsSeparators(t *testing.T) {
+ t.Parallel()
+
+ got := formatSkillFileTree([]string{`scripts\office\validate.py`})
+ require.Equal(t, "scripts/\n office/\n validate.py\n", got)
+}
diff --git a/internal/agent/tools/skill_read.go b/internal/agent/tools/skill_read.go
index b80a0879f..592f60389 100644
--- a/internal/agent/tools/skill_read.go
+++ b/internal/agent/tools/skill_read.go
@@ -5,6 +5,7 @@ import (
"encoding/json"
"fmt"
"path"
+ "sort"
"strings"
"github.com/Tencent/WeKnora/internal/agent/skills"
@@ -155,19 +156,10 @@ func (t *ReadSkillTool) Execute(ctx context.Context, args json.RawMessage) (*typ
builder.WriteString("## Instructions\n\n")
builder.WriteString(skill.Instructions)
- // Add available files section
- if len(files) > 1 { // More than just SKILL.md
- builder.WriteString("\n\n## Available Files\n\n")
- builder.WriteString("The following files are available in this skill directory. Use `read_skill` with `file_path` to read them (relative paths, e.g. scripts/foo.py). Do not list the skill directory with `list_sandbox_files` or `ls`:\n\n")
- for _, file := range files {
- if file != skills.SkillFileName { // Don't list SKILL.md again
- if skills.IsScript(file) {
- builder.WriteString(fmt.Sprintf("- `%s` (script - can be executed)\n", file))
- } else {
- builder.WriteString(fmt.Sprintf("- `%s`\n", file))
- }
- }
- }
+ if tree := formatSkillFileTree(files); tree != "" {
+ builder.WriteString("\n\n## Files\n\n")
+ builder.WriteString("Join the tree for `file_path` (relative to the skill root):\n\n")
+ builder.WriteString(tree)
}
resultData["skill_name"] = skill.Name
@@ -192,6 +184,89 @@ func (t *ReadSkillTool) Execute(ctx context.Context, args json.RawMessage) (*typ
}, nil
}
+// skillTreeSkipDirs are install/cache trees that walk the skill root but are
+// not something the model should open. Listing them as a flat bullet list
+// (or even as a tree) would dump thousands of paths into the turn.
+var skillTreeSkipDirs = map[string]struct{}{
+ ".venv": {},
+ "node_modules": {},
+ "__pycache__": {},
+ ".git": {},
+}
+
+type skillTreeNode struct {
+ children map[string]*skillTreeNode
+}
+
+// formatSkillFileTree renders the skill's files as an indented tree so each
+// directory name is paid for once. Box-drawing `tree` characters are skipped
+// on purpose: they cost tokens and are not part of file_path.
+func formatSkillFileTree(files []string) string {
+ root := &skillTreeNode{children: map[string]*skillTreeNode{}}
+ for _, raw := range files {
+ rel := strings.Trim(strings.ReplaceAll(raw, "\\", "/"), "/")
+ if rel == "" || rel == skills.SkillFileName {
+ continue
+ }
+ parts := strings.Split(rel, "/")
+ skip := false
+ for _, part := range parts {
+ if _, junk := skillTreeSkipDirs[part]; junk {
+ skip = true
+ break
+ }
+ }
+ if skip {
+ continue
+ }
+ n := root
+ for _, part := range parts {
+ if n.children == nil {
+ n.children = map[string]*skillTreeNode{}
+ }
+ child := n.children[part]
+ if child == nil {
+ child = &skillTreeNode{}
+ n.children[part] = child
+ }
+ n = child
+ }
+ }
+ if len(root.children) == 0 {
+ return ""
+ }
+ var b strings.Builder
+ writeSkillFileTree(&b, root, "")
+ return b.String()
+}
+
+func writeSkillFileTree(b *strings.Builder, n *skillTreeNode, indent string) {
+ names := make([]string, 0, len(n.children))
+ for name := range n.children {
+ names = append(names, name)
+ }
+ sort.Slice(names, func(i, j int) bool {
+ left, right := n.children[names[i]], n.children[names[j]]
+ leftDir, rightDir := len(left.children) > 0, len(right.children) > 0
+ if leftDir != rightDir {
+ return leftDir
+ }
+ return names[i] < names[j]
+ })
+ for _, name := range names {
+ child := n.children[name]
+ b.WriteString(indent)
+ b.WriteString(name)
+ if len(child.children) > 0 {
+ b.WriteByte('/')
+ b.WriteByte('\n')
+ writeSkillFileTree(b, child, indent+" ")
+ continue
+ }
+ b.WriteByte('\n')
+ }
+}
+
// skillEnvironmentSection tells the model where the skill's dependencies are.
//
// Every skill keeps its dependencies to itself — Python in its own virtualenv,
diff --git a/internal/application/service/agent_service.go b/internal/application/service/agent_service.go
index 85d72b758..13a6095b2 100644
--- a/internal/application/service/agent_service.go
+++ b/internal/application/service/agent_service.go
@@ -423,7 +423,12 @@ func (s *agentService) registerSandboxFileTools(
if store := sessionSandboxFileStore(sandboxMgr); store != nil {
toolRegistry.RegisterTool(tools.NewListSandboxFilesTool(store))
toolRegistry.RegisterTool(tools.NewReadSandboxFileTool(store))
- toolRegistry.RegisterTool(tools.NewWriteSandboxFileTool(store))
+ // The per-round completion budget, not a fixed byte count, is what
+ // bounds one write; the tool advertises a limit derived from it.
+ toolRegistry.RegisterTool(tools.NewWriteSandboxFileTool(
+ store,
+ types.AgentRoundMaxCompletionTokensFor(config.MaxCompletionTokens, config.SandboxConfigID),
+ ))
toolRegistry.RegisterTool(tools.NewEditSandboxFileTool(store))
logger.Infof(ctx, "Registered list_sandbox_files, read_sandbox_file, write_sandbox_file, and edit_sandbox_file tools")
} else {
@@ -1142,11 +1147,11 @@ func (s *agentService) ValidateConfig(config *types.AgentConfig) error {
return fmt.Errorf("config cannot be nil")
}
- if config.MaxIterations <= 0 {
- config.MaxIterations = 5 // Default
- }
-
- if config.MaxIterations > MAX_ITERATIONS {
+ if config.MaxIterations < 0 {
+ config.MaxIterations = types.UnlimitedMaxIterations
+ } else if config.MaxIterations == 0 {
+ config.MaxIterations = 5
+ } else if config.MaxIterations > MAX_ITERATIONS {
return fmt.Errorf("max iterations too high: %d (max %d)", config.MaxIterations, MAX_ITERATIONS)
}
diff --git a/internal/application/service/agent_service_test.go b/internal/application/service/agent_service_test.go
index 44df91b38..8909afd1c 100644
--- a/internal/application/service/agent_service_test.go
+++ b/internal/application/service/agent_service_test.go
@@ -574,3 +574,22 @@ func TestGetKnowledgeBaseInfos_ExcludesUnprocessedDocuments(t *testing.T) {
require.Len(t, infos[0].RecentDocs, 1)
assert.Equal(t, "doc-completed", infos[0].RecentDocs[0].KnowledgeID)
}
+
+func TestValidateConfigMaxIterationsUnlimited(t *testing.T) {
+ s := &agentService{}
+
+ unlimited := &types.AgentConfig{MaxIterations: -1}
+ require.NoError(t, s.ValidateConfig(unlimited))
+ assert.Equal(t, types.UnlimitedMaxIterations, unlimited.MaxIterations)
+
+ normalized := &types.AgentConfig{MaxIterations: -9}
+ require.NoError(t, s.ValidateConfig(normalized))
+ assert.Equal(t, types.UnlimitedMaxIterations, normalized.MaxIterations)
+
+ unset := &types.AgentConfig{}
+ require.NoError(t, s.ValidateConfig(unset))
+ assert.Equal(t, 5, unset.MaxIterations)
+
+ tooHigh := &types.AgentConfig{MaxIterations: MAX_ITERATIONS + 1}
+ require.Error(t, s.ValidateConfig(tooHigh))
+}
diff --git a/internal/application/service/session_agent_qa.go b/internal/application/service/session_agent_qa.go
index 9fd0cea81..675f4c52c 100644
--- a/internal/application/service/session_agent_qa.go
+++ b/internal/application/service/session_agent_qa.go
@@ -91,6 +91,24 @@ func (s *sessionService) AgentQA(
return fmt.Errorf("failed to get chat model: %w", err)
}
+ // The model's own metadata decides two things the agent cannot guess: how
+ // much history fits before compaction, and whether images can be passed
+ // through. Resolve it once, before the engine is built — the engine sizes
+ // its memory consolidator from MaxContextTokens at construction.
+ var agentModelSupportsVision bool
+ modelContextWindow := 0
+ if effectiveModelID != "" {
+ if modelInfo, err := s.modelService.GetModelByID(ctx, effectiveModelID); err == nil && modelInfo != nil {
+ agentModelSupportsVision = modelInfo.Parameters.SupportsVision
+ modelContextWindow = modelInfo.Parameters.ContextWindow
+ }
+ }
+ agentConfig.MaxContextTokens = types.AgentMaxContextTokens(
+ agentConfig.MaxContextTokens, modelContextWindow,
+ )
+ logger.Infof(ctx, "Agent context window: %d tokens (model %s declares %d)",
+ agentConfig.MaxContextTokens, effectiveModelID, modelContextWindow)
+
// Get rerank model from custom agent config only when knowledge_search can
// actually run. A disabled KB scope makes all KB tools ineffective, so it
// must not force users to configure an otherwise-unused rerank model.
@@ -212,14 +230,6 @@ func (s *sessionService) AgentQA(
}
}
- // Route image data based on agent model's vision capability
- var agentModelSupportsVision bool
- if effectiveModelID != "" {
- if modelInfo, err := s.modelService.GetModelByID(ctx, effectiveModelID); err == nil && modelInfo != nil {
- agentModelSupportsVision = modelInfo.Parameters.SupportsVision
- }
- }
-
agentQuery := req.Query
var agentImageURLs []string
if agentModelSupportsVision && len(req.ImageURLs) > 0 {
@@ -404,9 +414,8 @@ func (s *sessionService) buildAgentConfig(
}
logger.Infof(ctx, "Agent search targets built: %d targets", len(searchTargets))
- if agentConfig.MaxContextTokens <= 0 {
- agentConfig.MaxContextTokens = types.DefaultMaxContextTokens
- }
+ // MaxContextTokens is deliberately left unset here. The caller fills it
+ // from the resolved model's declared window, which is not known yet.
return agentConfig, nil
}
diff --git a/internal/application/service/tenant_skill_install.go b/internal/application/service/tenant_skill_install.go
index 513c12194..8af420d90 100644
--- a/internal/application/service/tenant_skill_install.go
+++ b/internal/application/service/tenant_skill_install.go
@@ -1981,7 +1981,9 @@ func installerAgentConfig(
cfg.EnableSkillInstallMode(defaults.ID, skillDir)
custom := defaults.Config
cfg.MaxIterations = custom.MaxIterations
- if cfg.MaxIterations == 0 {
+ if cfg.MaxIterations < 0 {
+ cfg.MaxIterations = types.UnlimitedMaxIterations
+ } else if cfg.MaxIterations == 0 {
cfg.MaxIterations = 30
}
// The install tools are unioned in rather than read off the registry entry.
diff --git a/internal/errors/errors.go b/internal/errors/errors.go
index 43779a56b..6c4375db3 100644
--- a/internal/errors/errors.go
+++ b/internal/errors/errors.go
@@ -231,7 +231,7 @@ func NewAgentMissingAllowedToolsError() *AppError {
func NewAgentInvalidMaxIterationsError() *AppError {
return &AppError{
Code: ErrAgentInvalidMaxIterations,
- Message: "最大迭代次数必须在1-20之间",
+ Message: "最大迭代次数须为正整数,或 -1 表示不限制",
HTTPCode: http.StatusBadRequest,
}
}
diff --git a/internal/event/event.go b/internal/event/event.go
index e32d98d79..a0baa34ab 100644
--- a/internal/event/event.go
+++ b/internal/event/event.go
@@ -74,6 +74,10 @@ const (
// streams, so the UI can show which memories the answer saw.
EventMemoryRecalled EventType = "memory_recalled"
+ // EventContextCompacted is emitted when older conversation was summarized
+ // away to fit the context window.
+ EventContextCompacted EventType = "context_compacted"
+
// Session events
EventSessionTitle EventType = "session_title" // 会话标题更新
diff --git a/internal/event/event_data.go b/internal/event/event_data.go
index fa4557037..3cac95478 100644
--- a/internal/event/event_data.go
+++ b/internal/event/event_data.go
@@ -197,6 +197,25 @@ type AgentFinalAnswerData struct {
IsFallback bool `json:"is_fallback,omitempty"` // True when response is a fallback (no knowledge base match)
}
+// ContextCompactedData reports that older conversation was replaced by a
+// summary. Compaction changes what the agent remembers, so it is shown rather
+// than hidden: an answer that forgets an earlier instruction is otherwise
+// indistinguishable from the model ignoring it.
+type ContextCompactedData struct {
+ Reason string `json:"reason"` // threshold | overflow
+ Round int `json:"round"`
+ TokensBefore int `json:"tokens_before"`
+ TokensAfter int `json:"tokens_after"`
+ MessagesBefore int `json:"messages_before"`
+ MessagesAfter int `json:"messages_after"`
+ Summary string `json:"summary"`
+ // Degraded marks a summary that came from the mechanical archive because
+ // the summarizer failed.
+ Degraded bool `json:"degraded,omitempty"`
+ // SplitTurn marks a cut that landed inside a single turn.
+ SplitTurn bool `json:"split_turn,omitempty"`
+}
+
// AgentReflectionData represents agent reflection data
type AgentReflectionData struct {
ToolCallID string `json:"tool_call_id"` // Tool call ID for tracking
diff --git a/internal/handler/dto/model.go b/internal/handler/dto/model.go
index 4ebc9c76f..c38bad3d1 100644
--- a/internal/handler/dto/model.go
+++ b/internal/handler/dto/model.go
@@ -47,6 +47,8 @@ type ModelParametersDTO struct {
ExtraConfig map[string]string `json:"extra_config,omitempty"`
CustomHeaders map[string]string `json:"custom_headers,omitempty"`
SupportsVision bool `json:"supports_vision"`
+ ContextWindow int `json:"context_window,omitempty"`
+ MaxOutputTokens int `json:"max_output_tokens,omitempty"`
MaxConcurrency int `json:"max_concurrency,omitempty"`
AppID string `json:"app_id,omitempty"`
}
@@ -68,6 +70,8 @@ func NewModelResponse(ctx context.Context, m *types.Model) *ModelResponse {
ExtraConfig: m.Parameters.ExtraConfig,
CustomHeaders: m.Parameters.CustomHeaders,
SupportsVision: m.Parameters.SupportsVision,
+ ContextWindow: m.Parameters.ContextWindow,
+ MaxOutputTokens: m.Parameters.MaxOutputTokens,
MaxConcurrency: m.Parameters.MaxConcurrency,
AppID: m.Parameters.AppID,
}
@@ -80,8 +84,9 @@ func NewModelResponse(ctx context.Context, m *types.Model) *ModelResponse {
if m.IsBuiltin && !canManageBuiltin {
// Builtin: strip everything that could reveal per-tenant config.
// EmbeddingParameters and ParameterSize / Provider / InterfaceType /
- // SupportsVision are intentionally preserved (they describe the
- // capability surface, not the configured endpoint).
+ // SupportsVision / ContextWindow / MaxOutputTokens are intentionally
+ // preserved (they describe the capability surface, not the configured
+ // endpoint).
params.BaseURL = ""
params.ExtraConfig = nil
params.CustomHeaders = nil
diff --git a/internal/handler/session/agent_stream_handler.go b/internal/handler/session/agent_stream_handler.go
index db535b224..9b454c557 100644
--- a/internal/handler/session/agent_stream_handler.go
+++ b/internal/handler/session/agent_stream_handler.go
@@ -116,6 +116,7 @@ func (h *AgentStreamHandler) Subscribe() {
h.eventBus.On(event.EventAgentToolResult, h.handleToolResult)
h.eventBus.On(event.EventAgentReferences, h.handleReferences)
h.eventBus.On(event.EventMemoryRecalled, h.handleMemoryRecalled)
+ h.eventBus.On(event.EventContextCompacted, h.handleContextCompacted)
h.eventBus.On(event.EventAgentFinalAnswer, h.handleFinalAnswer)
h.eventBus.On(event.EventAgentReflection, h.handleReflection)
h.eventBus.On(event.EventError, h.handleError)
@@ -457,6 +458,39 @@ func (h *AgentStreamHandler) handleMemoryRecalled(ctx context.Context, evt event
return nil
}
+// handleContextCompacted forwards a compaction to the UI.
+//
+// The summary itself is carried so the user can expand it and see exactly what
+// the agent kept, which is the only way to tell an agent that forgot something
+// from an agent that never had it.
+func (h *AgentStreamHandler) handleContextCompacted(_ context.Context, evt event.Event) error {
+ data, ok := evt.Data.(event.ContextCompactedData)
+ if !ok {
+ return nil
+ }
+
+ if err := h.streamManager.AppendEvent(h.ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{
+ ID: evt.ID,
+ Type: types.ResponseTypeContextCompacted,
+ Done: true,
+ Timestamp: time.Now(),
+ Data: map[string]interface{}{
+ "reason": data.Reason,
+ "round": data.Round,
+ "tokens_before": data.TokensBefore,
+ "tokens_after": data.TokensAfter,
+ "messages_before": data.MessagesBefore,
+ "messages_after": data.MessagesAfter,
+ "summary": data.Summary,
+ "degraded": data.Degraded,
+ "split_turn": data.SplitTurn,
+ },
+ }); err != nil {
+ logger.GetLogger(h.ctx).Error("Append context compacted event to stream failed", "error", err)
+ }
+ return nil
+}
+
// handleFinalAnswer handles final answer events
func (h *AgentStreamHandler) handleFinalAnswer(ctx context.Context, evt event.Event) error {
data, ok := evt.Data.(event.AgentFinalAnswerData)
diff --git a/internal/models/chat/chat.go b/internal/models/chat/chat.go
index aa2dc5efa..b85c29d6b 100644
--- a/internal/models/chat/chat.go
+++ b/internal/models/chat/chat.go
@@ -53,6 +53,17 @@ type ImageURL struct {
Detail string `json:"detail,omitempty"` // "auto", "low", "high"
}
+// MessageKind marks messages the engine synthesized rather than received from
+// the user or the model. Compaction needs to tell its own summary apart from a
+// real user turn: a summary that looks like ordinary history gets fed back into
+// the next summarization pass and degrades into a summary of a summary.
+type MessageKind string
+
+// MessageKindCompactionSummary marks the message that replaces compacted
+// history. It carries the `user` role because that is where providers expect
+// conversation history, so the role alone cannot identify it.
+const MessageKindCompactionSummary MessageKind = "compaction_summary"
+
// Message 表示聊天消息
type Message struct {
Role string `json:"role"` // 角色:system, user, assistant, tool
@@ -67,6 +78,10 @@ type Message struct {
// 把 assistant 的 reasoning_content 原样回传,否则会以 400 拒绝请求;其他不要求的供应商
// 会忽略未知字段,无副作用。
ReasoningContent string `json:"reasoning_content,omitempty"`
+ // Kind is engine-internal bookkeeping. `json:"-"` keeps it off the wire:
+ // providers reject unknown message fields on some endpoints, and this one
+ // means nothing to them anyway.
+ Kind MessageKind `json:"-"`
}
// ToolCall represents a tool call in a message
diff --git a/internal/models/chat/openai_stream.go b/internal/models/chat/openai_stream.go
index c51e022b8..be7b4673d 100644
--- a/internal/models/chat/openai_stream.go
+++ b/internal/models/chat/openai_stream.go
@@ -130,10 +130,15 @@ func (c *RemoteAPIChat) processStream(
FinishReason: state.lastFinishReason,
}
} else {
+ logger.Errorf(ctx, "Stream read error: %v (tool_calls_assembled=%d)",
+ err, len(state.toolCallMap))
streamChan <- types.StreamResponse{
ResponseType: types.ResponseTypeError,
Content: err.Error(),
Done: true,
+ ToolCalls: state.buildOrderedToolCalls(),
+ Usage: state.usage,
+ FinishReason: types.FinishReasonIncomplete,
}
}
return
@@ -181,11 +186,15 @@ func (c *RemoteAPIChat) processRawHTTPStream(
Usage: state.usage,
}
} else {
- logger.Errorf(ctx, "Stream read error: %v", err)
+ logger.Errorf(ctx, "Stream read error: %v (tool_calls_assembled=%d)",
+ err, len(state.toolCallMap))
streamChan <- types.StreamResponse{
ResponseType: types.ResponseTypeError,
Content: err.Error(),
Done: true,
+ ToolCalls: state.buildOrderedToolCalls(),
+ Usage: state.usage,
+ FinishReason: types.FinishReasonIncomplete,
}
}
return
diff --git a/internal/types/agent.go b/internal/types/agent.go
index c20621045..d614df520 100644
--- a/internal/types/agent.go
+++ b/internal/types/agent.go
@@ -8,9 +8,29 @@ import (
"time"
)
-// DefaultMaxContextTokens is the default context window budget for agent conversations (200k).
+// DefaultMaxContextTokens is the context window assumed for a model that does
+// not declare one. 200k matches typical windows on current chat/VLM models
+// (GPT-4.1, Claude, Gemini, Qwen, etc.).
+//
+// It is still below the largest windows on the market. Guessing high is
+// the dangerous direction: compaction never fires, and the first sign of
+// trouble is the provider rejecting the request. Guessing low only costs some
+// history that would have fit.
const DefaultMaxContextTokens = 200000
+// AgentMaxContextTokens picks the context window for one agent run. An
+// explicit agent setting wins, then whatever the model declares, then the
+// assumed default.
+func AgentMaxContextTokens(configured, modelContextWindow int) int {
+ if configured > 0 {
+ return configured
+ }
+ if modelContextWindow > 0 {
+ return modelContextWindow
+ }
+ return DefaultMaxContextTokens
+}
+
// DefaultSmartReasoningMaxCompletionTokens is the per-round budget when the
// agent cannot emit write_sandbox_file / edit_sandbox_file. 4096 matches
// typical OpenAI-compatible provider defaults and is enough for ordinary
@@ -52,19 +72,40 @@ func AgentRoundMaxCompletionTokens(configured int) int {
return AgentRoundMaxCompletionTokensFor(configured, "")
}
+// MinSandboxWriteCompletionTokens is the floor applied to an explicitly
+// configured per-round budget when a sandbox is bound. write_sandbox_file and
+// edit_sandbox_file carry the whole file body inside the tool-call JSON, so a
+// cap sized for ordinary chat truncates the arguments mid-string on every
+// attempt — the agent then burns its rounds rewriting a file it can never
+// finish. Below this the setting is not a preference, it is a deadlock.
+const MinSandboxWriteCompletionTokens = 8192
+
// AgentRoundMaxCompletionTokensFor is AgentRoundMaxCompletionTokens with
-// the agent's sandbox: unset + sandbox uses the large write-file budget.
+// the agent's sandbox: unset + sandbox uses the large write-file budget, and a
+// configured value too small to hold a file write is raised to the floor.
func AgentRoundMaxCompletionTokensFor(configured int, sandboxConfigID string) int {
if configured > 0 {
+ if NeedsSandboxWriteCompletionBudget(sandboxConfigID) &&
+ configured < MinSandboxWriteCompletionTokens {
+ return MinSandboxWriteCompletionTokens
+ }
return configured
}
return DefaultMaxCompletionTokens(AgentModeSmartReasoning, sandboxConfigID)
}
+// UnlimitedMaxIterations is the stored MaxIterations value meaning the ReAct
+// loop has no round cap. Zero still means "unset, apply default" so agents
+// that omit the field keep their current behaviour.
+const UnlimitedMaxIterations = -1
+
// AgentConfig represents the full agent configuration (used at tenant level and runtime)
// This includes all configuration parameters for agent execution
type AgentConfig struct {
- MaxIterations int `json:"max_iterations"` // Maximum number of ReAct iterations
+ // MaxIterations caps ReAct rounds. Zero is unset (filled with a default);
+ // a negative value is unlimited — the loop runs until the model stops,
+ // the user cancels, or another guard fires. See UnlimitedMaxIterations.
+ MaxIterations int `json:"max_iterations"`
AllowedTools []string `json:"allowed_tools"` // List of allowed tool names
Temperature float64 `json:"temperature"` // LLM temperature for agent
KnowledgeBases []string `json:"knowledge_bases"` // Accessible knowledge base IDs
@@ -130,11 +171,16 @@ type AgentConfig struct {
// Outputs exceeding this limit are truncated with head + tail preservation.
MaxToolOutputChars int `json:"max_tool_output_chars,omitempty"`
- // Maximum context window tokens for the agent (default: 200000).
- // The agent compresses older messages to stay within this limit,
- // preserving tool_call/tool_result pairs.
+ // Maximum context window tokens for the agent. Zero means "use the
+ // model's context_window, or DefaultMaxContextTokens (200000)".
MaxContextTokens int `json:"max_context_tokens,omitempty"`
+ // How much recent conversation a compaction keeps verbatim. Zero means
+ // compaction.DefaultKeepRecentTokens, scaled down on small windows. This
+ // is the knob that decides how often compaction runs: whatever the context
+ // grew to, it comes out of a compaction at roughly this size.
+ CompactionKeepRecentTokens int `json:"compaction_keep_recent_tokens,omitempty"`
+
// Whether to execute independent tool calls in parallel (default: false).
// When enabled and the LLM returns multiple tool calls, they run concurrently via errgroup.
ParallelToolCalls bool `json:"parallel_tool_calls,omitempty"`
@@ -187,6 +233,11 @@ func (c *AgentConfig) SkillInstallDir() string {
return c.skillInstallDir
}
+// UnlimitedIterations reports whether the ReAct loop has no round cap.
+func (c *AgentConfig) UnlimitedIterations() bool {
+ return c != nil && c.MaxIterations < 0
+}
+
// CitationsEnabled preserves citation output for legacy runtime configs that
// predate the setting and therefore have a nil CitationEnabled value.
func (c *AgentConfig) CitationsEnabled() bool {
diff --git a/internal/types/agent_test.go b/internal/types/agent_test.go
index 47006e45d..a0d1f3c43 100644
--- a/internal/types/agent_test.go
+++ b/internal/types/agent_test.go
@@ -76,6 +76,24 @@ func TestUseCustomSystemPromptFlag(t *testing.T) {
}
}
+// The window the agent plans against must come from the model when the model
+// knows it. Assuming a window wider than the real one means compaction never
+// runs and the provider rejects the request instead.
+func TestAgentMaxContextTokens(t *testing.T) {
+ if got := AgentMaxContextTokens(0, 0); got != DefaultMaxContextTokens {
+ t.Fatalf("nothing known = %d, want %d", got, DefaultMaxContextTokens)
+ }
+ if got := AgentMaxContextTokens(0, 32768); got != 32768 {
+ t.Fatalf("model window unused: got %d, want 32768", got)
+ }
+ if got := AgentMaxContextTokens(64000, 32768); got != 64000 {
+ t.Fatalf("explicit agent setting must win, got %d", got)
+ }
+ if got := AgentMaxContextTokens(64000, 0); got != 64000 {
+ t.Fatalf("explicit agent setting with unknown model = %d, want 64000", got)
+ }
+}
+
func TestAgentRoundMaxCompletionTokens(t *testing.T) {
if got := AgentRoundMaxCompletionTokens(0); got != DefaultSmartReasoningMaxCompletionTokens {
t.Fatalf("zero configured = %d, want %d", got, DefaultSmartReasoningMaxCompletionTokens)
@@ -89,8 +107,18 @@ func TestAgentRoundMaxCompletionTokens(t *testing.T) {
if got := AgentRoundMaxCompletionTokens(4096); got != 4096 {
t.Fatalf("explicit 4096 = %d, want 4096", got)
}
- if got := AgentRoundMaxCompletionTokensFor(4096, "cfg-a"); got != 4096 {
- t.Fatalf("explicit 4096 with sandbox must stay 4096, got %d", got)
+ // With a sandbox bound, a cap this small cannot hold a file body inside the
+ // tool-call JSON, so every write truncates mid-string and the agent can
+ // never finish. The floor makes the setting survivable rather than a
+ // deadlock.
+ if got := AgentRoundMaxCompletionTokensFor(4096, "cfg-a"); got != MinSandboxWriteCompletionTokens {
+ t.Fatalf("explicit 4096 with sandbox = %d, want floor %d", got, MinSandboxWriteCompletionTokens)
+ }
+ if got := AgentRoundMaxCompletionTokensFor(32768, "cfg-a"); got != 32768 {
+ t.Fatalf("explicit value above the floor must be honored, got %d", got)
+ }
+ if got := AgentRoundMaxCompletionTokens(4096); got != 4096 {
+ t.Fatalf("no sandbox means no floor, got %d", got)
}
if got := AgentRoundMaxCompletionTokens(64000); got != 64000 {
t.Fatalf("explicit high value = %d, want 64000", got)
diff --git a/internal/types/chat.go b/internal/types/chat.go
index 1a43d8fa8..5b6a39678 100644
--- a/internal/types/chat.go
+++ b/internal/types/chat.go
@@ -240,6 +240,11 @@ const (
// MemoryRecalled: the long-term memories injected into this answer, so
// the UI can show and let the user delete what influenced it.
ResponseTypeMemoryRecalled ResponseType = "memory_recalled"
+ // ResponseTypeContextCompacted is older conversation summarized away to
+ // fit the context window. Surfaced because it changes what the agent
+ // remembers — an answer that forgets an earlier instruction is otherwise
+ // indistinguishable from the model ignoring it.
+ ResponseTypeContextCompacted ResponseType = "context_compacted"
// ResponseTypeInstallPrompt is the instruction a skill install handed to
// the installer agent. Only the skill install transcript emits this, and
// it emits it first, so replaying the log alone shows what was asked for
@@ -249,6 +254,12 @@ const (
)
// StreamResponse stream response
+// FinishReasonIncomplete marks a stream that broke before the provider sent a
+// finish reason (read error, timeout, stall). Whatever content and tool calls
+// were collected are a partial response: callers must not treat them as a
+// completed turn.
+const FinishReasonIncomplete = "incomplete"
+
type StreamResponse struct {
ID string `json:"id"`
ResponseType ResponseType `json:"response_type"`
diff --git a/internal/types/custom_agent.go b/internal/types/custom_agent.go
index ed207deba..9e0ed172c 100644
--- a/internal/types/custom_agent.go
+++ b/internal/types/custom_agent.go
@@ -134,7 +134,9 @@ type CustomAgentConfig struct {
CitationEnabled *bool `yaml:"citation_enabled" json:"citation_enabled"`
// ===== Agent Mode Settings =====
- // Maximum iterations for ReAct loop (only for agent type)
+ // Maximum iterations for the ReAct loop. Zero is unset (filled with a
+ // default). A negative value is unlimited: the loop runs until the model
+ // stops, the user cancels, or another guard fires.
MaxIterations int `yaml:"max_iterations" json:"max_iterations"`
// Timeout for a single LLM call in seconds (0 = use global default)
LLMCallTimeout int `yaml:"llm_call_timeout" json:"llm_call_timeout,omitempty"`
@@ -501,6 +503,9 @@ func (a *CustomAgent) EnsureDefaults() {
if a.Config.MaxIterations == 0 {
a.Config.MaxIterations = 10
}
+ if a.Config.MaxIterations < 0 {
+ a.Config.MaxIterations = UnlimitedMaxIterations
+ }
if a.Config.WebSearchMaxResults == 0 {
a.Config.WebSearchMaxResults = 5
}
diff --git a/internal/types/custom_agent_test.go b/internal/types/custom_agent_test.go
index 83e5e9e26..927890b59 100644
--- a/internal/types/custom_agent_test.go
+++ b/internal/types/custom_agent_test.go
@@ -70,6 +70,28 @@ func TestEnsureDefaults_MaxCompletionTokensByMode(t *testing.T) {
}
}
+func TestEnsureDefaults_MaxIterationsUnlimited(t *testing.T) {
+ unset := &CustomAgent{Config: CustomAgentConfig{}}
+ unset.EnsureDefaults()
+ if unset.Config.MaxIterations != 10 {
+ t.Fatalf("unset max_iterations should default to 10, got %d", unset.Config.MaxIterations)
+ }
+
+ unlimited := &CustomAgent{Config: CustomAgentConfig{MaxIterations: -1}}
+ unlimited.EnsureDefaults()
+ if unlimited.Config.MaxIterations != UnlimitedMaxIterations {
+ t.Fatalf("EnsureDefaults must preserve unlimited max_iterations, got %d",
+ unlimited.Config.MaxIterations)
+ }
+
+ oddNegative := &CustomAgent{Config: CustomAgentConfig{MaxIterations: -7}}
+ oddNegative.EnsureDefaults()
+ if oddNegative.Config.MaxIterations != UnlimitedMaxIterations {
+ t.Fatalf("any negative max_iterations should normalize to %d, got %d",
+ UnlimitedMaxIterations, oddNegative.Config.MaxIterations)
+ }
+}
+
func TestEnsureDefaults_CitationsDefaultEnabledAndPreserveFalse(t *testing.T) {
legacy := &CustomAgent{Config: CustomAgentConfig{}}
legacy.EnsureDefaults()
diff --git a/internal/types/model.go b/internal/types/model.go
index 14f26ad4e..bbacaae15 100644
--- a/internal/types/model.go
+++ b/internal/types/model.go
@@ -134,6 +134,15 @@ type ModelParameters struct {
// 保留字段(Authorization、api-key、Content-Type、Accept 等)会在运行期被忽略以避免破坏签名/鉴权流程。
CustomHeaders map[string]string `yaml:"custom_headers,omitempty" json:"custom_headers,omitempty"`
SupportsVision bool `yaml:"supports_vision" json:"supports_vision"` // Whether the model accepts image/multimodal input
+ // ContextWindow is the model's total context window in tokens and
+ // MaxOutputTokens the most it emits in one response. Both are provider
+ // facts the agent cannot discover but has to act on: the context window is
+ // what decides when conversation history gets compacted, and assuming a
+ // window larger than the real one means compaction never fires and the
+ // provider rejects the request mid-conversation instead. 0 means unknown,
+ // which falls back to DefaultMaxContextTokens.
+ ContextWindow int `yaml:"context_window,omitempty" json:"context_window,omitempty"`
+ MaxOutputTokens int `yaml:"max_output_tokens,omitempty" json:"max_output_tokens,omitempty"`
// MaxConcurrency caps concurrent in-flight BACKGROUND (ingestion /
// enrichment) calls to THIS specific model, keyed by model ID and shared
// across all replicas. 0 (the default) means "fall back to the
diff --git a/website-docs/03-features/06-models.md b/website-docs/03-features/06-models.md
index cda2ab0ef..2a7033f51 100644
--- a/website-docs/03-features/06-models.md
+++ b/website-docs/03-features/06-models.md
@@ -165,6 +165,7 @@ return wrapChatConcurrency(c, config.MaxConcurrency, err)
| `extra_config` | map[string]string | nil | 厂商专属配置(如 Azure 的 `api_version`) |
| `custom_headers` | map[string]string | nil | 附加自定义 HTTP 请求头(类似 OpenAI SDK `extra_headers`;`Authorization`、`api-key` 等保留头在运行期被忽略) |
| `supports_vision` | bool | false | Chat 模型是否接受图片多模态输入 |
+| `context_window` | int | 0(回落到 200000) | 对话/VLM 上下文窗口(token)。智能体压缩历史按此上限工作;留空使用默认 200K。请填厂商真实窗口,填大会导致压缩不触发 |
| `max_concurrency` | int | 0(回落到全局 `model.max_concurrency`) | 该模型后台任务并发上限(仅 chat/vlm/embedding 生效) |
| `app_id` / `app_secret` | string | 空 | WeKnoraCloud 专用凭证,`app_secret` AES 加密存储 |
diff --git a/website-docs/03-features/07-agent.md b/website-docs/03-features/07-agent.md
index a015a9742..d0bc4f3d3 100644
--- a/website-docs/03-features/07-agent.md
+++ b/website-docs/03-features/07-agent.md
@@ -343,18 +343,26 @@ var ToolCapabilityRequirements = map[string]ToolRequirement{
`manageContextWindow`(`internal/agent/observe.go`)在每轮 Think 之前执行:
-**第一级:LLM 记忆整合(memory.Consolidator)** —— 当估算 token 超过 `MaxContextTokens × 0.5`(`DefaultConsolidationThreshold = 0.5`)时触发:
+`MaxContextTokens` 优先取智能体自身设置,其次取模型 `parameters.context_window`,都没有才回落到 `DefaultMaxContextTokens = 200000`。默认值刻意取在市面最大窗口之下:猜大是危险方向——压缩永远不触发,第一个征兆就是上游直接拒绝请求;猜小只是少留了一些本来放得下的历史。
+
+两级压缩共用同一个阈值 `MaxContextTokens - contextReserveTokens`,其中 `contextReserveTokens = max(该轮 completion 预算 + 4096, 16384)`。留白按**绝对值**而非窗口比例计算,因为要放下的是回复,而回复的大小和窗口多大无关;留白随该轮 completion 预算走,否则一个允许输出 24576 token 的智能体会在请求被接受之后被截断回复。
+
+**第一级:LLM 记忆整合(memory.Consolidator)** —— 当估算 token 超过上述阈值时触发:
- 保留:system prompt(首条)、**当前轮**(最后一条 user 消息及其后全部 assistant/tool 消息)、以及按 token 预算从尾部回收的近期历史(`findKeepBoundary` 以 `targetTokens = maxTokens × 0.5 × 0.6` 为目标,预留 500 token 给摘要,且**回收时把 assistant+tool_calls 与其 tool 结果作为整组处理,绝不拆散**);
- 其余较老的历史交给 LLM 摘要(低温 0.3、`MaxTokens: 2000`、单次 60s 超时、最多 `maxConsolidationAttempts = 3` 次),摘要要求保留关键事实、工具结果、用户意图和错误处理过程,目标压到原文 30% 以内;
-- 摘要作为一条 system 消息插入:`[Memory Summary - N earlier messages consolidated]`;
+- 摘要要求按固定 section 输出(Goal / Constraints & Preferences / Progress / Key Decisions / Next Steps / Critical Context),并把待总结的对话包在 `<conversation>` 标签内、指令放在最后,避免摘要器把对话内容当成指令;
+- 摘要作为一条 **user** 消息插入,包在 `<summary>` 标签里,前缀为 `The conversation history before this point was compacted into the following summary:`。用 user 而非第二条 system,是因为它是对话历史而不是指令,部分供应商会合并或特殊加权 system 消息;
+- 摘要末尾还会附上一段机械提取的沙箱文件清单(`internal/agent/memory/file_ops.go`):从被压缩掉的 `write_sandbox_file` / `edit_sandbox_file` / `read_sandbox_file` 调用里取出 `path`,写过的归入 `<modified-files>`、只读过的归入 `<read-files>`(写过的文件不再重复出现在 read 列表里),并从上一次摘要的同名标签里继承,使其跨多次压缩累积。摘要是散文,路径清单恰好是最容易被摘要器丢掉的细节;一旦丢了,模型会以为文件还没写,重新从头生成已经落盘的产物;
- LLM 三次都失败则退化为 `rawArchive`(截断的纯文本归档),绝不丢信息地静默失败。
-**第二级:滑动裁剪(token.CompressContext)** —— 无论整合是否发生都会执行,当 token 超过 `MaxContextTokens × 0.8`(`DefaultContextThresholdRatio = 0.8`)时:
+**第二级:滑动裁剪(token.CompressContext)** —— 无论整合是否发生都会执行,当 token 仍超过同一阈值时:
- 同样保留 system、当前轮尾部;
- 中间历史经 `groupToolMessages` 分组(assistant+tool_calls 与后续 tool 结果为一组),从**最老的组**开始整组丢弃,直到释放的 token 达到 `currentTokens - threshold`。
+**兜底:溢出后压缩重试一次。** 上面两级都建立在 token **估算**之上,而估算会低估——真实分词、供应商侧的模板开销都不在估算里,所以一个看起来安全的请求仍可能撞到窗口。判据:`finish_reason=length` 且 `usage.completion_tokens` **小于**我们本轮请求的上限(`AgentEngine.responseHitContextLimit`)。既然不是我们的 `max_tokens` 拦住的,那拦住它的就是窗口,而窗口是压缩能解决的;反之,用满了预算的截断说明模型确实还有话说,重试只会烧掉一轮复现同样的截断。命中时强制压缩(`forceCompaction`,绕过阈值判断)并重试一次,`overflowRecovered` 保证每轮最多一次——第二次仍溢出,说明问题根本不在历史长度上。
+
### 4.3 会话历史(agent_history)
跨轮历史由 `LoadAgentHistory`(`internal/application/service/agent_history.go`)每轮从 messages 表重建(DB 是唯一事实来源,无 Redis/内存缓存):
@@ -427,7 +435,29 @@ Agent 侧的启停在 `configureSkillsFromAgent`(`internal/application/service
Manager 初始化时:`disabled` 模式的 `disabledSandbox` 拒绝一切执行。
-### 5.4 技能执行时序图
+### 5.4 沙箱文件工具的契约
+
+`write_sandbox_file` / `read_sandbox_file` / `edit_sandbox_file` 三个工具共用一套上限与并发约定,设计目标是:**模型能写出来的文件,必须能读回来、能局部改,且不会因为一次响应写不完就前功尽弃。**
+
+**写:按 completion 预算给出建议大小,但不据此拒绝。** 工具描述里告诉模型的单次 `content` 建议上限不是写死的常量,而是由本轮 `MaxCompletionTokens` 推导(`writeBudgetBytes`,见 `internal/agent/tools/sandbox_write.go`)。理由是:真正卡住一次写入的从来不是某个字节数,而是模型这一轮还能吐多少 token;如果用户在前端把 `max_completion_token` 调小,一个固定的 256 KiB 上限就成了谎言——模型以为能写,实际参数在半路被截断。
+
+但这个数字只是**预测,不是校验**。推导用的字节/token 系数在 ASCII 和中文之间能差三倍,模型跑赢预测只说明预测不准。而能走到工具里的 `content` 必然是完整的:`finish_reason=length` 的整批调用已在 `act.go` 被拒,JSON 被截断的也已被 `RepairJSONDetail` 拦下。此时因为超出预测而拒绝一份完整的内容,等于把已经花 token 换来的成果扔掉,逼模型分块重发同样的字节——总开销严格更高,且比那次已经成功的调用更容易截断。它也防不住它看起来在防的东西:被截断的写入通常**小于**预测值,照样畅通无阻。工具里唯一硬拦的是 8 MiB 的单文件上限(overwrite 与 append 两条路径都查)。写不完的文件用 `mode: "append"` 分块续写。
+
+**读:分页而非拒绝。** 一页同时受三个上限约束:2000 行、`max_bytes` 字节预算,以及**注册表的 rune 预算**(`OutputBudget(ctx)`,默认 `DefaultMaxToolOutput = 24000`)。没读完的页在结果末尾附上 `[Showing lines A-B of N. Use offset=M to continue.]`;续读提示放在**工具结果里**而不是系统提示词里,是因为它只在模型真正需要时才出现,且直接给出下一次的 `offset`,不需要模型自己算。文件超过 8 MiB 才彻底拒绝下载(与 append 的累计上限对齐),转而建议 `shell_exec` 的 `sed -n` / `head` / `tail`。单行宽于整页预算时无法靠翻页前进,结果直接给出 `sed -n 'Np'` 命令,而不是返回一个空页让模型反复重试。
+
+**页是从整份下载里切出来的。** 三个沙箱后端的 `RemoteClient.ReadFile` 都只接受路径、返回全文,没有 range 读。整文件读进内存再按行切在本地文件系统上重读是 page cache 命中;我们跨网络,每翻一页重下一次全文意味着一个 1 MB 的产物按每页约 23 KB 翻要 45 次全量下载、45 个来回。所以 `read_sandbox_file` 在工具实例上缓存最近一次下载的文件(工具注册表每轮重建,缓存天然是轮次内的)。命中条件是 session、路径、size、mtime 全部相同,**且期间没有任何沙箱文件变更**——最后这条由 `file_mutation_queue.go` 里的全局纪元计数提供:同长度替换(比如改一个数字)不会改变 size,而部分后端的 mtime 只有秒级精度,单靠 stat 会读到脏数据。计数器是全局而非按路径的,写 B 文件会作废 A 的缓存,代价是极少发生的一次重下载,换来的是零维护、不会增长。缓存只留一个槽位:翻页只会走一个文件,单槽把内存占用锁在一份文件而不是这一轮读过的所有文件。
+
+第三个上限是必须的:`TruncateToolOutput` 对超预算的输出是**挖掉中段、保留首尾**。一页若走到那一步是最坏情况——续读提示恰好在尾部,会存活下来并"证明"已连续显示 1-2000 行,而中间被删掉的那一块模型永远不会察觉。按注册表同一套预算裁页,这条截断路径就永远不会触发。两个预算单位不同,且方向与直觉相反:64 KiB 中文约 22k rune 装得下,64 KiB 英文是 65k rune 装不下。至于 UTF-8 安全,分页天然成立——只在 `\n` 处断页,而 0x0A 不可能出现在多字节序列内部,字节预算落在哪都切不坏一个 rune。
+
+这三条约束都只写在各自工具的描述里,系统提示词不重复。单个工具的硬约束(尺寸、分页、`edits` 的匹配语义、`shell_exec` 的工作目录与退出码语义)属于工具描述,工具描述随 tools payload 每轮都发,和系统提示词同时在上下文里,重复一份不会让模型更容易看到;系统提示词只留跨工具的选型规则(比如"需要技能包的脚本走 `execute_skill_script` 而不是 `shell_exec`")。据此把系统提示词里 `shell_exec` 的 11 条子项收成一行工具清单条目,净省约 1.3 KB;两个方向的测试互相咬住这条边界(`prompts_shell_test.go` 断言机制细节**不在**提示词里,`shell_exec_test.go` 断言它们**在**工具描述里),避免日后又被顺手加回去。
+
+**改:一次调用改多处,且只有一种入参形状。** 所有替换都放进 `edits` 数组,单处修改就是长度为 1 的数组。刻意不保留并列的 `old_string` / `new_string` 平铺字段:那样只为单处修改省下十几个字节,代价是模型要在两种互斥形状间做选择、`replace_all` 只对其中一种有效、每条报错都要维护带/不带下标两个版本。`replace_all` 改为挂在条目上,于是一批里可以混合「全局重命名」和「必须唯一」的条目。
+
+每个 `old_string` 都对照**原始文件**匹配,而不是对照前几处编辑之后的结果——模型是看着同一个版本的文件写出所有 `old_string` 的,那就该在那个版本里解析。于是批量编辑与顺序无关,两处编辑抢同一段字节会在写入前被检测为区间相交并整批拒绝(`replace_all` 展开出的多个区间同样参与检测),而不是静默改坏文件。模型把数组写成单个对象或 JSON 字符串是常见现象,`sandboxEditList` 会容错解析——为一个模型自己看不见的格式问题浪费一轮不划算。
+
+**并发:按路径串行化。** append 与 edit 都是「读—改—写」,而一次响应里的多个工具调用会并行执行(`ParallelToolCalls`)。同一路径的两次 append 若并行,会读到同一份底本,后写的把先写的整个覆盖掉,症状是模型自己的输出凭空消失、且无法从日志证伪。`internal/agent/tools/file_mutation_queue.go` 按 `(sessionID, path)` 加锁串行化,不同路径仍然并发——全局锁虽然也正确,但会让并行工具调用对最需要它的场景失去意义。
+
+### 5.5 技能执行时序图
```mermaid
sequenceDiagram