feat(harness): let the decision model drive four judgement points

Compaction candidates, context modes, long-run steering, and long-term
memory writes are now decided by the configured decision model when the
matching strategy is set to ``decision``:

- ``HARNESS_COMPACTION_STRATEGY=decision`` replaces the role based
  candidate rules with a content pre-filter plus a per-candidate
  "keep verbatim or summarize" judgement, because role labels cannot tell
  a tool result from the user's own text on real ADK traffic.
- ``HARNESS_MODE_STRATEGY=decision`` decides the context mode blocks per
  invocation instead of matching keywords.
- ``HARNESS_LONG_RUN_STRATEGY=decision`` only injects steering guidance
  while the run still looks unfinished, with the counter as a hard
  fallback after ``unconditional_after_model_calls``.
- ``MEMORY_SAVE_STRATEGY=decision`` decides whether a turn holds something
  durable; a skipped turn keeps its cursor, so nothing is dropped.

Every point defaults to its previous behaviour and degrades to it when the
decision model is absent or fails.

Change-Id: Id68bd9c71540e78a87638fc5c4735712cf7317a4

Author: wujiaming-ai

docs/content/docs/framework/memory/long-term/index.en.mdx

@@ -173,6 +173,16 @@ agent = Agent(
 ```
 
 To avoid frequent index re-initialization, VeADK exposes `MIN_MESSAGES_THRESHOLD` and `MIN_TIME_THRESHOLD` env vars to tune the save cadence: by default it saves after 10 accumulated events or a 60-second interval; additionally, when you switch `session_id` and start a new turn, VeADK saves the previous session to long-term memory.
+
+The default is `MEMORY_SAVE_STRATEGY=threshold`, the two thresholds above. With `decision`, the configured decision model decides whether the turn holds something durable (a stated preference, fact, decision, or constraint), thresholded by `MEMORY_SAVE_WORTH_THRESHOLD` (default `0.5`):
+
+| Judgement | Behaviour |
+| --- | --- |
+| Above the threshold | Saved immediately, without waiting for 10 events or 60 seconds |
+| Below the threshold | Skipped, and not saved merely because events accumulated |
+| Unavailable | Falls back to `MIN_MESSAGES_THRESHOLD` / `MIN_TIME_THRESHOLD` |
+
+A skipped turn does not advance the save cursor, so the next accepted judgement writes those events together: nothing is lost. See the [environment variable reference](/references/configuration/environment-variables) for the decision model variables.
 ## Auto-save Memory Policy
 Configure `auto_save_memory_policy` on `Agent` to decide which events are persisted by automatic long-term-memory saving. If omitted, it is equivalent to `"default"`.
 ```python

docs/content/docs/framework/memory/long-term/index.mdx

@@ -173,6 +173,16 @@ agent = Agent(
 ```
 
 为避免索引被频繁初始化，VeADK 提供 `MIN_MESSAGES_THRESHOLD` 与 `MIN_TIME_THRESHOLD` 两个环境变量自定义保存周期：默认在累计 10 条 event 或间隔 60 秒时触发保存；此外，当切换 `session_id` 并发起新问答时，VeADK 会自动把上一个会话写入长期记忆。
+
+默认保存策略是 `MEMORY_SAVE_STRATEGY=threshold`，即上面的双阈值规则。设置为 `decision` 后，改由已配置的判定模型判断"这一轮是否包含值得长期记住的内容"（陈述过的偏好、事实、决策、约束等），阈值由 `MEMORY_SAVE_WORTH_THRESHOLD` 控制，默认 `0.5`：
+
+| 判定结果 | 行为 |
+| --- | --- |
+| 通过阈值 | 立即写入，不必等满 10 条 event 或 60 秒 |
+| 未通过阈值 | 跳过，不会仅因为攒够条数就写入 |
+| 判定不可用 | 回落到 `MIN_MESSAGES_THRESHOLD` / `MIN_TIME_THRESHOLD` |
+
+被跳过的轮次不会推进保存游标，后续判定通过时会把这批 event 一起写入，因此不会丢数据。判定模型的环境变量见 [环境变量参考](/references/configuration/environment-variables)。
 ## 自动保存记忆策略
 开发者在 `Agent` 上配置 `auto_save_memory_policy` 来控制自动保存长期记忆时哪些 event 会被写入；不配置时等价于 `"default"`。
 ```python

docs/content/docs/references/configuration/environment-variables.en.mdx

@@ -76,6 +76,9 @@ Prefix `HARNESS_`, used to attach optional Harness plugins to HarnessApp Runtime
 | `HARNESS_MAX_TOOL_RESULT_CHARS` | Single tool-result compaction threshold, default `4000`. |
 | `HARNESS_VERIFIER_MODE` | Final-response verification mode, `observe` or `block`; default `observe`. |
 | `HARNESS_STORE_PATH` | Optional JSONL event store path; in-memory store is used when unset. |
+| `HARNESS_COMPACTION_STRATEGY` | Compaction candidate strategy, `builtin` or `decision`; default `builtin`. |
+| `HARNESS_LONG_RUN_STRATEGY` | Long-run steering strategy, `counter` or `decision`; default `counter`. |
+| `HARNESS_MODE_STRATEGY` | Context mode-block strategy, `keywords` or `decision`; default `keywords`. |
 
 The `harness_enhance` block maps to these environment variables when deploying a HarnessApp Runtime. Prefer `harness.yaml` or `veadk agentkit invoke` flags for normal developer workflows; use environment variables for platform integration and container runtimes.
 

docs/content/docs/references/configuration/environment-variables.mdx

@@ -76,6 +76,9 @@ volcengine:
 | `HARNESS_MAX_TOOL_RESULT_CHARS` | 单个工具结果压缩阈值，默认 `4000`。 |
 | `HARNESS_VERIFIER_MODE` | 最终回答校验模式，`observe` 或 `block`，默认 `observe`。 |
 | `HARNESS_STORE_PATH` | 可选 JSONL 事件存储路径；不设置时使用内存存储。 |
+| `HARNESS_COMPACTION_STRATEGY` | 工具结果压缩候选策略，`builtin` 或 `decision`，默认 `builtin`。 |
+| `HARNESS_LONG_RUN_STRATEGY` | 长任务收尾引导策略，`counter` 或 `decision`，默认 `counter`。 |
+| `HARNESS_MODE_STRATEGY` | 上下文模式块策略，`keywords` 或 `decision`，默认 `keywords`。 |
 
 `harness_enhance` 配置块会在 HarnessApp Runtime 部署时映射为这些环境变量。推荐开发者优先通过 `harness.yaml` 或 `veadk agentkit invoke` 参数启用，环境变量适合平台集成和镜像运行时。
 

docs/extensions/harness/README.md

@@ -173,6 +173,10 @@ export HARNESS_ENHANCE_ENABLED=true
 export HARNESS_ENHANCE_COMPONENTS=invocation_context,compactor,response_verification
 export HARNESS_COMPRESSION_PROVIDER=builtin
 export HARNESS_VERIFIER_MODE=observe
+# optional: let a decision model judge the built-in rules
+# export HARNESS_COMPACTION_STRATEGY=decision
+# export HARNESS_LONG_RUN_STRATEGY=decision
+# export HARNESS_MODE_STRATEGY=decision
 ```
 
 Equivalent YAML:
@@ -208,6 +212,21 @@ veadk agentkit invoke \
 | `HARNESS_MAX_TOOL_RESULT_CHARS` | `4000` | Tool-result compaction threshold. |
 | `HARNESS_VERIFIER_MODE` | `observe` | Verification behavior: `observe` or `block`. |
 | `HARNESS_STORE_PATH` | unset | Uses a JSONL event store when set. |
+| `HARNESS_COMPACTION_STRATEGY` | `builtin` | Compaction candidates: `builtin` or `decision`. |
+| `HARNESS_LONG_RUN_STRATEGY` | `counter` | Long-run steering: `counter` or `decision`. |
+| `HARNESS_MODE_STRATEGY` | `keywords` | Context mode blocks: `keywords` or `decision`. |
+
+## Decision Model Strategies
+
+The three `*_STRATEGY=decision` settings replace a rule with a judgement from
+the configured decision model. They need `DECISION_MODEL_ENABLED=true` and an
+API key; without one, each strategy keeps its rule and logs a warning.
+
+| Strategy | Rule it replaces | Unavailable behaviour |
+| --- | --- | --- |
+| `HARNESS_COMPACTION_STRATEGY` | Role and size based compaction candidates | Builtin rules |
+| `HARNESS_LONG_RUN_STRATEGY` | Model-call counter | Counter, forced after the unconditional count |
+| `HARNESS_MODE_STRATEGY` | Precision and artifact keyword markers | Keyword markers |
 
 ## Compaction Providers
 

docs/extensions/harness/README.zh.md

@@ -165,6 +165,10 @@ export HARNESS_ENHANCE_ENABLED=true
 export HARNESS_ENHANCE_COMPONENTS=invocation_context,compactor,response_verification
 export HARNESS_COMPRESSION_PROVIDER=builtin
 export HARNESS_VERIFIER_MODE=observe
+# 可选：把内置规则交给判定模型
+# export HARNESS_COMPACTION_STRATEGY=decision
+# export HARNESS_LONG_RUN_STRATEGY=decision
+# export HARNESS_MODE_STRATEGY=decision
 ```
 
 等价 YAML：
@@ -200,6 +204,19 @@ veadk agentkit invoke \
 | `HARNESS_MAX_TOOL_RESULT_CHARS` | `4000` | 工具结果压缩阈值。 |
 | `HARNESS_VERIFIER_MODE` | `observe` | 校验行为，支持 `observe` 或 `block`。 |
 | `HARNESS_STORE_PATH` | 未设置 | 设置后使用 JSONL event store。 |
+| `HARNESS_COMPACTION_STRATEGY` | `builtin` | 压缩候选策略：`builtin` 或 `decision`。 |
+| `HARNESS_LONG_RUN_STRATEGY` | `counter` | 长任务引导策略：`counter` 或 `decision`。 |
+| `HARNESS_MODE_STRATEGY` | `keywords` | 上下文模式块策略：`keywords` 或 `decision`。 |
+
+## 判定模型策略
+
+三个 `*_STRATEGY=decision` 开关把一条规则换成判定模型的判定结果，需要 `DECISION_MODEL_ENABLED=true` 与 API Key；没有配置时各自保留原规则并打印告警。
+
+| 策略 | 被替代的规则 | 判定不可用时 |
+| --- | --- | --- |
+| `HARNESS_COMPACTION_STRATEGY` | 按角色和长度挑选压缩候选 | 内置规则 |
+| `HARNESS_LONG_RUN_STRATEGY` | 仅按模型调用次数计数 | 计数规则，超过强制次数后必定生效 |
+| `HARNESS_MODE_STRATEGY` | 精度/产物关键词匹配 | 关键词匹配 |
 
 ## 压缩 Provider
 

tests/extensions/decisions/test_harness_judges.py

@@ -0,0 +1,149 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Harness judges against a real HTTP System One endpoint."""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from veadk.extensions.decisions import (
+    DecisionModelConfig,
+    DecisionModelResponseError,
+    DecisionExtension,
+)
+from veadk.extensions.harness.modules.tool_result_compactor import (
+    DecisionCompactionJudge,
+    ToolResultCompactor,
+    ToolResultCompactorConfig,
+)
+from veadk.extensions.harness.schemas import CompressionRequest, ConversationMessage
+
+from .fake_system_one import fake_system_one
+
+
+def _extension(base_url: str) -> DecisionExtension:
+    return DecisionExtension(
+        DecisionModelConfig(enabled=True, api_base=base_url, api_key="test-key")
+    )
+
+
+def _scripted(
+    probabilities: dict[int, float],
+) -> tuple[int, dict[str, str], dict[str, object]]:
+    """Build a response answering ``item_<index>`` with the given values."""
+    answers = {
+        f"item_{index}": {"type": "noul", "noul": value}
+        for index, value in probabilities.items()
+    }
+    return 200, {}, {"model": "fake-system-one", "answers": answers, "usage": {}}
+
+
+def test_compaction_judge_batches_one_question_per_candidate() -> None:
+    with fake_system_one() as server:
+        judge = DecisionCompactionJudge(_extension(server.base_url))
+        probabilities = asyncio.run(
+            judge.aprotect(
+                goal="rank the candidates by score",
+                evidence={1: "x" * 5000, 3: "y" * 5000},
+            )
+        )
+
+    assert set(probabilities) == {1, 3}
+    assert len(server.calls) == 1
+    call = server.calls[0]
+    assert call.model == "jev-latest"
+    assert call.authorization == "Bearer test-key"
+    assert sorted(call.questions) == ["item_1", "item_3"]
+    assert call.questions["item_1"]["type"] == "noul"
+    assert "rank the candidates by score" in call.state
+    assert "item 1" in call.state and "item 3" in call.state
+
+
+def test_compaction_judge_parses_scripted_probabilities() -> None:
+    with fake_system_one([_scripted({0: 0.95, 1: 0.05})]) as server:
+        judge = DecisionCompactionJudge(_extension(server.base_url))
+        probabilities = asyncio.run(
+            judge.aprotect(goal="g", evidence={0: "a" * 4000, 1: "b" * 4000})
+        )
+
+    assert probabilities[0] == pytest.approx(0.95)
+    assert probabilities[1] == pytest.approx(0.05)
+
+
+def test_compaction_judge_rejects_a_partial_judgement() -> None:
+    partial = (
+        200,
+        {},
+        {"model": "fake", "answers": {"item_0": {"type": "noul", "noul": 0.9}}},
+    )
+    with fake_system_one([partial]) as server:
+        judge = DecisionCompactionJudge(_extension(server.base_url))
+        with pytest.raises(DecisionModelResponseError, match="no usable answer"):
+            asyncio.run(
+                judge.aprotect(goal="g", evidence={0: "a" * 4000, 1: "b" * 4000})
+            )
+
+
+def test_compaction_judge_bounds_the_state_and_keeps_every_item() -> None:
+    evidence = {index: "z" * 20000 for index in range(12)}
+    with fake_system_one() as server:
+        judge = DecisionCompactionJudge(
+            _extension(server.base_url),
+            max_state_chars=2400,
+            max_evidence_chars=800,
+        )
+        asyncio.run(judge.aprotect(goal="g", evidence=evidence))
+
+    state = server.calls[0].state
+    assert len(state) < 4000
+    for index in evidence:
+        assert f"item {index} (" in state
+
+
+def test_decision_strategy_end_to_end_keeps_evidence_and_fits() -> None:
+    """A real round trip through the client, the judge, and the policy."""
+
+    messages = [
+        ConversationMessage(role="user", content="goal: rank the candidates"),
+        ConversationMessage(role="user", content="tool_result: " + "x" * 9000),
+        ConversationMessage(role="model", content="I inspected the table."),
+        ConversationMessage(role="user", content="tool_result: " + "y" * 9000),
+        ConversationMessage(role="model", content="One more check needed."),
+        ConversationMessage(role="model", content="Now I will summarize."),
+        ConversationMessage(role="user", content="go on"),
+    ]
+    with fake_system_one([_scripted({1: 0.99, 3: 0.01})]) as server:
+        compactor = ToolResultCompactor(
+            ToolResultCompactorConfig(
+                strategy="decision",
+                max_context_chars=12000,
+                summary_chars=400,
+            ),
+            compaction_judge=DecisionCompactionJudge(_extension(server.base_url)),
+        )
+        result = asyncio.run(
+            compactor.acompress_messages(
+                CompressionRequest(messages=messages, max_context_chars=12000),
+                goal="rank the candidates",
+            )
+        )
+
+    assert len(server.calls) == 1
+    assert result.report.omitted_messages == 0
+    assert result.report.compressed_chars <= 12000
+    assert result.messages[1] == messages[1]
+    assert result.messages[3] != messages[3]