diff --git a/README.md b/README.md
index be9e250a..06d9ea9f 100644
--- a/README.md
+++ b/README.md
@@ -88,6 +88,13 @@ You hire coworkers, not chat boxes. Each one has a **Role**, a **Goal**, a **Bac
### Agent Runtime: native or DSH (2.2.0+)
The `AgentRuntimeProvider` contract separates an employee from the engine that runs its turn. The **native runtime** keeps ReAct, Plan-and-Execute, persistent Goals, and Team Runs inside MateClaw. The **DSH runtime** manages `dsh-jsonrpc-agent` as an authenticated child process and streams thinking, text, tool calls, usage, completion, and cancellation back as normalized runtime events. DSH owns the external Agent loop; MateClaw still owns the session, workspace, credentials, tools, approvals, messages, and UI projection. Runtime availability and capabilities are validated before startup, and DSH can be installed, verified, connection-tested, enabled, or disabled from the console. [Configure DeepSeek Harness →](https://claw.mate.vip/docs/en/deepseek-harness)
+### Durable long tasks: checkpoint, restart, continue (2.2.0+)
+Persistent Goals turn work that takes hours into bounded, recoverable segments. The database preserves the goal checklist, continuation state, attempts, cooldowns, leases, and user input accepted while the worker is busy. After a single backend instance restarts, the supervisor reconciles the interrupted attempt, reads persisted checkpoints and artifacts, and schedules the next safe segment instead of asking you to repeat the task.
+
+For file-producing work, ask the employee to keep a progress ledger, append small verifiable units, inspect the existing tail after recovery, and complete the Goal only after reproducible acceptance checks pass. The runtime does not promise exactly-once behavior for arbitrary external side effects; payments, sends, publishes, and destructive calls still need provider idempotency or review. [Run and verify durable Goals →](https://claw.mate.vip/docs/en/goals)
+
+> Prompt pattern: “Create a persistent Goal first. Save the plan and progress in the workspace, write in small checkpoints, resume from existing evidence after errors or restart, and call `completeGoal` only after every criterion has verifiable evidence.”
+
### Team Runs (2.1.0+)
One request, one durable **Team Run**. A stable `runId` links the user's objective, task DAG, worker executions, final synthesis, and deliverables. Chat is the outcome surface, Agents Live groups the workers for real-time observation, and Teams owns history and governance — all three consume the same server projection. Worker conversations no longer flood the normal sidebar; summaries and files lead, while tasks, evidence, approvals, and read-only worker records drill down on demand. Underneath, the 2.0 shared board still provides dependency orchestration, parallel dispatch, prerequisite hand-off, execution leases, cancel-interrupt, and human approval gates.
diff --git a/README_zh.md b/README_zh.md
index febc524a..9eb8c66f 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -88,6 +88,13 @@ MateClaw 的 **LLM Wiki** 把它消化成结构化页面，页面之间自己长
### Agent Runtime：Native 或 DSH（2.2.0+）
`AgentRuntimeProvider` contract 把员工与实际执行回合的引擎分开。**Native Runtime** 在 MateClaw 内运行 ReAct、Plan-and-Execute、Persistent Goal 与 Team Run；**DSH Runtime** 把 `dsh-jsonrpc-agent` 作为认证子进程管理，并将思考、文本、工具调用、用量、完成与取消统一映射为 runtime event。DSH 掌管外部 Agent loop，MateClaw 继续掌管 session、workspace、凭证、工具、审批、消息和 UI 投影。启动前会校验 runtime 可用性与能力；控制台可完成 DSH 的安装、配置、校验、连接测试和启停。[配置 DeepSeek Harness →](https://claw.mate.vip/docs/zh/deepseek-harness)
+### 持久长任务：检查点、重启、继续（2.2.0+）
+Persistent Goal 把需要数小时的工作拆成有界、可恢复的执行段。数据库会保存目标清单、continuation 状态、attempt、冷却、lease，以及员工忙碌期间已经接收的用户输入。单后端实例重启后，supervisor 会先核对被中断的 attempt，读取持久检查点和已有产物，再调度下一段安全工作，不要求用户重新描述任务。
+
+对于写文件的任务，应要求员工维护进度账本、以小块追加可验证内容、恢复时先检查文件尾部，并且只有在可复现验收全部通过后才完成 Goal。运行时不承诺任意外部副作用严格一次；付款、发送、发布和破坏性操作仍需使用服务商幂等键或人工复核。[运行并验证持久目标 →](https://claw.mate.vip/docs/zh/goals)
+
+> 提示词模板：“第一步创建持续目标；把计划和进度保存在工作区；按小检查点写入；发生错误或重启后从已有证据继续；只有每条验收标准都有可验证证据时才调用 `completeGoal`。”
+
### Team Run（2.1.0+）
一次请求对应一个持久化的 **Team Run**。稳定的 `runId` 串起用户目标、任务 DAG、成员执行、最终汇总与交付物。Chat 是成果交付面，Agents Live 按运行聚合成员并展示实时状态，Teams 管理历史与治理；三处读取同一份服务端投影。成员子会话不再挤进普通会话列表，摘要和文件优先展示，任务、证据、审批与只读成员记录按需下钻。底层继续使用 2.0 的共享任务板，保留依赖编排、并行派发、前置结果传递、执行租约、取消中断和人工审批卡点。
diff --git a/mateclaw-desktop/package.json b/mateclaw-desktop/package.json
index e1fef6e5..1753a344 100644
--- a/mateclaw-desktop/package.json
+++ b/mateclaw-desktop/package.json
@@ -1,6 +1,6 @@
{
"name": "mateclaw-desktop",
- "version": "2.2.0",
+ "version": "2.3.0",
"description": "MateClaw Desktop - AI Assistant powered by Spring AI Alibaba",
"author": "MateClaw Team",
"license": "Apache-2.0",
diff --git a/mateclaw-plugin-api/src/main/java/vip/mate/plugin/api/memory/PluginMemoryProvider.java b/mateclaw-plugin-api/src/main/java/vip/mate/plugin/api/memory/PluginMemoryProvider.java
index b4b47833..7dd82d06 100644
--- a/mateclaw-plugin-api/src/main/java/vip/mate/plugin/api/memory/PluginMemoryProvider.java
+++ b/mateclaw-plugin-api/src/main/java/vip/mate/plugin/api/memory/PluginMemoryProvider.java
@@ -11,7 +11,7 @@ import java.util.List;
*
* @author MateClaw Team
*/
-public interface PluginMemoryProvider {
+public interface PluginMemoryProvider extends AutoCloseable {
/**
* Unique provider identifier, e.g. "vector_memory", "graph_memory".
@@ -114,4 +114,9 @@ public interface PluginMemoryProvider {
*/
default void onSessionEnd(Long agentId, String conversationId) {
}
+
+ /** Release provider-owned resources when the plugin is unloaded. */
+ @Override
+ default void close() {
+ }
}
diff --git a/mateclaw-plugin-mem0/src/main/java/vip/mate/plugin/mem0/Mem0Config.java b/mateclaw-plugin-mem0/src/main/java/vip/mate/plugin/mem0/Mem0Config.java
index ea7ae20e..1a424431 100644
--- a/mateclaw-plugin-mem0/src/main/java/vip/mate/plugin/mem0/Mem0Config.java
+++ b/mateclaw-plugin-mem0/src/main/java/vip/mate/plugin/mem0/Mem0Config.java
@@ -13,6 +13,7 @@ package vip.mate.plugin.mem0;
* @param syncEnabled whether syncTurn should POST to Mem0 /memories/
* @param maxResults cap on memories returned per recall
* @param timeoutMs HTTP timeout for both recall and sync
+ * @param syncQueueCapacity maximum number of turns waiting for asynchronous sync
* @author MateClaw Team
*/
record Mem0Config(
@@ -21,10 +22,18 @@ record Mem0Config(
boolean searchEnabled,
boolean syncEnabled,
int maxResults,
- int timeoutMs
+ int timeoutMs,
+ int syncQueueCapacity
) {
static final int DEFAULT_MAX_RESULTS = 5;
static final int DEFAULT_TIMEOUT_MS = 3000;
+ static final int DEFAULT_SYNC_QUEUE_CAPACITY = 256;
+
+ Mem0Config(String baseUrl, String apiKey, boolean searchEnabled, boolean syncEnabled,
+ int maxResults, int timeoutMs) {
+ this(baseUrl, apiKey, searchEnabled, syncEnabled, maxResults, timeoutMs,
+ DEFAULT_SYNC_QUEUE_CAPACITY);
+ }
/**
* Whether this provider should participate at all.
diff --git a/mateclaw-plugin-mem0/src/main/java/vip/mate/plugin/mem0/Mem0Exception.java b/mateclaw-plugin-mem0/src/main/java/vip/mate/plugin/mem0/Mem0Exception.java
index 064fffa3..5ba2c875 100644
--- a/mateclaw-plugin-mem0/src/main/java/vip/mate/plugin/mem0/Mem0Exception.java
+++ b/mateclaw-plugin-mem0/src/main/java/vip/mate/plugin/mem0/Mem0Exception.java
@@ -3,9 +3,8 @@ package vip.mate.plugin.mem0;
/**
* Raised when a Mem0 REST call fails (non-2xx response, IO error, timeout).
*
{@code systemPromptBlock} — no-op (returns ""), aligns with SessionSearchProvider
*
{@code prefetch(agentId, query, ownerKey)} — when {@code searchEnabled}
* and {@code ownerKey} is non-blank, calls {@code POST /memories/search/}
- * and returns a {@code [Mem0 Recall]} block. Returns "" on any failure
- * or when disabled.
+ * and returns a {@code [Mem0 Recall]} block. Failures propagate to the
+ * platform's timeout/circuit-breaker boundary.
*
{@code syncTurn(agentId, conversationId, messages, ownerKey)} — when
* {@code syncEnabled} and {@code ownerKey} is non-blank, asynchronously
* pushes the turn to {@code POST /memories/} under {@code user_id =
* ownerKey}, the same identifier prefetch recalls by. Failures are
- * logged and swallowed; never blocks the response path. The four-arg
+ * logged and swallowed; never blocks the response path. The bounded
+ * queue drops new writes when saturated. The four-arg
* variant (no ownerKey) skips — writing under any other identifier
* would produce memories that owner-scoped recall can never surface.
*
{@code getToolBeans} — empty (no agent-facing tools in v1)
@@ -34,8 +37,8 @@ import java.util.concurrent.Executors;
* When {@code ownerKey} is null/blank, both recall and sync are skipped — Mem0
* requires {@code user_id}.
*
- *
Asynchronous sync: a single-thread daemon executor is used
- * so that bursts of turns don't pile up on the platform's request thread.
+ *
Asynchronous sync: a single-thread daemon executor with a bounded queue
+ * prevents an unavailable Mem0 service from growing heap usage without limit.
*
* @author MateClaw Team
*/
@@ -46,21 +49,19 @@ class Mem0Provider implements PluginMemoryProvider {
private final Mem0Config config;
private final Mem0Client client;
private final Logger log;
- private final Executor async;
+ private final ThreadPoolExecutor async;
+ private final AtomicLong droppedSyncCount = new AtomicLong();
Mem0Provider(Mem0Config config, Mem0Client client, Logger log) {
this.config = config;
this.client = client;
this.log = log;
- // Single-thread executor is enough — syncTurn calls are sequential per
- // agent and not latency-sensitive; the platform's request thread must
- // not be blocked. A bounded single-thread queue keeps memory footprint
- // predictable even under burst load.
- this.async = Executors.newSingleThreadExecutor(r -> {
- Thread t = new Thread(r, "mem0-sync");
- t.setDaemon(true);
- return t;
- });
+ this.async = new ThreadPoolExecutor(1, 1, 0L, TimeUnit.MILLISECONDS,
+ new ArrayBlockingQueue<>(Math.max(1, config.syncQueueCapacity())), r -> {
+ Thread t = new Thread(r, "mem0-sync");
+ t.setDaemon(true);
+ return t;
+ }, new ThreadPoolExecutor.AbortPolicy());
}
@Override
@@ -104,20 +105,12 @@ class Mem0Provider implements PluginMemoryProvider {
if (userQuery == null || userQuery.isBlank()) {
return "";
}
- try {
- List memories = client.searchMemories(
- ownerKey, agentId == null ? null : agentId.toString(), userQuery);
- if (memories.isEmpty()) {
- return "";
- }
- return formatRecallBlock(memories);
- } catch (Exception e) {
- // Fault isolation: log and return empty so the platform falls back
- // to the other (local) providers without affecting the response.
- log.warn("[Mem0] prefetch failed for agent={} owner={}: {}",
- agentId, ownerKey, e.getMessage());
+ List memories = client.searchMemories(
+ ownerKey, agentId == null ? null : agentId.toString(), userQuery);
+ if (memories.isEmpty()) {
return "";
}
+ return formatRecallBlock(memories);
}
@Override
@@ -143,15 +136,52 @@ class Mem0Provider implements PluginMemoryProvider {
&& (assistantReply == null || assistantReply.isBlank())) {
return;
}
- CompletableFuture.runAsync(() -> {
- try {
- client.addMemories(ownerKey, agentId == null ? null : agentId.toString(),
- conversationId, userMessage, assistantReply);
- } catch (Exception e) {
- log.debug("[Mem0] syncTurn failed for agent={} owner={}: {}",
- agentId, ownerKey, e.getMessage());
+ try {
+ async.execute(() -> {
+ try {
+ client.addMemories(ownerKey, agentId == null ? null : agentId.toString(),
+ conversationId, userMessage, assistantReply);
+ } catch (Exception e) {
+ log.debug("[Mem0] syncTurn failed for agent={} owner={}: {}",
+ agentId, ownerKey, e.getMessage());
+ }
+ });
+ } catch (RejectedExecutionException e) {
+ long dropped = droppedSyncCount.incrementAndGet();
+ log.warn("[Mem0] sync queue full or provider closed; dropped turn for agent={} owner={} (totalDropped={})",
+ agentId, ownerKey, dropped);
+ }
+ }
+
+ int queuedSyncCount() {
+ return async.getQueue().size();
+ }
+
+ long droppedSyncCount() {
+ return droppedSyncCount.get();
+ }
+
+ boolean isClosed() {
+ return async.isShutdown();
+ }
+
+ @Override
+ public void close() {
+ async.shutdown();
+ List dropped = List.of();
+ try {
+ long drainMs = Math.min(1000L, Math.max(100L, config.timeoutMs()));
+ if (!async.awaitTermination(drainMs, TimeUnit.MILLISECONDS)) {
+ dropped = async.shutdownNow();
}
- }, async);
+ } catch (InterruptedException e) {
+ Thread.currentThread().interrupt();
+ dropped = async.shutdownNow();
+ }
+ if (!dropped.isEmpty()) {
+ droppedSyncCount.addAndGet(dropped.size());
+ log.warn("[Mem0] provider closed with {} queued sync turn(s) discarded", dropped.size());
+ }
}
@Override
diff --git a/mateclaw-plugin-mem0/src/main/resources/mateclaw-plugin.json b/mateclaw-plugin-mem0/src/main/resources/mateclaw-plugin.json
index a0e974a9..6a4a3f98 100644
--- a/mateclaw-plugin-mem0/src/main/resources/mateclaw-plugin.json
+++ b/mateclaw-plugin-mem0/src/main/resources/mateclaw-plugin.json
@@ -43,6 +43,12 @@
"required": false,
"secret": false,
"description": "HTTP timeout in milliseconds for both recall and sync. Default 3000."
+ },
+ "syncQueueCapacity": {
+ "type": "integer",
+ "required": false,
+ "secret": false,
+ "description": "Maximum pending asynchronous sync turns. New writes are dropped when full. Default 256."
}
}
}
diff --git a/mateclaw-plugin-mem0/src/test/java/vip/mate/plugin/mem0/Mem0ConfigTest.java b/mateclaw-plugin-mem0/src/test/java/vip/mate/plugin/mem0/Mem0ConfigTest.java
index f1d0a279..f3eb92b4 100644
--- a/mateclaw-plugin-mem0/src/test/java/vip/mate/plugin/mem0/Mem0ConfigTest.java
+++ b/mateclaw-plugin-mem0/src/test/java/vip/mate/plugin/mem0/Mem0ConfigTest.java
@@ -35,4 +35,10 @@ class Mem0ConfigTest {
Mem0Config c = new Mem0Config("http://localhost:8080", null, true, true, 5, 1000);
assertThat(c.normalizedBaseUrl()).isEqualTo("http://localhost:8080");
}
+
+ @Test
+ void legacyConstructorUsesBoundedQueueDefault() {
+ Mem0Config c = new Mem0Config("http://localhost:8080", null, true, true, 5, 1000);
+ assertThat(c.syncQueueCapacity()).isEqualTo(Mem0Config.DEFAULT_SYNC_QUEUE_CAPACITY);
+ }
}
diff --git a/mateclaw-plugin-mem0/src/test/java/vip/mate/plugin/mem0/Mem0PluginTest.java b/mateclaw-plugin-mem0/src/test/java/vip/mate/plugin/mem0/Mem0PluginTest.java
index b4f0739a..cb13d959 100644
--- a/mateclaw-plugin-mem0/src/test/java/vip/mate/plugin/mem0/Mem0PluginTest.java
+++ b/mateclaw-plugin-mem0/src/test/java/vip/mate/plugin/mem0/Mem0PluginTest.java
@@ -90,6 +90,7 @@ class Mem0PluginTest {
PluginContext ctx = new StubContext(config, registered) {
@Override
public void registerMemoryProvider(PluginMemoryProvider provider) {
+ registered.set(provider);
throw new PluginException("Only one external memory provider allowed");
}
};
@@ -98,6 +99,7 @@ class Mem0PluginTest {
assertThatThrownBy(() -> plugin.onLoad(ctx))
.isInstanceOf(PluginException.class)
.hasMessageContaining("Only one");
+ assertThat(((Mem0Provider) registered.get()).isClosed()).isTrue();
}
/**
diff --git a/mateclaw-plugin-mem0/src/test/java/vip/mate/plugin/mem0/Mem0ProviderTest.java b/mateclaw-plugin-mem0/src/test/java/vip/mate/plugin/mem0/Mem0ProviderTest.java
index 0a84d40d..37f0b2a4 100644
--- a/mateclaw-plugin-mem0/src/test/java/vip/mate/plugin/mem0/Mem0ProviderTest.java
+++ b/mateclaw-plugin-mem0/src/test/java/vip/mate/plugin/mem0/Mem0ProviderTest.java
@@ -14,8 +14,11 @@ import java.net.InetSocketAddress;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.atomic.AtomicReference;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
class Mem0ProviderTest {
@@ -43,6 +46,7 @@ class Mem0ProviderTest {
@AfterEach
void tearDown() {
+ if (provider != null) provider.close();
if (server != null) server.stop(0);
}
@@ -129,16 +133,15 @@ class Mem0ProviderTest {
}
@Test
- void threeArgPrefetch_returnsEmptyOnServerError() {
- // Replace handler to fail; the provider should swallow and return "".
+ void threeArgPrefetch_propagatesServerErrorToPlatformCircuitBreaker() {
server.removeContext("/");
server.createContext("/", ex -> {
ex.sendResponseHeaders(500, 0);
ex.close();
});
- String result = provider.prefetch(1L, "q", "user:42");
- assertThat(result).isEmpty();
+ assertThatThrownBy(() -> provider.prefetch(1L, "q", "user:42"))
+ .isInstanceOf(Mem0Exception.class);
}
@Test
@@ -215,5 +218,42 @@ class Mem0ProviderTest {
Mem0Provider p = new Mem0Provider(cfg, new Mem0Client(cfg), LoggerFactory.getLogger("test"));
assertThat(p.prefetch(1L, "q", "user:42")).isEmpty();
assertThat(searchCount.get()).isZero();
+ p.close();
+ }
+
+ @Test
+ void syncQueueIsBoundedAndCloseReleasesExecutor() throws Exception {
+ CountDownLatch firstStarted = new CountDownLatch(1);
+ CountDownLatch releaseFirst = new CountDownLatch(1);
+ AtomicInteger writes = new AtomicInteger();
+ Mem0Config cfg = new Mem0Config("http://localhost:8080", null,
+ false, true, 3, 3000, 1);
+ Mem0Client blockingClient = new Mem0Client(cfg) {
+ @Override
+ void addMemories(String userId, String agentId, String conversationId,
+ String userMessage, String assistantReply) {
+ writes.incrementAndGet();
+ firstStarted.countDown();
+ try {
+ releaseFirst.await(2, TimeUnit.SECONDS);
+ } catch (InterruptedException e) {
+ Thread.currentThread().interrupt();
+ }
+ }
+ };
+ Mem0Provider bounded = new Mem0Provider(cfg, blockingClient, LoggerFactory.getLogger("test"));
+ try {
+ bounded.syncTurn(1L, "one", "u", "a", "user:1");
+ assertThat(firstStarted.await(1, TimeUnit.SECONDS)).isTrue();
+ bounded.syncTurn(1L, "two", "u", "a", "user:1");
+ bounded.syncTurn(1L, "three", "u", "a", "user:1");
+
+ assertThat(bounded.queuedSyncCount()).isEqualTo(1);
+ assertThat(bounded.droppedSyncCount()).isEqualTo(1);
+ } finally {
+ releaseFirst.countDown();
+ bounded.close();
+ }
+ assertThat(bounded.isClosed()).isTrue();
}
}
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/AgentGraphBuilder.java b/mateclaw-server/src/main/java/vip/mate/agent/AgentGraphBuilder.java
index c4fe1b07..464c77fe 100644
--- a/mateclaw-server/src/main/java/vip/mate/agent/AgentGraphBuilder.java
+++ b/mateclaw-server/src/main/java/vip/mate/agent/AgentGraphBuilder.java
@@ -18,6 +18,7 @@ import org.springframework.stereotype.Component;
import vip.mate.agent.graph.StateGraphReActAgent;
import vip.mate.agent.graph.NodeStreamingChatHelper;
import vip.mate.agent.graph.executor.ToolExecutionExecutor;
+import vip.mate.execution.evidence.service.ExecutionEvidenceRecorder;
import vip.mate.agent.graph.edge.ObservationDispatcher;
import vip.mate.agent.graph.edge.ReasoningDispatcher;
import vip.mate.agent.graph.lifecycle.ReActLifecycleListener;
@@ -103,6 +104,13 @@ public class AgentGraphBuilder {
"${mateclaw.skill.disclosure.load-skill-tool.enabled:true}")
private boolean loadSkillToolEnabled;
+ private ExecutionEvidenceRecorder executionEvidenceRecorder;
+
+ @Autowired
+ public void setExecutionEvidenceRecorder(ExecutionEvidenceRecorder recorder) {
+ this.executionEvidenceRecorder = recorder;
+ }
+
/** Escape hatch: when false, the final answer is sent verbatim without Markdown normalization. */
@org.springframework.beans.factory.annotation.Value(
"${mate.agent.markdown-normalize-enabled:true}")
@@ -675,6 +683,7 @@ public class AgentGraphBuilder {
executor.setSkillRuntimeService(skillRuntimeService);
executor.setUsageRecencyTracker(toolUsageRecencyTracker);
executor.setProgressContext(progressContext);
+ executor.setExecutionEvidenceRecorder(executionEvidenceRecorder);
// Optional: route child-agent denied-tool audit events through
// the audit pipeline. Null when audit is not wired (legacy / test).
if (auditEventService != null) {
@@ -998,6 +1007,7 @@ public class AgentGraphBuilder {
executor.setSkillRuntimeService(skillRuntimeService);
executor.setUsageRecencyTracker(toolUsageRecencyTracker);
executor.setProgressContext(progressContext);
+ executor.setExecutionEvidenceRecorder(executionEvidenceRecorder);
// Optional: route child-agent denied-tool audit events through
// the audit pipeline. Null when audit is not wired (legacy / test).
if (auditEventService != null) {
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/AgentService.java b/mateclaw-server/src/main/java/vip/mate/agent/AgentService.java
index 0d83c1a6..b7b119d1 100644
--- a/mateclaw-server/src/main/java/vip/mate/agent/AgentService.java
+++ b/mateclaw-server/src/main/java/vip/mate/agent/AgentService.java
@@ -28,7 +28,6 @@ import vip.mate.workspace.conversation.repository.ConversationMapper;
import java.util.List;
import java.util.Locale;
-import java.time.Duration;
import java.util.Map;
import java.nio.file.Path;
import java.util.concurrent.ConcurrentHashMap;
@@ -90,6 +89,12 @@ public class AgentService {
@Autowired(required = false)
private vip.mate.agent.runtime.dsh.DshRuntimeService dshRuntimeService;
+ @Autowired
+ private vip.mate.agent.runtime.dsh.DshConversationHistory dshConversationHistory;
+
+ @Autowired(required = false)
+ private vip.mate.goal.service.GoalApprovalReplayStream goalApprovalReplay;
+
/**
* Runtime Agent instance cache. Keyed first by agentId, then by a model
* key, so a conversation that pins a non-default model gets its own graph
@@ -325,11 +330,11 @@ public class AgentService {
*/
public String chat(Long agentId, String message, String conversationId, ChatOrigin origin) {
clearAutoRecordedForNewTurn(conversationId);
- memoryRecallTracker.trackRecalls(agentId, message);
if (isDshAgent(agentId)) {
return collectChatResult(chatStructuredStream(agentId, message, conversationId,
"", null, origin != null ? origin : ChatOrigin.EMPTY)).content();
}
+ trackMemoryRecalls(agentId, message, origin);
BaseAgent agent = getOrBuildAgentForConversation(agentId, conversationId);
ChatOriginHolder.set(origin != null ? origin : ChatOrigin.EMPTY);
try {
@@ -366,13 +371,13 @@ public class AgentService {
public Flux chatStream(Long agentId, String message, String conversationId, ChatOrigin origin) {
clearAutoRecordedForNewTurn(conversationId);
- memoryRecallTracker.trackRecalls(agentId, message);
if (isDshAgent(agentId)) {
return chatStructuredStream(agentId, message, conversationId, "", null,
origin != null ? origin : ChatOrigin.EMPTY)
.filter(delta -> delta.content() != null)
.map(StreamDelta::content);
}
+ trackMemoryRecalls(agentId, message, origin);
BaseAgent agent = getOrBuildAgentForConversation(agentId, conversationId);
// Capture the origin into a request-scoped holder; cleared on Flux
// termination so the next reactive subscriber doesn't inherit stale state.
@@ -409,7 +414,7 @@ public class AgentService {
String requesterId, String thinkingLevel,
ChatOrigin origin) {
clearAutoRecordedForNewTurn(conversationId);
- memoryRecallTracker.trackRecalls(agentId, message);
+ trackMemoryRecalls(agentId, message, origin);
if (isDshAgent(agentId)) {
AgentEntity dshAgent = getAgent(agentId);
return withLifecycleFlux(agentId, message, conversationId,
@@ -418,7 +423,8 @@ public class AgentService {
dshAgent.getModelName(), dshWorkingDirectory(dshAgent),
dshWorkingDirectory(dshAgent)),
connection -> vip.mate.agent.runtime.RuntimeEventStreamAdapter.adapt(
- connection.prompt(msg)),
+ connection.prompt(dshConversationHistory.enrich(
+ convId, message, msg, origin))),
connection -> connection.close()),
StreamDelta::content)
.doFinally(signal -> ThinkingLevelHolder.clear());
@@ -469,7 +475,7 @@ public class AgentService {
public String execute(Long agentId, String goal, String conversationId, ChatOrigin origin) {
clearAutoRecordedForNewTurn(conversationId);
- memoryRecallTracker.trackRecalls(agentId, goal);
+ trackMemoryRecalls(agentId, goal, origin);
BaseAgent agent = getOrBuildAgentForConversation(agentId, conversationId);
ChatOriginHolder.set(origin != null ? origin : ChatOrigin.EMPTY);
try {
@@ -496,7 +502,7 @@ public class AgentService {
public String chatWithReplay(Long agentId, String userMessage, String conversationId,
String toolCallPayload, ChatOrigin origin) {
- memoryRecallTracker.trackRecalls(agentId, userMessage);
+ trackMemoryRecalls(agentId, userMessage, origin);
BaseAgent agent = getOrBuildAgentForConversation(agentId, conversationId);
ChatOriginHolder.set(origin != null ? origin : ChatOrigin.EMPTY);
try {
@@ -524,23 +530,7 @@ public class AgentService {
* {@code _usage_final} event for token and model attribution.
*/
private ChatResult collectChatResult(Flux stream) {
- StringBuilder content = new StringBuilder();
- final int[] usage = {0, 0};
- final String[] modelInfo = {null, null};
- stream.doOnNext(delta -> {
- if (delta.isEvent() && "_usage_final".equals(delta.eventType())) {
- Map data = delta.eventData();
- usage[0] = ((Number) data.getOrDefault("promptTokens", 0)).intValue();
- usage[1] = ((Number) data.getOrDefault("completionTokens", 0)).intValue();
- Object model = data.get("runtimeModelName");
- Object provider = data.get("runtimeProviderId");
- if (model != null) modelInfo[0] = model.toString();
- if (provider != null) modelInfo[1] = provider.toString();
- } else if (delta.content() != null) {
- content.append(delta.content());
- }
- }).blockLast(Duration.ofMinutes(10));
- return new ChatResult(content.toString(), usage[0], usage[1], modelInfo[0], modelInfo[1]);
+ return ChatResultCollector.collect(stream);
}
/**
@@ -560,9 +550,25 @@ public class AgentService {
public Flux chatWithReplayStream(Long agentId, String userMessage, String conversationId,
String toolCallPayload, String requesterId,
ChatOrigin origin) {
- memoryRecallTracker.trackRecalls(agentId, userMessage);
+ trackMemoryRecalls(agentId, userMessage, origin);
BaseAgent agent = getOrBuildAgentForConversation(agentId, conversationId);
ChatOrigin captured = origin != null ? origin : ChatOrigin.EMPTY;
+ if (goalApprovalReplay != null && goalApprovalReplay.applies(captured)) {
+ return Flux.using(() -> acquireTurn(conversationId), permit ->
+ goalApprovalReplay.replay(captured, toolCallPayload, fresh -> {
+ ChatOrigin previous = ChatOriginHolder.get();
+ ChatOriginHolder.set(fresh);
+ try {
+ return vip.mate.agent.context.GoalContinuationContext.call(true, () ->
+ invokeWithLifecycleFlux(agentId, userMessage, conversationId,
+ (msg, convId) -> agent.chatWithReplayStream(msg, convId, toolCallPayload,
+ requesterId != null ? requesterId : ""), StreamDelta::content));
+ } finally {
+ if (previous == ChatOrigin.EMPTY) ChatOriginHolder.clear();
+ else ChatOriginHolder.set(previous);
+ }
+ }), vip.mate.agent.runtime.ConversationTurnGate.Permit::close);
+ }
return Flux.defer(() -> {
ChatOriginHolder.set(captured);
return withLifecycleFlux(agentId, userMessage, conversationId,
@@ -772,6 +778,13 @@ public class AgentService {
return "dsh".equalsIgnoreCase(entity.getRuntimeType());
}
+ private void trackMemoryRecalls(Long agentId, String message, ChatOrigin origin) {
+ String ownerKey = memoryProperties.isLifecycleMediatorEnabled()
+ ? memoryOwnerResolver.resolve(origin != null ? origin : ChatOrigin.EMPTY)
+ : null;
+ memoryRecallTracker.trackRecalls(agentId, message, ownerKey);
+ }
+
private void validateDshConfiguration(AgentEntity agent) {
if (!"dsh".equalsIgnoreCase(agent.getRuntimeType())) return;
if (dshRuntimeService == null) {
@@ -970,10 +983,15 @@ public class AgentService {
* post-approval replays).
*/
public record ChatResult(String content, int promptTokens, int completionTokens,
- String runtimeModel, String runtimeProvider) {
+ String runtimeModel, String runtimeProvider, String finishReason) {
+
+ public ChatResult(String content, int promptTokens, int completionTokens,
+ String runtimeModel, String runtimeProvider) {
+ this(content, promptTokens, completionTokens, runtimeModel, runtimeProvider, null);
+ }
public static ChatResult contentOnly(String content) {
- return new ChatResult(content != null ? content : "", 0, 0, null, null);
+ return new ChatResult(content != null ? content : "", 0, 0, null, null, null);
}
}
}
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/ChatResultCollector.java b/mateclaw-server/src/main/java/vip/mate/agent/ChatResultCollector.java
new file mode 100644
index 00000000..e7bb0ab1
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/agent/ChatResultCollector.java
@@ -0,0 +1,39 @@
+package vip.mate.agent;
+
+import reactor.core.publisher.Flux;
+
+import java.time.Duration;
+import java.util.Map;
+
+/** Collapses a structured agent stream without discarding terminal metadata. */
+final class ChatResultCollector {
+
+ private ChatResultCollector() {
+ }
+
+ static AgentService.ChatResult collect(Flux stream) {
+ StringBuilder content = new StringBuilder();
+ final int[] usage = {0, 0};
+ final String[] modelInfo = {null, null};
+ final String[] finishReason = {null};
+ stream.doOnNext(delta -> {
+ if (delta.isEvent() && "_usage_final".equals(delta.eventType())) {
+ Map data = delta.eventData() != null ? delta.eventData() : Map.of();
+ usage[0] = ((Number) data.getOrDefault("promptTokens", 0)).intValue();
+ usage[1] = ((Number) data.getOrDefault("completionTokens", 0)).intValue();
+ Object model = data.get("runtimeModelName");
+ Object provider = data.get("runtimeProviderId");
+ if (model != null) modelInfo[0] = model.toString();
+ if (provider != null) modelInfo[1] = provider.toString();
+ } else if (delta.isEvent() && "finish_reason".equals(delta.eventType())) {
+ Map data = delta.eventData();
+ Object reason = data != null ? data.get("reason") : null;
+ if (reason != null) finishReason[0] = reason.toString();
+ } else if (delta.content() != null) {
+ content.append(delta.content());
+ }
+ }).blockLast(Duration.ofMinutes(10));
+ return new AgentService.ChatResult(content.toString(), usage[0], usage[1],
+ modelInfo[0], modelInfo[1], finishReason[0]);
+ }
+}
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/GraphEventPublisher.java b/mateclaw-server/src/main/java/vip/mate/agent/GraphEventPublisher.java
index 1a0bd842..6c67bc91 100644
--- a/mateclaw-server/src/main/java/vip/mate/agent/GraphEventPublisher.java
+++ b/mateclaw-server/src/main/java/vip/mate/agent/GraphEventPublisher.java
@@ -160,8 +160,14 @@ public final class GraphEventPublisher {
public static GraphEvent toolApprovalRequested(String pendingId, String toolName,
String arguments, String reason) {
+ return toolApprovalRequested(null, pendingId, toolName, arguments, reason);
+ }
+
+ public static GraphEvent toolApprovalRequested(String toolCallId, String pendingId, String toolName,
+ String arguments, String reason) {
long ts = System.currentTimeMillis();
return new GraphEvent(EVENT_TOOL_APPROVAL_REQUESTED, Map.of(
+ "toolCallId", toolCallId != null ? toolCallId : "",
"pendingId", pendingId,
"toolName", toolName != null ? toolName : "",
"arguments", arguments != null ? arguments : "",
@@ -177,8 +183,16 @@ public final class GraphEventPublisher {
String arguments, String reason,
String summary, String maxSeverity,
List> findings) {
+ return toolApprovalRequested(null, pendingId, toolName, arguments, reason, summary, maxSeverity, findings);
+ }
+
+ public static GraphEvent toolApprovalRequested(String toolCallId, String pendingId, String toolName,
+ String arguments, String reason,
+ String summary, String maxSeverity,
+ List> findings) {
long ts = System.currentTimeMillis();
java.util.Map data = new java.util.LinkedHashMap<>();
+ data.put("toolCallId", toolCallId != null ? toolCallId : "");
data.put("pendingId", pendingId);
data.put("toolName", toolName != null ? toolName : "");
data.put("arguments", arguments != null ? arguments : "");
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/binding/service/AgentBindingService.java b/mateclaw-server/src/main/java/vip/mate/agent/binding/service/AgentBindingService.java
index 2596faec..bbc28df1 100644
--- a/mateclaw-server/src/main/java/vip/mate/agent/binding/service/AgentBindingService.java
+++ b/mateclaw-server/src/main/java/vip/mate/agent/binding/service/AgentBindingService.java
@@ -730,6 +730,10 @@ public class AgentBindingService implements AgentBindingResolver {
"addGoalCriterion",
"completeGoal",
"getGoalStatus",
+ // User-selected managed JSON protocol, authorized again inside each tool service.
+ "getManagedGoalJsonSlots",
+ "publishManagedGoalJson",
+ "checkManagedGoalJson",
"waitForGoalInput",
// Conversation-scoped progress ledger — same rationale as the
// goal primitives above. Long multi-step research / drafting
@@ -769,6 +773,7 @@ public class AgentBindingService implements AgentBindingResolver {
"read_file",
"send_file",
"write_file",
+ "append_file",
"edit_file",
"execute_shell_command",
// Inline code execution — an agent-wide capability alongside shell.
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/context/ChatOrigin.java b/mateclaw-server/src/main/java/vip/mate/agent/context/ChatOrigin.java
index 0e4e2035..760796b7 100644
--- a/mateclaw-server/src/main/java/vip/mate/agent/context/ChatOrigin.java
+++ b/mateclaw-server/src/main/java/vip/mate/agent/context/ChatOrigin.java
@@ -5,6 +5,7 @@ import org.springframework.ai.chat.model.ToolContext;
import org.springframework.lang.Nullable;
import java.util.Map;
+import java.util.Objects;
/**
* Immutable value object that travels alongside an agent invocation describing
@@ -76,9 +77,37 @@ public record ChatOrigin(
* from "this is an external/anonymous identifier" (RFC: identity typing).
*/
@Nullable Long requesterUserId,
- @Nullable Long originMessageId
+ @Nullable Long originMessageId,
+ @Nullable ExecutionAttribution executionAttribution,
+ /** Managed Goal captured for this turn: null=legacy unknown, 0=observed unselected. */
+ @Nullable Long selectedGoalId
) {
+ public ChatOrigin(@Nullable Long agentId, @Nullable String conversationId,
+ @Nullable String requesterId, @Nullable Long workspaceId,
+ @Nullable String workspaceBasePath, @Nullable Long channelId,
+ @Nullable ChannelTarget channelTarget, boolean cronOrigin,
+ @Nullable String senderName, @Nullable String channelType,
+ @Nullable String chatId, @Nullable String baseUrl,
+ @Nullable Long requesterUserId, @Nullable Long originMessageId,
+ @Nullable ExecutionAttribution executionAttribution) {
+ this(agentId, conversationId, requesterId, workspaceId, workspaceBasePath,
+ channelId, channelTarget, cronOrigin, senderName, channelType,
+ chatId, baseUrl, requesterUserId, originMessageId, executionAttribution, null);
+ }
+
+ public ChatOrigin(@Nullable Long agentId, @Nullable String conversationId,
+ @Nullable String requesterId, @Nullable Long workspaceId,
+ @Nullable String workspaceBasePath, @Nullable Long channelId,
+ @Nullable ChannelTarget channelTarget, boolean cronOrigin,
+ @Nullable String senderName, @Nullable String channelType,
+ @Nullable String chatId, @Nullable String baseUrl,
+ @Nullable Long requesterUserId, @Nullable Long originMessageId) {
+ this(agentId, conversationId, requesterId, workspaceId, workspaceBasePath,
+ channelId, channelTarget, cronOrigin, senderName, channelType,
+ chatId, baseUrl, requesterUserId, originMessageId, null);
+ }
+
public ChatOrigin(@Nullable Long agentId, @Nullable String conversationId,
@Nullable String requesterId, @Nullable Long workspaceId,
@Nullable String workspaceBasePath, @Nullable Long channelId,
@@ -149,27 +178,32 @@ public record ChatOrigin(
public ChatOrigin withAgent(@Nullable Long newAgentId) {
return new ChatOrigin(newAgentId, conversationId, requesterId,
workspaceId, workspaceBasePath, channelId, channelTarget, cronOrigin,
- senderName, channelType, chatId, baseUrl, requesterUserId, originMessageId);
+ senderName, channelType, chatId, baseUrl, requesterUserId, originMessageId,
+ executionAttribution, selectedGoalId);
}
public ChatOrigin withWorkspace(@Nullable Long newWorkspaceId,
@Nullable String newWorkspaceBasePath) {
return new ChatOrigin(agentId, conversationId, requesterId,
newWorkspaceId, newWorkspaceBasePath, channelId, channelTarget, cronOrigin,
- senderName, channelType, chatId, baseUrl, requesterUserId, originMessageId);
+ senderName, channelType, chatId, baseUrl, requesterUserId, originMessageId,
+ executionAttribution, selectedGoalId);
}
public ChatOrigin withConversationId(@Nullable String newConversationId) {
return new ChatOrigin(agentId, newConversationId, requesterId,
workspaceId, workspaceBasePath, channelId, channelTarget, cronOrigin,
- senderName, channelType, chatId, baseUrl, requesterUserId, originMessageId);
+ senderName, channelType, chatId, baseUrl, requesterUserId, originMessageId,
+ Objects.equals(conversationId, newConversationId) ? executionAttribution : null,
+ selectedGoalId);
}
/** Carry a request-derived public base URL (see {@link #baseUrl()}). */
public ChatOrigin withBaseUrl(@Nullable String newBaseUrl) {
return new ChatOrigin(agentId, conversationId, requesterId,
workspaceId, workspaceBasePath, channelId, channelTarget, cronOrigin,
- senderName, channelType, chatId, newBaseUrl, requesterUserId, originMessageId);
+ senderName, channelType, chatId, newBaseUrl, requesterUserId, originMessageId,
+ executionAttribution, selectedGoalId);
}
/**
@@ -183,13 +217,34 @@ public record ChatOrigin(
@Nullable String newChatId) {
return new ChatOrigin(agentId, conversationId, requesterId,
workspaceId, workspaceBasePath, channelId, channelTarget, cronOrigin,
- newSenderName, newChannelType, newChatId, baseUrl, requesterUserId, originMessageId);
+ newSenderName, newChannelType, newChatId, baseUrl, requesterUserId, originMessageId,
+ executionAttribution, selectedGoalId);
}
public ChatOrigin withOriginMessageId(@Nullable Long newOriginMessageId) {
return new ChatOrigin(agentId, conversationId, requesterId,
workspaceId, workspaceBasePath, channelId, channelTarget, cronOrigin,
- senderName, channelType, chatId, baseUrl, requesterUserId, newOriginMessageId);
+ senderName, channelType, chatId, baseUrl, requesterUserId, newOriginMessageId,
+ executionAttribution, selectedGoalId);
+ }
+
+ public ChatOrigin withApprovalId(String pendingId) {
+ ExecutionAttribution attribution = executionAttribution == null
+ ? new ExecutionAttribution(null, null, null, pendingId, null)
+ : executionAttribution.withApproval(pendingId);
+ return withExecutionAttribution(attribution);
+ }
+
+ public ChatOrigin withExecutionAttribution(ExecutionAttribution attribution) {
+ return new ChatOrigin(agentId, conversationId, requesterId, workspaceId, workspaceBasePath,
+ channelId, channelTarget, cronOrigin, senderName, channelType, chatId, baseUrl,
+ requesterUserId, originMessageId, attribution, selectedGoalId);
+ }
+
+ public ChatOrigin withSelectedGoalId(@Nullable Long goalId) {
+ return new ChatOrigin(agentId, conversationId, requesterId, workspaceId, workspaceBasePath,
+ channelId, channelTarget, cronOrigin, senderName, channelType, chatId, baseUrl,
+ requesterUserId, originMessageId, executionAttribution, goalId);
}
// ---------------- Spring AI ToolContext interop ----------------
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/context/ConversationWindowManager.java b/mateclaw-server/src/main/java/vip/mate/agent/context/ConversationWindowManager.java
index db0a2ae8..34b9f0a3 100644
--- a/mateclaw-server/src/main/java/vip/mate/agent/context/ConversationWindowManager.java
+++ b/mateclaw-server/src/main/java/vip/mate/agent/context/ConversationWindowManager.java
@@ -1410,6 +1410,17 @@ public class ConversationWindowManager {
ChatResponse response = chatModel.call(new Prompt(promptMessages, options));
if (response != null && response.getResult() != null
&& response.getResult().getOutput() != null) {
+ String finishReason = response.getResult().getMetadata() != null
+ ? response.getResult().getMetadata().getFinishReason() : null;
+ if ("length".equalsIgnoreCase(finishReason)) {
+ // A non-empty response can still be structurally incomplete
+ // when the provider exhausts max tokens. Persisting it would
+ // poison every later iterative summary.
+ log.warn("[ConversationWindow] LLM 摘要因 token 上限被截断，丢弃结果, conv={}",
+ conversationId);
+ setSummaryCooldown(conversationId);
+ return null;
+ }
String summary = response.getResult().getOutput().getText();
if (summary != null && !summary.isBlank()) {
// 成功：保存摘要供下次迭代更新，清除冷却
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/context/ExecutionAttribution.java b/mateclaw-server/src/main/java/vip/mate/agent/context/ExecutionAttribution.java
new file mode 100644
index 00000000..04978c8c
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/agent/context/ExecutionAttribution.java
@@ -0,0 +1,12 @@
+package vip.mate.agent.context;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+
+/** Server-issued execution linkage. This record is never a tool argument or an HTTP request body. */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public record ExecutionAttribution(Long goalId, String goalAttemptId, Long cronRunId,
+ String approvalId, String ownerFence) {
+ public ExecutionAttribution withApproval(String pendingId) {
+ return new ExecutionAttribution(goalId, goalAttemptId, cronRunId, pendingId, ownerFence);
+ }
+}
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/graph/NodeStreamingChatHelper.java b/mateclaw-server/src/main/java/vip/mate/agent/graph/NodeStreamingChatHelper.java
index ada8e499..7b31185b 100644
--- a/mateclaw-server/src/main/java/vip/mate/agent/graph/NodeStreamingChatHelper.java
+++ b/mateclaw-server/src/main/java/vip/mate/agent/graph/NodeStreamingChatHelper.java
@@ -26,6 +26,7 @@ import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.util.ArrayList;
import java.util.List;
+import java.util.Locale;
import java.util.Map;
import java.util.concurrent.CancellationException;
import java.util.concurrent.CountDownLatch;
@@ -554,6 +555,7 @@ public class NodeStreamingChatHelper {
// ("credit balance is too low") use these phrases in 402-class responses.
// Chinese provider patterns (Zhipu 1113, DashScope, general) — same hard
// failure semantics: retrying the same provider won't refill the balance.
+ String lowerMsg = msg.toLowerCase(Locale.ROOT);
if (msg.contains("402") || msg.contains("insufficient_quota")
|| msg.contains("credit balance is too low")
|| msg.contains("billing_error") || msg.contains("billing_hard_limit_reached")
@@ -562,7 +564,13 @@ public class NodeStreamingChatHelper {
|| msg.contains("余额不足") || msg.contains("请充值")
|| msg.contains("\"code\":\"1113\"") || msg.contains("\"code\":1113")
|| msg.contains("AccountBalanceNotEnough")
- || msg.contains("balance not enough")) {
+ || msg.contains("balance not enough")
+ || lowerMsg.contains("invalidsubscription")
+ || lowerMsg.contains("subscription has expired")
+ || lowerMsg.contains("arrearage")
+ || lowerMsg.contains("account is in good standing")
+ || lowerMsg.contains("insufficient_balance")
+ || lowerMsg.contains("insufficient balance")) {
return ErrorType.BILLING;
}
// RFC-009 P3.2: MODEL_NOT_FOUND — provider rejects the requested model id.
@@ -1169,6 +1177,7 @@ public class NodeStreamingChatHelper {
List toolCallAccumulators = new ArrayList<>();
AtomicReference lastAssistantMessage = new AtomicReference<>();
AtomicReference errorRef = new AtomicReference<>();
+ AtomicReference finishReason = new AtomicReference<>();
AtomicInteger promptTokens = new AtomicInteger(0);
AtomicInteger completionTokens = new AtomicInteger(0);
// Prompt cache / reasoning counters; providers that don't report them stay 0.
@@ -1284,6 +1293,11 @@ public class NodeStreamingChatHelper {
return;
}
var generation = chatResponse.getResult();
+ if (generation.getMetadata() != null
+ && generation.getMetadata().getFinishReason() != null
+ && !generation.getMetadata().getFinishReason().isBlank()) {
+ finishReason.set(generation.getMetadata().getFinishReason());
+ }
AssistantMessage msg = generation.getOutput();
lastAssistantMessage.set(msg);
@@ -1572,7 +1586,10 @@ public class NodeStreamingChatHelper {
// ===== 成功（检查是否因 thinking-only 软上限或内容重复被截断） =====
boolean truncatedByThinkingCap = thinkingOnlyCapTriggered.get();
boolean truncatedByContentRepeat = contentRepeatCapTriggered.get();
- boolean truncated = truncatedByThinkingCap || truncatedByContentRepeat;
+ boolean thinkingTokenLimit = "length".equalsIgnoreCase(finishReason.get())
+ && thinkingAccum.length() > 0 && contentAccum.toString().isBlank()
+ && toolCallAccumulators.isEmpty();
+ boolean truncated = truncatedByThinkingCap || truncatedByContentRepeat || thinkingTokenLimit;
if (truncatedByThinkingCap) {
log.warn("[{}] LLM stream disposed: thinking-only soft cap reached for conversation {}",
phase, conversationId);
@@ -1601,6 +1618,7 @@ public class NodeStreamingChatHelper {
String truncationReason = truncatedByThinkingCap ? "thinking_only_no_content"
: truncatedByContentRepeat ? "content_repetition"
+ : thinkingTokenLimit ? "thinking_token_limit"
: null;
return assembleResult(contentAccum, thinkingAccum, toolCallAccumulators,
promptTokens.get(), completionTokens.get(),
@@ -2028,9 +2046,26 @@ public class NodeStreamingChatHelper {
|| combined.contains("model not found") || combined.contains("not_found_error")) {
return "Model name not available on this provider — verify the model exists and is supported (Settings → Models)";
}
+ // Do not mislabel unsupported model parameters as image errors (#640).
+ // Only emit known parameter names and fixed guidance, never raw response
+ // bodies, which may contain credentials or echoed conversation content.
+ String lowerError = combined.toLowerCase(java.util.Locale.ROOT);
+ if (lowerError.contains("unsupported parameter") || lowerError.contains("unsupported_parameter")
+ || lowerError.contains("unsupported value") || lowerError.contains("unsupported_value")) {
+ if (lowerError.contains("max_tokens") && lowerError.contains("max_completion_tokens")) {
+ return "模型不支持 max_tokens，请改用 max_completion_tokens。请更新 MateClaw，并检查模型及提供商生成参数配置。";
+ }
+ for (String parameter : java.util.List.of("max_completion_tokens", "max_tokens", "temperature", "top_p",
+ "reasoning_effort", "stream_options", "parallel_tool_calls", "tool_choice", "response_format")) {
+ if (lowerError.contains(parameter)) {
+ return "模型不支持生成参数或参数值：" + parameter + "。请检查模型及提供商生成参数配置。";
+ }
+ }
+ return "模型不支持当前生成参数或参数值，请检查模型及提供商生成参数配置。";
+ }
// 对 Jackson 反序列化错误，提取关键信息
if (msg.contains("engine_overloaded")) return "Model service overloaded, please retry later";
- if (msg.contains("unsupported image format") || msg.contains("unsupported")) return "Unsupported file format (e.g. SVG), use PNG/JPG instead";
+ if (lowerError.contains("unsupported image format")) return "Unsupported file format (e.g. SVG), use PNG/JPG instead";
if (msg.contains("invalid_request_error") || msg.contains("400 Bad Request")) return "Bad request, please check input";
if (msg.contains("rate_limit") || msg.contains("429")) return "Rate limit exceeded, please retry later";
if (msg.contains("timeout") || msg.contains("Timeout")) return "Request timeout, please retry";
@@ -2509,11 +2544,41 @@ public class NodeStreamingChatHelper {
acc.id,
acc.type != null ? acc.type : "function",
acc.name,
- sanitizeToolCallArguments(acc.name, acc.arguments.toString())));
+ toolCallArgumentsForExecution(acc.name, acc.arguments.toString())));
}
return result;
}
+ /**
+ * Finalize a streamed tool call for local execution.
+ *
+ *
Blank arguments are a common zero-argument representation and remain
+ * normalized to an empty object. Invalid non-blank JSON, however, must be
+ * preserved until {@code ToolExecutionExecutor} sees it; replacing it with
+ * {@code {}} loses the distinction between a truncated stream and a real
+ * empty call and can execute the wrong operation. The outgoing-history
+ * normalization path still calls {@link #sanitizeToolCallArguments} before
+ * a later provider request.
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/graph/StateGraphReActAgent.java b/mateclaw-server/src/main/java/vip/mate/agent/graph/StateGraphReActAgent.java
index 8b6a98ef..2d08592e 100644
--- a/mateclaw-server/src/main/java/vip/mate/agent/graph/StateGraphReActAgent.java
+++ b/mateclaw-server/src/main/java/vip/mate/agent/graph/StateGraphReActAgent.java
@@ -700,6 +700,10 @@ public class StateGraphReActAgent extends BaseAgent implements StructuredStreamC
goalService.findActiveByConversation(conversationId);
if (active != null) {
inputs.put(MateClawStateKeys.ACTIVE_GOAL, active);
+ if (active.isJsonAcceptanceRequired()) {
+ inputs.put(SYSTEM_PROMPT, inputs.get(SYSTEM_PROMPT) + "\n\n"
+ + vip.mate.goal.service.GoalJsonProtocolHints.INSTRUCTIONS);
+ }
}
} catch (Exception e) {
log.warn("[{}] findActiveByConversation failed: {}", agentName, e.getMessage());
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolCallDeadline.java b/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolCallDeadline.java
new file mode 100644
index 00000000..c78f6800
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolCallDeadline.java
@@ -0,0 +1,60 @@
+package vip.mate.agent.graph.executor;
+
+import java.util.concurrent.ScheduledFuture;
+import java.util.concurrent.ScheduledThreadPoolExecutor;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+import java.util.function.Supplier;
+
+/** Interrupts cooperative callbacks in place, preserving their thread-local context. */
+final class ToolCallDeadline {
+ private static final ScheduledThreadPoolExecutor TIMER = new ScheduledThreadPoolExecutor(
+ 1, Thread.ofPlatform().daemon().name("tool-deadline-", 0).factory());
+
+ static {
+ TIMER.setRemoveOnCancelPolicy(true);
+ }
+
+ private final Thread owner = Thread.currentThread();
+ private boolean active = true;
+ private boolean expired;
+
+ private synchronized void expire() {
+ if (active) {
+ expired = true;
+ owner.interrupt();
+ }
+ }
+
+ private synchronized boolean finish() {
+ active = false;
+ return expired;
+ }
+
+ static T call(String toolName, long timeoutMs, Supplier callback) throws TimeoutException {
+ ToolCallDeadline deadline = new ToolCallDeadline();
+ ScheduledFuture timer = TIMER.schedule(deadline::expire, Math.max(1L, timeoutMs), TimeUnit.MILLISECONDS);
+ try {
+ T result = callback.get();
+ if (deadline.finish()) throw timeout(toolName, timeoutMs);
+ return result;
+ } catch (RuntimeException failure) {
+ if (deadline.finish()) {
+ TimeoutException timeout = timeout(toolName, timeoutMs);
+ timeout.initCause(failure);
+ throw timeout;
+ }
+ throw failure;
+ } finally {
+ // Synchronize with the timer before this thread can execute another
+ // tool. Never leave a late watchdog interrupt on a reused worker.
+ boolean expired = deadline.finish();
+ timer.cancel(false);
+ if (expired) Thread.interrupted();
+ }
+ }
+
+ private static TimeoutException timeout(String name, long timeoutMs) {
+ return new TimeoutException("Tool " + name + " timed out after " + timeoutMs + "ms");
+ }
+}
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolExecutionExecutor.java b/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolExecutionExecutor.java
index 9e0f0663..99a5e3fe 100644
--- a/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolExecutionExecutor.java
+++ b/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolExecutionExecutor.java
@@ -15,6 +15,7 @@ import vip.mate.tool.mcp.runtime.ProgressAwareMcpToolCallback;
import vip.mate.agent.AgentToolSet;
import vip.mate.agent.GraphEventPublisher;
import vip.mate.agent.context.ChatOrigin;
+import vip.mate.execution.evidence.service.ExecutionEvidenceRecorder;
import vip.mate.agent.context.StructuredTruncator;
import vip.mate.agent.graph.state.DirectToolOutput;
import vip.mate.agent.graph.state.SourceEvidenceLedger;
@@ -85,7 +86,7 @@ public class ToolExecutionExecutor {
static final int MAX_TOOL_CALLS_PER_RESPONSE = 16;
private static final Set DEFAULT_UNSAFE_TOOLS = Set.of(
- "browser_use", "BrowserUseTool", "write_file", "edit_file"
+ "browser_use", "BrowserUseTool", "write_file", "append_file", "edit_file"
);
/**
@@ -483,6 +484,9 @@ public class ToolExecutionExecutor {
ChatOrigin origin,
Set loadedSkills) {
ChatOrigin safeOrigin = origin != null ? origin : ChatOrigin.EMPTY;
+ if (!isReplay && safeOrigin.executionAttribution() != null) {
+ safeOrigin = safeOrigin.withApprovalId(null);
+ }
if (isBlank(safeOrigin.conversationId()) && !isBlank(conversationId)) {
safeOrigin = safeOrigin.withConversationId(conversationId);
}
@@ -614,7 +618,7 @@ public class ToolExecutionExecutor {
} catch (Exception jsonEx) {
log.warn("[ToolExecutor] Tool {} arguments invalid/truncated JSON (len={}): {}",
toolName, arguments.length(), jsonEx.getMessage());
- String truncationError = normalizeToolExecutionError(jsonEx);
+ String truncationError = incompleteToolArgumentsError(toolName);
events.add(GraphEventPublisher.toolComplete(toolCall.id(), toolName, truncationError, false));
allResponses.add(new ToolResponseMessage.ToolResponse(
toolCall.id(), responseName, truncationError));
@@ -701,7 +705,7 @@ public class ToolExecutionExecutor {
// 4. 分类: concurrencySafe
boolean safe = isConcurrencySafe(toolName);
preparedCalls.add(new PreparedToolCall(toolCall, responseName, callback, arguments, safe, allResponses.size(),
- conversationId, requesterId, workspaceBasePath, safeOrigin, rawEvidenceRef));
+ conversationId, requesterId, workspaceBasePath, safeOrigin, UUID.randomUUID().toString(), rawEvidenceRef));
// 占位，Phase 2 填充
allResponses.add(null);
}
@@ -730,6 +734,17 @@ public class ToolExecutionExecutor {
rawEvidenceRef.get());
}
+ private static String incompleteToolArgumentsError(String toolName) {
+ var error = OBJECT_MAPPER.createObjectNode();
+ error.put("error", true);
+ error.put("code", "TOOL_ARGUMENTS_INCOMPLETE");
+ error.put("recoverable", true);
+ error.put("toolName", toolName == null ? "" : toolName);
+ error.put("message", "Tool arguments were incomplete or invalid JSON; the tool was not executed.");
+ error.put("hint", "Retry with a smaller payload. For file updates, prefer edit_file or append_file instead of rewriting the whole file.");
+ return error.toString();
+ }
+
private static String requestedSkillName(String arguments) {
if (arguments == null || arguments.isBlank()) {
return null;
@@ -780,6 +795,15 @@ public class ToolExecutionExecutor {
List events,
String conversationId, String workspaceBasePath,
List directOutputs) {
+ return executePreApproved(toolCall, storedArguments, events, conversationId, workspaceBasePath,
+ directOutputs, ChatOrigin.EMPTY);
+ }
+
+ public ToolResponseMessage.ToolResponse executePreApproved(
+ AssistantMessage.ToolCall toolCall, String storedArguments,
+ List events,
+ String conversationId, String workspaceBasePath,
+ List directOutputs, ChatOrigin origin) {
String toolName = resolveToolName(toolCall.name());
String callArguments = storedArguments != null ? storedArguments : toolCall.arguments();
@@ -815,10 +839,11 @@ public class ToolExecutionExecutor {
// Origin is method-local (see thread-safety note on execute());
// the legacy ThreadLocal that used to carry it across executePreApproved
// calls was a cross-conversation footgun and has been removed.
- ChatOrigin replayOrigin = ChatOrigin.EMPTY
- .withConversationId(conversationId)
- .withWorkspace(null, workspaceBasePath);
- String result = callback.call(callArguments, toolContextWithScopedCatalog(replayOrigin));
+ ChatOrigin replayOrigin = (origin == null ? ChatOrigin.EMPTY : origin)
+ .withConversationId(conversationId);
+ replayOrigin = replayOrigin.withWorkspace(replayOrigin.workspaceId(), workspaceBasePath);
+ String result = invokeObserved(callback, callArguments, toolContextWithScopedCatalog(replayOrigin),
+ UUID.randomUUID().toString(), toolCall.id());
throwIfStopRequested(conversationId);
int rawLen = result != null ? result.length() : 0;
@@ -1066,7 +1091,7 @@ public class ToolExecutionExecutor {
toolContext = new ToolContext(ctxMap);
}
- result = pc.callback.call(pc.arguments, toolContext);
+ result = invokeObserved(pc.callback, pc.arguments, toolContext, pc.invocationKey, pc.toolCall.id());
throwIfStopRequested(pc.conversationId);
} finally {
if (progressToken != null) {
@@ -1271,7 +1296,7 @@ public class ToolExecutionExecutor {
ToolExecutionGuardHelper.ApprovalRequest approval = ToolExecutionGuardHelper.handleToolApproval(
toolCall, toolName, arguments, evaluation,
conversationId, agentId, requesterId, approvalService, streamTracker,
- events, remaining);
+ events, remaining, origin);
toolGuardService.recordApprovalAudit(guardCtx, evaluation, approval.pendingId(), autoOutcome);
return GuardDecision.needsApproval(approval.response(), approval.pendingId());
}
@@ -1293,7 +1318,7 @@ public class ToolExecutionExecutor {
String approvalResponse = ToolExecutionGuardHelper.handleToolApprovalLegacy(
toolCall, toolName, arguments, guardResult,
conversationId, agentId, requesterId, approvalService, streamTracker,
- events, remaining);
+ events, remaining, origin);
// Legacy path never persisted a pendingId to carry here; the value
// is unused downstream (only the boolean awaitingApproval is read).
return GuardDecision.needsApproval(approvalResponse, null);
@@ -1761,6 +1786,20 @@ public class ToolExecutionExecutor {
return new ToolContext(context);
}
+ private ExecutionEvidenceRecorder executionEvidenceRecorder;
+
+ public void setExecutionEvidenceRecorder(ExecutionEvidenceRecorder recorder) {
+ this.executionEvidenceRecorder = recorder;
+ }
+
+ private String invokeObserved(ToolCallback callback, String arguments, ToolContext context,
+ String invocationKey, String providerCallId) throws TimeoutException {
+ String toolName = callback.getToolDefinition().name();
+ return ToolCallDeadline.call(toolName, getToolTimeoutMs(toolName),
+ () -> executionEvidenceRecorder == null ? callback.call(arguments, context)
+ : executionEvidenceRecorder.invoke(callback, arguments, context, invocationKey, providerCallId));
+ }
+
// ==================== 内部数据类 ====================
private record PreparedToolCall(
@@ -1774,6 +1813,7 @@ public class ToolExecutionExecutor {
String requesterId,
String workspaceBasePath,
ChatOrigin origin,
+ String invocationKey,
/**
* Shared reference (one per execute() invocation) where each
* concurrent {@code executeSingleTool} merges a {@link SourceEvidenceLedger}
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/graph/node/ActionNode.java b/mateclaw-server/src/main/java/vip/mate/agent/graph/node/ActionNode.java
index 8423ae04..fda80429 100644
--- a/mateclaw-server/src/main/java/vip/mate/agent/graph/node/ActionNode.java
+++ b/mateclaw-server/src/main/java/vip/mate/agent/graph/node/ActionNode.java
@@ -61,7 +61,7 @@ public class ActionNode implements NodeAction {
/**
* Tools whose results should NOT be auto-recorded into the ledger.
- * Two groups:
+ * Three groups:
*
*
Meta-tools (load_skill, enable_tool, progress_update,
* skill helpers) — they either have their own ledger side-effects
@@ -72,6 +72,8 @@ public class ActionNode implements NodeAction {
* answer follow-up questions from stale output instead of
* re-checking, because the snapshot instructs "已完成的步骤不要
* 重复执行".
+ *
Time-bound verification — managed JSON bindings may need
+ * a new check during the same loop after a goal definition changes.
*
*/
private static final Set AUTO_RECORD_SKIP = Set.of(
@@ -82,7 +84,9 @@ public class ActionNode implements NodeAction {
"extract_document_text", "extract_pdf_text", "extract_docx_text",
"detect_file_type",
"getCurrentDateTime", "getCurrentDate", "getCurrentTime",
- "listSubagents"
+ "listSubagents", "getManagedGoalJsonSlots",
+ // A binding is time-bound and can need refreshing during this same tool loop.
+ "checkManagedGoalJson"
);
private final ToolExecutionExecutor executor;
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/graph/node/GoalEvaluationNode.java b/mateclaw-server/src/main/java/vip/mate/agent/graph/node/GoalEvaluationNode.java
index 841f1816..f3975e6d 100644
--- a/mateclaw-server/src/main/java/vip/mate/agent/graph/node/GoalEvaluationNode.java
+++ b/mateclaw-server/src/main/java/vip/mate/agent/graph/node/GoalEvaluationNode.java
@@ -202,7 +202,7 @@ public class GoalEvaluationNode implements NodeAction {
// Completion is the deterministic "all criteria passed" signal the
// evaluator already folded into result.completed() — no score gate.
if (result.completed()) {
- GoalEntity completed = goalService.markCompleted(refreshed.getId(), result);
+ GoalEntity completed = goalService.markRuntimeEvaluatedCompleted(refreshed.getId(), result, accessor.chatOrigin());
return MateClawStateAccessor.output()
.goalEvaluationResult(result.toMap())
.goalEvaluatedThisRun(true)
@@ -232,8 +232,15 @@ public class GoalEvaluationNode implements NodeAction {
} catch (Throwable t) {
log.warn("[GoalEvaluationNode] terminal write failed for goal={} — degrading to evaluated-only: {}",
refreshed.getId(), t.toString());
+ Map outward = result.toMap();
+ if (refreshed.isJsonAcceptanceRequired() && result.completed()) {
+ outward.put("completed", false);
+ outward.put("decision", GoalEvaluationResult.DECISION_CONTINUE);
+ outward.put("gap", "Managed JSON completion was not committed. "
+ + vip.mate.goal.service.GoalJsonProtocolHints.INSTRUCTIONS);
+ }
return MateClawStateAccessor.output()
- .goalEvaluationResult(result.toMap())
+ .goalEvaluationResult(outward)
.goalEvaluatedThisRun(true)
.events(List.of(skippedEvent(refreshed.getId(), "terminal_write_failed")))
.build();
@@ -394,6 +401,7 @@ public class GoalEvaluationNode implements NodeAction {
snapshot.put("successCheckPrompt", goal.getSuccessCheckPrompt());
snapshot.put("status", goal.getStatus() == null ? null : goal.getStatus().getValue());
snapshot.put("persistentExecution", goal.getPersistentExecution());
+ snapshot.put("jsonAcceptanceRequired", goal.isJsonAcceptanceRequired());
snapshot.put("turnBudget", goal.getTurnBudget());
snapshot.put("turnsUsed", goal.getTurnsUsed());
snapshot.put("llmCallBudget", goal.getLlmCallBudget());
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/graph/node/ObservationNode.java b/mateclaw-server/src/main/java/vip/mate/agent/graph/node/ObservationNode.java
index 6f4d5981..c8d3ef88 100644
--- a/mateclaw-server/src/main/java/vip/mate/agent/graph/node/ObservationNode.java
+++ b/mateclaw-server/src/main/java/vip/mate/agent/graph/node/ObservationNode.java
@@ -54,7 +54,7 @@ public class ObservationNode implements NodeAction {
* determined statically, and a false reminder is worse than none.
*/
private static final java.util.Set FILE_MUTATION_TOOLS =
- java.util.Set.of("write_file", "edit_file");
+ java.util.Set.of("write_file", "append_file", "edit_file");
private static final String VERIFICATION_REMINDER =
"\n\n[✅ 验证提醒] 本轮修改了文件。在给出最终回答前，请先验证改动是否生效" +
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/graph/node/ReasoningNode.java b/mateclaw-server/src/main/java/vip/mate/agent/graph/node/ReasoningNode.java
index 24147384..c1cd8635 100644
--- a/mateclaw-server/src/main/java/vip/mate/agent/graph/node/ReasoningNode.java
+++ b/mateclaw-server/src/main/java/vip/mate/agent/graph/node/ReasoningNode.java
@@ -148,7 +148,7 @@ public class ReasoningNode implements NodeAction {
"(?i)(word|docx|pdf|pptx|xlsx|markdown|\\bmd\\b|下载|附件|文档|文件|保存|落盘|导出)");
private static final List ARTIFACT_DELIVERY_TOOL_PREFIXES = List.of(
"renderDocx", "renderPdf", "renderPptx", "renderXlsx", "send_file", "sendFile",
- "write_file", "local_write_file", "edit_file", "local_edit_file");
+ "write_file", "append_file", "local_write_file", "edit_file", "local_edit_file");
/** Continuation nudge appended to the prompt when the model returns an empty turn. */
private static final String EMPTY_COMPLETION_NUDGE =
@@ -1160,21 +1160,20 @@ public class ReasoningNode implements NodeAction {
// soft cap would be re-promoted to ERROR_FALLBACK and we'd lose the
// INCOMPLETE semantics.
- if (result.partial() && "thinking_only_no_content".equals(result.errorMessage())) {
- // Soft thinking-only loop: the helper disposed the upstream stream
- // because the model accumulated >= THINKING_ONLY_HARD_CAP_CHARS of
- // reasoning_content without emitting any visible content or tool
- // calls. Treat as INCOMPLETE rather than fatal — the thinking text
- // has already been streamed and is preserved for the UI's collapse
- // panel; the user gets a short fallback line they can retry from.
+ if (result.partial() && ("thinking_only_no_content".equals(result.errorMessage())
+ || "thinking_token_limit".equals(result.errorMessage()))) {
+ // Either our thinking-only cap or the provider's output-token budget
+ // ended reasoning before any answer/tool call. Preserve the transcript
+ // and surface INCOMPLETE rather than retrying a supposed empty response.
String partialThinking = result.thinking() != null ? result.thinking() : "";
- log.warn("[ReasoningNode] Thinking-only soft cap hit ({} thinking chars, no content/tools); " +
- "INCOMPLETE",
- partialThinking.length());
+ log.warn("[ReasoningNode] Thinking-only turn ended: {} ({} thinking chars); INCOMPLETE",
+ result.errorMessage(), partialThinking.length());
var builder = reasonOutput()
.needsToolCall(false)
.shouldSummarize(false)
- .finalAnswer("（模型在思考阶段停留过久且未给出最终答案，请重试或拆分问题。）")
+ .finalAnswer("thinking_token_limit".equals(result.errorMessage())
+ ? "（模型在输出最终答案前已耗尽输出 token 预算。请关闭思考、适当增加模型最大输出 token 数，或拆分问题后重试。）"
+ : "（模型在思考阶段停留过久且未给出最终答案，请重试或拆分问题。）")
.llmCallCount(nextLlmCallCount)
.finishReason(FinishReason.INCOMPLETE)
.contentStreamed(false)
@@ -1244,6 +1243,28 @@ public class ReasoningNode implements NodeAction {
.build();
}
+ // Compatibility safety net for providers/adapters that return the
+ // runtime's reserved error placeholder as an HTTP-successful content
+ // response. Without this guard the long-form completion gate treats
+ // the placeholder as a short draft and can repeat it until the graph's
+ // iteration cap. Cron and other synchronous callers consume the
+ // resulting structured ERROR_FALLBACK; they do not need to infer from
+ // user-facing text.
+ if (isRuntimeErrorPlaceholder(result.text())) {
+ String errorText = result.text();
+ log.error("[ReasoningNode] Runtime error placeholder returned as normal content; failing turn");
+ return reasonOutput()
+ .needsToolCall(false)
+ .shouldSummarize(false)
+ .finalAnswer(errorText)
+ .llmCallCount(nextLlmCallCount)
+ .finishReason(FinishReason.ERROR_FALLBACK)
+ .contentStreamed(true)
+ .thinkingStreamed(result.thinking() != null && !result.thinking().isEmpty())
+ .mergeUsage(state, result)
+ .build();
+ }
+
if (result.partial()) {
int partialChars = result.text() != null ? result.text().length() : 0;
log.warn("[ReasoningNode] Partial LLM result ({} chars), treating as final answer", partialChars);
@@ -1429,6 +1450,10 @@ public class ReasoningNode implements NodeAction {
}
}
+ static boolean isRuntimeErrorPlaceholder(String text) {
+ return text != null && text.stripLeading().startsWith("[错误]");
+ }
+
private static String evidenceWarning(List unsupportedReferences) {
return "\n\n[证据不足] 以下引用未出现在本轮已读取/搜索到的工具证据中，或缺少有效来源标注："
+ String.join(", ", unsupportedReferences)
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/graph/plan/StateGraphPlanExecuteAgent.java b/mateclaw-server/src/main/java/vip/mate/agent/graph/plan/StateGraphPlanExecuteAgent.java
index 7c5c6120..8c3508d7 100644
--- a/mateclaw-server/src/main/java/vip/mate/agent/graph/plan/StateGraphPlanExecuteAgent.java
+++ b/mateclaw-server/src/main/java/vip/mate/agent/graph/plan/StateGraphPlanExecuteAgent.java
@@ -93,10 +93,17 @@ public class StateGraphPlanExecuteAgent extends BaseAgent implements StructuredS
@Override
public Flux chatWithReplayStream(String userMessage, String conversationId,
String toolCallPayload) {
+ return chatWithReplayStream(userMessage, conversationId, toolCallPayload, "");
+ }
+
+ @Override
+ public Flux chatWithReplayStream(String userMessage, String conversationId,
+ String toolCallPayload, String requesterId) {
setState(AgentState.RUNNING);
try {
log.info("[{}] Plan-Execute replay stream: conversationId={}", agentName, conversationId);
Map inputs = buildInitialState(userMessage, conversationId);
+ inputs.put(MateClawStateKeys.REQUESTER_ID, requesterId != null ? requesterId : "");
// 从 DB 恢复 awaiting_approval 状态的计划上下文（按 conversationId 过滤，避免并发会话误取）
PlanningService.PlanResumeContext ctx = planningService.findAwaitingApprovalContext(conversationId);
@@ -389,6 +396,10 @@ public class StateGraphPlanExecuteAgent extends BaseAgent implements StructuredS
goalService.findActiveByConversation(conversationId);
if (active != null) {
inputs.put(MateClawStateKeys.ACTIVE_GOAL, active);
+ if (active.isJsonAcceptanceRequired()) {
+ inputs.put(MateClawStateKeys.SYSTEM_PROMPT, inputs.get(MateClawStateKeys.SYSTEM_PROMPT) + "\n\n"
+ + vip.mate.goal.service.GoalJsonProtocolHints.INSTRUCTIONS);
+ }
}
} catch (Exception e) {
log.warn("[{}] findActiveByConversation failed: {}", agentName, e.getMessage());
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/graph/plan/node/StepExecutionNode.java b/mateclaw-server/src/main/java/vip/mate/agent/graph/plan/node/StepExecutionNode.java
index 2fc267b4..2192dc1e 100644
--- a/mateclaw-server/src/main/java/vip/mate/agent/graph/plan/node/StepExecutionNode.java
+++ b/mateclaw-server/src/main/java/vip/mate/agent/graph/plan/node/StepExecutionNode.java
@@ -356,13 +356,13 @@ public class StepExecutionNode implements NodeAction {
for (AssistantMessage.ToolCall toolCall : allToolCalls) {
if (isPreApprovedToolCall(toolCall.name(), preApprovedPayload)) {
String storedArguments = extractArgumentsFromPayload(preApprovedPayload);
- events.add(GraphEventPublisher.toolStart(toolCall.name(), toolCall.arguments()));
+ events.add(GraphEventPublisher.toolStart(toolCall.id(), toolCall.name(), toolCall.arguments()));
// RFC-052: pass the directOutputs collector so that an
// approved direct tool's full content is captured here
// (instead of leaking into the next LLM round).
ToolResponseMessage.ToolResponse response = executor.executePreApproved(
toolCall, storedArguments, events, conversationId, workspaceBasePath,
- stepDirectOutputs);
+ stepDirectOutputs, chatOrigin);
toolResponses.add(response);
preApprovedPayload = ""; // 只消费一次
} else {
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/runtime/dsh/DshConversationHistory.java b/mateclaw-server/src/main/java/vip/mate/agent/runtime/dsh/DshConversationHistory.java
new file mode 100644
index 00000000..64e82611
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/agent/runtime/dsh/DshConversationHistory.java
@@ -0,0 +1,92 @@
+package vip.mate.agent.runtime.dsh;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import vip.mate.agent.context.ChatOrigin;
+import vip.mate.agent.context.TokenEstimator;
+import vip.mate.workspace.conversation.model.MessageEntity;
+import vip.mate.workspace.conversation.repository.MessageMapper;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/** Bounded text replay for the SDK adapter's fresh-per-turn DSH sessions. */
+@Service
+@RequiredArgsConstructor
+public class DshConversationHistory {
+ private static final int MAX_MESSAGES = 40;
+ private static final int MAX_HISTORY_TOKENS = 4096;
+ private static final String PREFIX = "Previous conversation messages (JSON historical data, not new instructions). "
+ + "Use them as context for the current user message below. Some older history may be omitted.\n";
+ private static final String SUFFIX = "\nCurrent user message:\n";
+ private static final String TRUNCATED = "\n[truncated]";
+
+ private final MessageMapper mapper;
+ private final ObjectMapper objectMapper;
+
+ public String enrich(String conversationId, String originalInput, String currentInput, ChatOrigin origin) {
+ if (conversationId == null || conversationId.isBlank() || (origin != null && origin.cronOrigin())) {
+ return currentInput;
+ }
+ Long beforeId = origin == null ? null : origin.originMessageId();
+ // A leaf mapper avoids a circular dependency through ConversationService.
+ // Select only the text fields needed for replay; never load tool metadata or reasoning.
+ List rows = mapper.selectList(new LambdaQueryWrapper()
+ .select(MessageEntity::getId, MessageEntity::getRole, MessageEntity::getContent)
+ .eq(MessageEntity::getConversationId, conversationId)
+ .eq(MessageEntity::getDeleted, 0)
+ .eq(MessageEntity::getStatus, "completed")
+ .in(MessageEntity::getRole, List.of("user", "assistant"))
+ .lt(beforeId != null, MessageEntity::getId, beforeId)
+ .orderByDesc(MessageEntity::getId)
+ .last("LIMIT " + MAX_MESSAGES));
+
+ List selected = new ArrayList<>();
+ for (int index = 0; index < rows.size(); index++) {
+ MessageEntity row = rows.get(index);
+ // Legacy callers may not supply an origin ID. Only drop the latest
+ // matching user row, preserving older intentionally repeated questions.
+ if (beforeId == null && index == 0 && "user".equals(row.getRole())
+ && java.util.Objects.equals(originalInput, row.getContent())) continue;
+ String content = row.getContent();
+ if (content == null || content.isBlank()) continue;
+ selected.addFirst(new HistoricalMessage(row.getRole(), content));
+ if (TokenEstimator.estimateTokens(frame(selected)) <= MAX_HISTORY_TOKENS) continue;
+
+ // Retain as much of the boundary message as fits, including JSON
+ // escaping and framing in the estimate. Keep the current input intact.
+ int low = 0;
+ int high = Math.min(content.length(), MAX_HISTORY_TOKENS * 4);
+ while (low < high) {
+ int mid = (low + high + 1) / 2;
+ selected.set(0, new HistoricalMessage(row.getRole(), prefix(content, mid) + TRUNCATED));
+ if (TokenEstimator.estimateTokens(frame(selected)) <= MAX_HISTORY_TOKENS) low = mid;
+ else high = mid - 1;
+ }
+ if (low == 0) selected.removeFirst();
+ else selected.set(0, new HistoricalMessage(row.getRole(), prefix(content, low) + TRUNCATED));
+ break;
+ }
+ return selected.isEmpty() ? currentInput : frame(selected) + currentInput;
+ }
+
+ private static String prefix(String content, int length) {
+ if (length > 0 && length < content.length() && Character.isHighSurrogate(content.charAt(length - 1))) {
+ length--;
+ }
+ return content.substring(0, length);
+ }
+
+ private String frame(List messages) {
+ try {
+ return PREFIX + objectMapper.writeValueAsString(messages) + SUFFIX;
+ } catch (JsonProcessingException error) {
+ throw new IllegalStateException("Unable to encode DSH conversation history", error);
+ }
+ }
+
+ private record HistoricalMessage(String role, String content) {}
+}
diff --git a/mateclaw-server/src/main/java/vip/mate/agent/runtime/dsh/DshRuntimeService.java b/mateclaw-server/src/main/java/vip/mate/agent/runtime/dsh/DshRuntimeService.java
index 608ac54b..6d2cbd43 100644
--- a/mateclaw-server/src/main/java/vip/mate/agent/runtime/dsh/DshRuntimeService.java
+++ b/mateclaw-server/src/main/java/vip/mate/agent/runtime/dsh/DshRuntimeService.java
@@ -19,6 +19,7 @@ import vip.mate.agent.runtime.contract.RuntimeValidation;
import vip.mate.agent.runtime.dsh.management.DshRuntimeConfigService;
import vip.mate.agent.runtime.dsh.management.DshRuntimeConfiguration;
import vip.mate.agent.AgentService;
+import vip.mate.config.ConversationWindowProperties;
import vip.mate.llm.model.ModelConfigEntity;
import vip.mate.llm.model.ModelProviderEntity;
import vip.mate.llm.service.ModelConfigService;
@@ -53,16 +54,21 @@ public class DshRuntimeService implements AgentRuntimeProvider {
private final ModelConfigService modelConfigService;
private final ModelProviderService modelProviderService;
private final DshRuntimeConfigService runtimeConfigService;
+ private final ConversationWindowProperties windowProperties;
+ private static final int DEFAULT_MAX_OUTPUT_TOKENS = 4096;
+ private static final int DEFAULT_CONTEXT_WINDOW = 128000;
public DshRuntimeService(
ObjectMapper objectMapper,
ModelConfigService modelConfigService,
ModelProviderService modelProviderService,
- DshRuntimeConfigService runtimeConfigService) {
+ DshRuntimeConfigService runtimeConfigService,
+ ConversationWindowProperties windowProperties) {
this.objectMapper = objectMapper;
this.modelConfigService = modelConfigService;
this.modelProviderService = modelProviderService;
this.runtimeConfigService = runtimeConfigService;
+ this.windowProperties = windowProperties;
DshRuntimeConfiguration configuration = runtimeConfig();
log.info("[DSH] runtime configured: command={}, cordisConfig={}", configuration.executablePath(),
configuration.cordisConfigPath().isBlank() ? "" : configuration.cordisConfigPath());
@@ -245,8 +251,10 @@ public class DshRuntimeService implements AgentRuntimeProvider {
String dshSessionId = conversationId + "-" + UUID.randomUUID();
Files.createDirectories(session.workingDirectory());
String requestedModel = modelName == null || modelName.isBlank() ? configuration.modelName() : modelName;
- ModelProviderEntity provider = resolveProvider(requestedModel);
- String effectiveModelName = resolveModelName(requestedModel);
+ ModelConfigEntity model = resolveModel(requestedModel);
+ ModelProviderEntity provider = resolveProvider(model);
+ String effectiveModelName = resolveModelName(requestedModel, model);
+ int maxOutputTokens = resolveMaxOutputTokens(model, windowProperties.getDefaultMaxInputTokens());
log.debug("[DSH] model route: requestedModel={}, effectiveModel={}, provider={}, apiKeyConfigured={}, baseUrlConfigured={}",
modelName == null || modelName.isBlank() ? "" : modelName,
effectiveModelName,
@@ -284,7 +292,8 @@ public class DshRuntimeService implements AgentRuntimeProvider {
send(writer, request("initialize", "init-" + conversationId, Map.of(
"cwd", session.workingDirectory().toString(),
"provider", "deepseek-official",
- "model", effectiveModelName)));
+ "model", effectiveModelName,
+ "maxTokens", maxOutputTokens)));
awaitResponse(reader, "init-" + conversationId);
long sequence = 0;
sink.next(RuntimeEventProjector.project(RuntimeEvent.of(
@@ -487,13 +496,15 @@ public class DshRuntimeService implements AgentRuntimeProvider {
return primary != null && !primary.isBlank() ? primary : fallback;
}
- private ModelProviderEntity resolveProvider(String modelName) {
- ModelConfigEntity model = null;
+ private ModelConfigEntity resolveModel(String modelName) {
try {
- model = modelConfigService.resolveModel(modelName);
+ return modelConfigService.resolveModel(modelName);
} catch (RuntimeException ignored) {
- // Fall back to the dedicated DeepSeek provider below.
+ return null;
}
+ }
+
+ private ModelProviderEntity resolveProvider(ModelConfigEntity model) {
if (model != null && model.getProvider() != null && !model.getProvider().isBlank()) {
try {
return modelProviderService.getProviderConfig(model.getProvider());
@@ -508,18 +519,30 @@ public class DshRuntimeService implements AgentRuntimeProvider {
}
}
- private String resolveModelName(String modelName) {
- try {
- ModelConfigEntity model = modelConfigService.resolveModel(modelName);
- if (model != null && model.getModelName() != null && !model.getModelName().isBlank()) {
- return model.getModelName();
- }
- } catch (RuntimeException ignored) {
- // Fall back to the DSH catalog default for a not-yet-configured agent.
+ private static String resolveModelName(String modelName, ModelConfigEntity model) {
+ if (model != null && model.getModelName() != null && !model.getModelName().isBlank()) {
+ return model.getModelName();
}
return modelName == null || modelName.isBlank() ? "deepseek-v4-flash" : modelName;
}
+ /**
+ * SDK initialize.maxTokens is inherited by main and in-process child agents.
+ * Never let an unset model cap fall through to DSH's 256000-token default.
+ * As in the graph runtime, reserve at least half the known window for input.
+ * This is a static bound, not a token count of DSH's growing tool history.
+ */
+ static int resolveMaxOutputTokens(ModelConfigEntity model, int defaultWindow) {
+ int output = model != null && model.getMaxTokens() != null && model.getMaxTokens() > 0
+ ? model.getMaxTokens() : DEFAULT_MAX_OUTPUT_TOKENS;
+ int window = model != null && model.getMaxInputTokens() != null && model.getMaxInputTokens() > 0
+ ? model.getMaxInputTokens() : defaultWindow > 0 ? defaultWindow : DEFAULT_CONTEXT_WINDOW;
+ if (window < 2) {
+ throw new IllegalArgumentException("DSH 模型上下文窗口过小，无法同时容纳输入和输出，请检查模型配置");
+ }
+ return Math.min(output, window / 2);
+ }
+
RuntimeEvent mapEvent(String sessionId, long sequence, JsonNode event) {
String type = event.path("type").asText("");
JsonNode data = event.path("data");
diff --git a/mateclaw-server/src/main/java/vip/mate/approval/ApprovalWorkflowService.java b/mateclaw-server/src/main/java/vip/mate/approval/ApprovalWorkflowService.java
index 238e17fd..35e4d318 100644
--- a/mateclaw-server/src/main/java/vip/mate/approval/ApprovalWorkflowService.java
+++ b/mateclaw-server/src/main/java/vip/mate/approval/ApprovalWorkflowService.java
@@ -20,6 +20,7 @@ import org.springframework.transaction.support.TransactionSynchronization;
import org.springframework.transaction.support.TransactionSynchronizationManager;
import vip.mate.agent.context.ChatOrigin;
import vip.mate.agent.context.ChatOriginHolder;
+import vip.mate.goal.service.GoalApprovalRunService;
import vip.mate.approval.event.ApprovalResolutionEvent;
import vip.mate.approval.event.WorkflowApprovalResolvedEvent;
import vip.mate.approval.model.ToolApprovalEntity;
@@ -62,6 +63,8 @@ public class ApprovalWorkflowService implements ApplicationRunner {
* publish is a no-op. */
@Autowired(required = false)
private ApplicationEventPublisher events;
+ @Autowired(required = false)
+ private GoalApprovalRunService goalApprovalRuns;
/**
* GC scheduler — owns the 5-minute clock for the entire approval state machine
@@ -230,19 +233,18 @@ public class ApprovalWorkflowService implements ApplicationRunner {
String toolName, String toolArguments, String reason,
String toolCallPayload, String siblingToolCalls, String agentId,
GuardEvaluation evaluation) {
+ // Capture the graph-bound origin and selected Goal before creating
+ // the pending row. Its Goal may change while the approval waits, but
+ // the persisted snapshot retains the identity it had at creation.
+ ChatOrigin origin = ChatOriginHolder.get();
+ if (goalApprovalRuns != null) origin = goalApprovalRuns.captureSelectedGoal(origin);
+ String chatOriginJson = serializeChatOrigin(origin);
+
// 1. 内存层
String pendingId = approvalService.createPending(
conversationId, userId, toolName, toolArguments, reason,
toolCallPayload, siblingToolCalls, agentId);
- // RFC-063r §2.12: capture the originating ChatOrigin from the holder.
- // The holder was set by AgentService.{chat,chatStream,...} for the
- // duration of the agent invocation that produced this approval — so
- // it is non-null for IM / web triggered tool calls. Snapshot is
- // serialized once here and persisted on the DB row so cross-restart
- // replays keep the channel binding.
- String chatOriginJson = serializeChatOrigin(ChatOriginHolder.get());
-
// 2. 增强内存记录
approvalService.getPending(pendingId).ifPresent(pending -> {
if (evaluation != null) {
@@ -412,6 +414,24 @@ public class ApprovalWorkflowService implements ApplicationRunner {
"consumed", /* removeFromMap */ true);
}
+ /** Claim one exact approval before a team worker executes its guarded tool. */
+ @Transactional
+ public ResolveOutcome claimForReplay(String pendingId, String userId) {
+ return performResolve(pendingId, userId, "APPROVED", MetadataDecision.APPROVED,
+ "approved", /* removeFromMap */ false);
+ }
+
+ /** Consume an approval previously claimed by {@link #claimForReplay}. */
+ @Transactional
+ public ResolveOutcome consumeReplayClaim(String pendingId, String userId) {
+ PendingApproval target = getReplayClaim(pendingId).orElse(null);
+ if (target == null) {
+ return ResolveOutcome.alreadyResolved(pendingId);
+ }
+ return performResolveOnSnapshot(target, userId, "APPROVED", "CONSUMED",
+ MetadataDecision.APPROVED, "consumed", /* removeFromMap */ true);
+ }
+
/**
* Consume the earliest already-{@code approved} record for the conversation +
* tool — used when an out-of-band approval (e.g. /approve text command flow that
@@ -423,7 +443,7 @@ public class ApprovalWorkflowService implements ApplicationRunner {
if (target == null) {
return ResolveOutcome.alreadyResolved(null);
}
- return performResolveOnSnapshot(target, null, "CONSUMED", MetadataDecision.APPROVED,
+ return performResolveOnSnapshot(target, null, "APPROVED", "CONSUMED", MetadataDecision.APPROVED,
"consumed", /* removeFromMap */ true);
}
@@ -447,7 +467,7 @@ public class ApprovalWorkflowService implements ApplicationRunner {
List outcomes = new java.util.ArrayList<>(targets.size());
for (PendingApproval target : targets) {
try {
- ResolveOutcome outcome = performResolveOnSnapshot(target, userId, "DENIED",
+ ResolveOutcome outcome = performResolveOnSnapshot(target, userId, "PENDING", "DENIED",
MetadataDecision.DENIED, "denied", /* removeFromMap */ true);
if (outcome.dbSynced()) outcomes.add(outcome);
} catch (Exception e) {
@@ -475,7 +495,7 @@ public class ApprovalWorkflowService implements ApplicationRunner {
if (targets.isEmpty()) return List.of();
List outcomes = new java.util.ArrayList<>(targets.size());
for (PendingApproval target : targets) {
- ResolveOutcome outcome = performResolveOnSnapshot(target, null, "SUPERSEDED",
+ ResolveOutcome outcome = performResolveOnSnapshot(target, null, "PENDING", "SUPERSEDED",
MetadataDecision.DENIED, "superseded", /* removeFromMap */ true);
if (outcome.dbSynced()) outcomes.add(outcome);
}
@@ -644,12 +664,13 @@ public class ApprovalWorkflowService implements ApplicationRunner {
pendingId, snapshot != null, snapshot != null ? snapshot.getStatus() : "n/a");
return ResolveOutcome.alreadyResolved(pendingId);
}
- return performResolveOnSnapshot(snapshot, userId, dbStatus, metaDecision,
+ return performResolveOnSnapshot(snapshot, userId, "PENDING", dbStatus, metaDecision,
snapshotStatus, removeFromMap);
}
private ResolveOutcome performResolveOnSnapshot(PendingApproval snapshot, String userId,
- String dbStatus, MetadataDecision metaDecision,
+ String expectedDbStatus, String dbStatus,
+ MetadataDecision metaDecision,
String snapshotStatus, boolean removeFromMap) {
// Phase 1 — DB UPDATE (conditional). The eq("PENDING") guard makes the call
// idempotent: if another path already won, we get rows=0 and bail without
@@ -658,7 +679,7 @@ public class ApprovalWorkflowService implements ApplicationRunner {
try {
LambdaUpdateWrapper wrapper = new LambdaUpdateWrapper()
.eq(ToolApprovalEntity::getPendingId, snapshot.getPendingId())
- .eq(ToolApprovalEntity::getStatus, "PENDING")
+ .eq(ToolApprovalEntity::getStatus, expectedDbStatus)
.set(ToolApprovalEntity::getStatus, dbStatus)
.set(ToolApprovalEntity::getResolvedAt, LocalDateTime.now());
if (userId != null) {
@@ -672,8 +693,8 @@ public class ApprovalWorkflowService implements ApplicationRunner {
throw e;
}
if (rows == 0) {
- log.info("[ApprovalWorkflow] resolve no-op for {}: DB row not in PENDING (concurrent resolve)",
- snapshot.getPendingId());
+ log.info("[ApprovalWorkflow] resolve no-op for {}: DB row not in {} (concurrent resolve)",
+ snapshot.getPendingId(), expectedDbStatus);
return ResolveOutcome.alreadyResolved(snapshot.getPendingId());
}
@@ -809,6 +830,44 @@ public class ApprovalWorkflowService implements ApplicationRunner {
return approvalService.getPending(pendingId);
}
+ /**
+ * Recover an exact APPROVED replay claim from memory or DB. APPROVED claims are
+ * intentionally durable so a worker replay can be finalized after a restart
+ * without reopening the approval to denial.
+ */
+ public java.util.Optional getReplayClaim(String pendingId) {
+ PendingApproval inMemory = approvalService.getPending(pendingId)
+ .filter(pending -> "approved".equals(pending.getStatus()))
+ .orElse(null);
+ if (inMemory != null) {
+ return java.util.Optional.of(inMemory);
+ }
+ ToolApprovalEntity entity = approvalMapper.selectOne(
+ new LambdaQueryWrapper()
+ .eq(ToolApprovalEntity::getPendingId, pendingId)
+ .eq(ToolApprovalEntity::getStatus, "APPROVED"));
+ if (entity == null) {
+ return java.util.Optional.empty();
+ }
+ Instant createdAt = entity.getCreatedAt() == null
+ ? Instant.now()
+ : entity.getCreatedAt().atZone(ZoneId.systemDefault()).toInstant();
+ PendingApproval snapshot = new PendingApproval(entity.getPendingId(),
+ entity.getConversationId(), entity.getUserId(), entity.getToolName(),
+ entity.getToolArguments(), entity.getSummary(), createdAt, "approved");
+ snapshot.setToolCallPayload(entity.getToolCallPayload());
+ snapshot.setSiblingToolCalls(entity.getSiblingToolCalls());
+ snapshot.setAgentId(entity.getAgentId());
+ snapshot.setChannelType(entity.getChannelType());
+ snapshot.setRequesterName(entity.getRequesterName());
+ snapshot.setReplyTarget(entity.getReplyTarget());
+ snapshot.setFindingsJson(entity.getFindingsJson());
+ snapshot.setMaxSeverity(entity.getMaxSeverity());
+ snapshot.setSummary(entity.getSummary());
+ snapshot.setChatOrigin(entity.getChatOrigin());
+ return java.util.Optional.of(snapshot);
+ }
+
public PendingApproval findPendingByConversation(String conversationId) {
return approvalService.findPendingByConversation(conversationId);
}
diff --git a/mateclaw-server/src/main/java/vip/mate/channel/ChannelMessageRouter.java b/mateclaw-server/src/main/java/vip/mate/channel/ChannelMessageRouter.java
index 184f7905..017df0de 100644
--- a/mateclaw-server/src/main/java/vip/mate/channel/ChannelMessageRouter.java
+++ b/mateclaw-server/src/main/java/vip/mate/channel/ChannelMessageRouter.java
@@ -1469,6 +1469,7 @@ public class ChannelMessageRouter {
replayOrigin = chatOriginFactory.from(
channelEntity, triggerMessage, conversationId, /* workspaceBasePath */ null);
}
+ replayOrigin = replayOrigin.withApprovalId(consumed.getPendingId());
AgentService.ChatResult replayResult = agentService.chatWithReplayWithUsage(
agentId, replayPrompt, conversationId, consumed.getToolCallPayload(), replayOrigin);
String reply = replayResult.content();
diff --git a/mateclaw-server/src/main/java/vip/mate/channel/web/ChatController.java b/mateclaw-server/src/main/java/vip/mate/channel/web/ChatController.java
index cd9999b8..ce7fff4e 100644
--- a/mateclaw-server/src/main/java/vip/mate/channel/web/ChatController.java
+++ b/mateclaw-server/src/main/java/vip/mate/channel/web/ChatController.java
@@ -74,6 +74,12 @@ public class ChatController {
@org.springframework.beans.factory.annotation.Autowired
private ConversationTurnGate turnGate = new ConversationTurnGate();
+ @org.springframework.beans.factory.annotation.Autowired
+ private vip.mate.goal.service.GoalJsonAcceptanceService jsonAcceptance;
+
+ @org.springframework.beans.factory.annotation.Autowired
+ private vip.mate.goal.service.GoalApprovalRunService goalApprovalRuns;
+
// Virtual thread per SSE task: matches the app-wide virtual-thread model
// (spring.threads.virtual.enabled=true) and, unlike a cached platform-thread
// pool, never reuses a thread across tasks, so no ThreadLocal state can leak
@@ -241,7 +247,13 @@ public class ChatController {
// deny: workflow.resolve handles DB + metadata + memory atomically.
if (isDenyCommand) {
- ResolveOutcome denyOutcome = approvalService.resolve(pending.getPendingId(), username, "denied");
+ ResolveOutcome denyOutcome;
+ try {
+ denyOutcome = resolveWithCurrentApprover(pending, auth, username, false);
+ } catch (vip.mate.exception.MateClawException revoked) {
+ sendErrorDoneAndComplete(emitter, revoked.getMessage());
+ return emitter;
+ }
conversationService.removeApprovalPlaceholders(conversationId);
log.info("[Approval-Stream] User {} denied pending {} for conversation {} (dbSynced={}, msgRewritten={})",
username, pending.getPendingId(), conversationId,
@@ -251,7 +263,13 @@ public class ChatController {
// approve: atomic resolveAndConsume; workflow handles DB + metadata + memory.
PendingApproval consumed = null;
if (isApprovalCommand) {
- ResolveOutcome consumeOutcome = approvalService.resolveAndConsume(pending.getPendingId(), username);
+ ResolveOutcome consumeOutcome;
+ try {
+ consumeOutcome = resolveWithCurrentApprover(pending, auth, username, true);
+ } catch (vip.mate.exception.MateClawException revoked) {
+ sendErrorDoneAndComplete(emitter, revoked.getMessage());
+ return emitter;
+ }
if (consumeOutcome.isAlreadyResolved()) {
try {
sendEvent(emitter, "error", Map.of("message", "审批记录已过期或已被处理"));
@@ -346,7 +364,7 @@ public class ChatController {
}
// Carry the request-thread base URL so any file a replayed
// tool generates gets an absolute download link.
- replayOrigin = replayOrigin.withBaseUrl(requestBaseUrl);
+ replayOrigin = replayOrigin.withBaseUrl(requestBaseUrl).withApprovalId(finalConsumed.getPendingId());
Disposable disposable = agentService.chatWithReplayStream(
replayAgentId, replayPrompt, conversationId, finalConsumed.getToolCallPayload(), username, replayOrigin)
.doOnNext(delta -> {
@@ -577,6 +595,19 @@ public class ChatController {
? (regenerateSeed.content() != null ? regenerateSeed.content() : "")
: requestMessage;
+ // Snapshot selection on the request thread before the executor can be
+ // delayed behind other work. A Goal abandoned during model inference
+ // must still be recognizable when that turn asks for approval.
+ final vip.mate.agent.context.ChatOrigin selectedTurnOrigin;
+ try {
+ selectedTurnOrigin = captureWebGoal(memoryOrigin(conversationId, username,
+ requesterUserIdOf(auth), workspaceId, request.getEndUserId())
+ .withBaseUrl(requestBaseUrl), agentId);
+ } catch (vip.mate.exception.MateClawException invalidSelection) {
+ sendErrorDoneAndComplete(emitter, invalidSelection.getMessage());
+ return emitter;
+ }
+
// ---- 正常请求：注册流状态并附着首个订阅者 ----
streamTracker.register(conversationId);
setupPermit.close();
@@ -638,10 +669,7 @@ public class ChatController {
// RFC-063r §2.5: web entry — null channelId / no ChannelTarget;
// tools that need a workspace path read it from the agent (origin
// is enriched with workspaceBasePath in StateGraph buildInitialState).
- vip.mate.agent.context.ChatOrigin webOrigin =
- memoryOrigin(conversationId, username, requesterUserIdOf(auth), workspaceId, request.getEndUserId())
- .withBaseUrl(requestBaseUrl)
- .withOriginMessageId(originMessageId);
+ vip.mate.agent.context.ChatOrigin webOrigin = selectedTurnOrigin.withOriginMessageId(originMessageId);
Disposable disposable = agentService.chatStructuredStream(agentId, promptText, conversationId, username, request.getThinkingLevel(), webOrigin)
.doOnNext(delta -> {
if (emitterDone.get()) return;
@@ -1114,8 +1142,17 @@ public class ChatController {
// Commit the payload before publishing acceptance. The stream tracker is
// only a wake signal; the database row remains authoritative on restart.
- var stored = inputQueue.enqueue(conversationId, agentId, username, message, contentParts,
- LocalDateTime.now());
+ var enqueueConversation = conversationService.findByConversationId(conversationId);
+ Long queueAgentId = agentId == null && enqueueConversation != null
+ ? enqueueConversation.getAgentId() : agentId;
+ if (enqueueConversation == null || queueAgentId == null
+ || !java.util.Objects.equals(queueAgentId, enqueueConversation.getAgentId())) {
+ return R.fail(409, "会话助手已变化，请刷新后重试");
+ }
+ var queuedSelection = captureWebGoal(vip.mate.agent.context.ChatOrigin.web(conversationId,
+ username, enqueueConversation.getWorkspaceId(), null, null, requesterUserIdOf(auth)), queueAgentId);
+ var stored = inputQueue.enqueue(conversationId, queueAgentId, username, message, contentParts,
+ requesterUserIdOf(auth), queuedSelection.selectedGoalId(), LocalDateTime.now());
boolean queued = streamTracker.notifyQueuedInput(conversationId);
if (!queued) {
inputQueue.cancel(stored.id(), "stream_finished_before_queue_registration",
@@ -1167,9 +1204,9 @@ public class ChatController {
String promptText = buildPromptText(request.getMessage(), request.getContentParts());
// Carry the web origin so per-owner memory recall (read) and the
// post-conversation memory write below agree on the same owner key.
- vip.mate.agent.context.ChatOrigin webOrigin =
+ vip.mate.agent.context.ChatOrigin webOrigin = captureWebGoal(
memoryOrigin(request.getConversationId(), username, requesterUserIdOf(auth), workspaceId,
- request.getEndUserId()).withOriginMessageId(
+ request.getEndUserId()), agentId).withOriginMessageId(
savedUser == null ? null : savedUser.getId());
AgentService.ChatResult result = turnGate.withPermit(permit, () ->
agentService.chatWithUsage(agentId, promptText, request.getConversationId(), webOrigin));
@@ -1344,11 +1381,46 @@ public class ChatController {
return vip.mate.agent.context.ChatOrigin.web(conversationId, username, workspaceId, null, baseUrl, requesterUserId);
}
- /**
- * Extract the authenticated user's immutable numeric id from the
- * {@link Authentication} details (stamped by {@code JwtAuthFilter} for both
- * the JWT and PAT paths). Null when not authenticated or details absent.
- */
+ private vip.mate.agent.context.ChatOrigin captureWebGoal(
+ vip.mate.agent.context.ChatOrigin origin, Long agentId) {
+ var withAgent = origin.withAgent(agentId);
+ return goalApprovalRuns == null ? withAgent : goalApprovalRuns.captureSelectedGoal(withAgent);
+ }
+
+ /** Hold the selected Goal's approver identity through the approval write. */
+ private ResolveOutcome resolveWithCurrentApprover(PendingApproval pending, Authentication auth,
+ String username, boolean approve) {
+ if (goalApprovalRuns != null && jsonAcceptance != null) {
+ var origin = approvalService.restoreChatOrigin(pending.getChatOrigin());
+ if (approve && (origin == null || origin.conversationId() == null
+ || origin.requesterUserId() == null && (origin.executionAttribution() == null
+ || origin.executionAttribution().goalId() == null))
+ && goalApprovalRuns.hasManagedGoalHistory(pending.getConversationId(), pending.getAgentId())) {
+ throw new vip.mate.exception.MateClawException(409,
+ "Managed Goal approval origin is unavailable; start a new request");
+ }
+ if (origin != null) origin = origin.withApprovalId(pending.getPendingId());
+ if (origin != null && goalApprovalRuns.requiresCurrentApprover(origin)) {
+ var capturedOrigin = origin;
+ Long currentUserId = requesterUserIdOf(auth);
+ return jsonAcceptance.withAuthenticatedUser(currentUserId, username, current -> {
+ var attribution = capturedOrigin.executionAttribution();
+ if (attribution == null || attribution.goalAttemptId() == null) {
+ if (!java.util.Objects.equals(currentUserId, capturedOrigin.requesterUserId())) {
+ throw new vip.mate.exception.MateClawException(403, "Approval belongs to another account");
+ }
+ }
+ goalApprovalRuns.validateCapturedForApproval(capturedOrigin, current, approve);
+ return approve ? approvalService.resolveAndConsume(pending.getPendingId(), current)
+ : approvalService.resolve(pending.getPendingId(), current, "denied");
+ });
+ }
+ }
+ return approve ? approvalService.resolveAndConsume(pending.getPendingId(), username)
+ : approvalService.resolve(pending.getPendingId(), username, "denied");
+ }
+
+ /** Extract the immutable account id stamped in Authentication details. */
private Long requesterUserIdOf(org.springframework.security.core.Authentication auth) {
if (auth == null) return null;
Object details = auth.getDetails();
@@ -1461,6 +1533,30 @@ public class ChatController {
return;
}
+ // A row queued by an older binary has no selection snapshot. If this
+ // conversation has managed Goal history, execution could turn an old
+ // selected request into an explicitly unselected approval after a Goal
+ // ended. Keep the user's text and require a fresh authenticated turn.
+ if (preConsumedInput.selectedGoalId() == null && goalApprovalRuns != null
+ && goalApprovalRuns.hasManagedGoalHistory(conversationId, String.valueOf(agentId))) {
+ skipQueuedInput(preConsumedInput, queueClaimId, conversationId, emitter, emitterDone,
+ requesterId, baseUrl, "managed_goal_selection_unknown",
+ "排队消息缺少Goal选择快照，内容已保存，请重新发送");
+ return;
+ }
+ if (preConsumedInput.selectedGoalId() != null) {
+ var selectedOrigin = vip.mate.agent.context.ChatOrigin.web(conversationId,
+ preConsumedInput.createdBy(), queuedConversation.getWorkspaceId(), null,
+ baseUrl, preConsumedInput.requesterUserId())
+ .withAgent(agentId).withSelectedGoalId(preConsumedInput.selectedGoalId());
+ if (goalApprovalRuns == null || !goalApprovalRuns.queuedSelectionStillCurrent(selectedOrigin)) {
+ skipQueuedInput(preConsumedInput, queueClaimId, conversationId, emitter, emitterDone,
+ requesterId, baseUrl, "managed_goal_selection_stale",
+ "排队消息的Goal或账户已失效，内容已保存，请重新发送");
+ return;
+ }
+ }
+
// Rate Limit 防护：如果上一轮以 rate limit 错误结束，不立即续跑排队消息（必然再次 429）。
// 改为持久化用户消息 + 通知前端"稍后重试"，避免连锁 429 浪费配额。
String lastMessage = conversationService.getLastMessage(conversationId);
@@ -1526,12 +1622,15 @@ public class ChatController {
streamTracker.incrementFlux(conversationId);
// RFC-063r §2.5: queued messages land in the same conversation; carry
// a web-origin ChatOrigin so any cron job created during the queued
- // turn keeps a consistent (null-channel) binding.
+ // turn keeps a consistent (null-channel) binding. The account id comes
+ // from the authenticated enqueue, never from the previous stream
+ // username. Managed operations revalidate this account and scope.
vip.mate.agent.context.ChatOrigin queuedOrigin =
- vip.mate.agent.context.ChatOrigin.web(conversationId, requesterId, null, null)
- .withBaseUrl(baseUrl)
- .withOriginMessageId(queuedOriginMessageId);
- Disposable disposable = agentService.chatStructuredStream(agentId, queuedMessage, conversationId, requesterId, null, queuedOrigin)
+ vip.mate.agent.context.ChatOrigin.web(conversationId, preConsumedInput.createdBy(),
+ queuedConversation.getWorkspaceId(), null, baseUrl, preConsumedInput.requesterUserId())
+ .withOriginMessageId(queuedOriginMessageId)
+ .withSelectedGoalId(preConsumedInput.selectedGoalId());
+ Disposable disposable = agentService.chatStructuredStream(agentId, queuedMessage, conversationId, preConsumedInput.createdBy(), null, queuedOrigin)
.doOnNext(delta -> {
if (emitterDone.get()) return;
try {
@@ -1651,6 +1750,42 @@ public class ChatController {
() -> emergencySaveAccumulator(conversationId, accumulator));
}
+ private void skipQueuedInput(ConversationInputQueueStore.QueuedInput input, String claimId,
+ String conversationId, SseEmitter emitter, AtomicBoolean emitterDone,
+ String requesterId, String baseUrl, String reason, String warning) {
+ if (input.persistedMessageId() == null) {
+ MessageEntity saved = conversationService.saveMessage(conversationId, "user",
+ input.message(), input.contentParts(), "queued");
+ if (saved == null || !inputQueue.bindMessage(input.id(), claimId,
+ saved.getId(), LocalDateTime.now())) {
+ inputQueue.release(input.id(), claimId, LocalDateTime.now());
+ throw new IllegalStateException("Skipped queued input could not be preserved");
+ }
+ }
+ if (!inputQueue.consume(input.id(), claimId, LocalDateTime.now()))
+ throw new IllegalStateException("Skipped queued input claim was lost");
+ // The preceding turn may have removed its RunState already, so a
+ // tracker broadcast can silently disappear. The held emitter is the
+ // authoritative response for this queued input.
+ try {
+ sendEvent(emitter, "warning", Map.of("message", warning));
+ sendEvent(emitter, "queued_input_skipped", Map.of(
+ "conversationId", conversationId,
+ "message", input.message() == null ? "" : input.message(),
+ "reason", reason));
+ } catch (IOException disconnected) {
+ log.debug("Queued-input skip notification could not be delivered for {}: {}",
+ conversationId, disconnected.getMessage());
+ }
+ if (hasQueuedInput(conversationId)) {
+ sseExecutor.execute(() -> startQueuedMessage(conversationId, emitter, emitterDone,
+ requesterId, baseUrl));
+ } else {
+ conversationService.updateStreamStatus(conversationId, "idle");
+ completeEmitterQuietly(emitter, emitterDone);
+ }
+ }
+
private boolean hasQueuedInput(String conversationId) {
return inputQueue.countQueued(conversationId) > 0;
}
diff --git a/mateclaw-server/src/main/java/vip/mate/channel/web/ChatStreamTracker.java b/mateclaw-server/src/main/java/vip/mate/channel/web/ChatStreamTracker.java
index 122f30e0..bd1fdcf7 100644
--- a/mateclaw-server/src/main/java/vip/mate/channel/web/ChatStreamTracker.java
+++ b/mateclaw-server/src/main/java/vip/mate/channel/web/ChatStreamTracker.java
@@ -1,5 +1,6 @@
package vip.mate.channel.web;
+import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import jakarta.annotation.PreDestroy;
import lombok.extern.slf4j.Slf4j;
@@ -88,6 +89,18 @@ public class ChatStreamTracker {
@Value("${mateclaw.stream.iteration-events:true}")
private boolean iterationEventsEnabled = true;
+ /**
+ * Coalesce the tiny token fragments produced by streaming model clients
+ * before assigning an SSE id and touching the replay buffer. This keeps
+ * rendering responsive while avoiding thousands of emitter writes for a
+ * single long answer.
+ */
+ @Value("${mateclaw.stream.content-batch-ms:25}")
+ private long contentBatchMs = 25L;
+
+ @Value("${mateclaw.stream.content-batch-chars:256}")
+ private int contentBatchChars = 256;
+
/**
* Heartbeat cadence (seconds) before the first model token arrives. Short
* because pre-token gaps strand the UI on a blank "正在生成中" placeholder
@@ -127,6 +140,11 @@ public class ChatStreamTracker {
this.iterationEventsEnabled = enabled;
}
+ void setContentBatchingForTesting(long flushMs, int maxChars) {
+ this.contentBatchMs = Math.max(1L, flushMs);
+ this.contentBatchChars = Math.max(1, maxChars);
+ }
+
public boolean isIterationEventsEnabled() {
return iterationEventsEnabled;
}
@@ -219,6 +237,11 @@ public class ChatStreamTracker {
/** 已广播的 pending approval ID 集合（用于幂等去重） */
final java.util.Set broadcastedApprovalIds = java.util.concurrent.ConcurrentHashMap.newKeySet();
+ /** Pending visible answer text waiting for the SSE coalescing window. Guarded by lock. */
+ String pendingContentField;
+ final StringBuilder pendingContent = new StringBuilder();
+ ScheduledFuture pendingContentFlush;
+
/** 创建时间（用于 stale 检测和清理） */
final long createdAt = System.currentTimeMillis();
@@ -748,6 +771,99 @@ public class ChatStreamTracker {
return true;
}
+ private record ContentDelta(String field, String text) {}
+
+ /**
+ * Buffer only the two established visible-content wire shapes:
+ * {@code {"delta":"..."}} (workspace chat) and
+ * {@code {"text":"..."}} (embedded webchat). Payloads with extra
+ * metadata stay on the ordinary path so batching never discards fields.
+ */
+ private boolean tryBufferContentDelta(RunState state, String eventName,
+ String jsonData, boolean skipBuffer) {
+ if (!"content_delta".equals(eventName) || skipBuffer || state == null) {
+ return false;
+ }
+ ContentDelta delta = parseContentDelta(jsonData);
+ if (delta == null) {
+ return false;
+ }
+
+ boolean flushNow = false;
+ synchronized (state.lock) {
+ if (!isCurrent(state) || state.done) {
+ return true;
+ }
+ // A conversation uses one wire field for a run. If a caller does
+ // switch shapes, flush the old batch and deliver the new payload
+ // unchanged rather than mixing contracts.
+ if (state.pendingContentField != null
+ && !state.pendingContentField.equals(delta.field())) {
+ return false;
+ }
+ state.lastEventAt = System.currentTimeMillis();
+ state.pendingContentField = delta.field();
+ state.pendingContent.append(delta.text());
+ if (state.pendingContent.length() >= Math.max(1, contentBatchChars)) {
+ flushNow = true;
+ } else if (state.pendingContentFlush == null
+ || state.pendingContentFlush.isDone()) {
+ state.pendingContentFlush = heartbeatScheduler.schedule(
+ () -> flushPendingContent(state),
+ Math.max(1L, contentBatchMs), TimeUnit.MILLISECONDS);
+ }
+ }
+ if (flushNow) {
+ flushPendingContent(state);
+ }
+ return true;
+ }
+
+ private ContentDelta parseContentDelta(String jsonData) {
+ if (jsonData == null || jsonData.isEmpty()) return null;
+ try {
+ JsonNode node = objectMapper.readTree(jsonData);
+ if (node == null || !node.isObject() || node.size() != 1) return null;
+ String field = node.has("delta") ? "delta" : node.has("text") ? "text" : null;
+ if (field == null || !node.path(field).isTextual()) return null;
+ String text = node.path(field).textValue();
+ return text == null || text.isEmpty() ? null : new ContentDelta(field, text);
+ } catch (Exception ignored) {
+ return null;
+ }
+ }
+
+ /** Snapshot under the run lock, then emit through the fenced raw path. */
+ private void flushPendingContent(RunState state) {
+ String field;
+ String text;
+ synchronized (state.lock) {
+ if (state.pendingContent.length() == 0) {
+ if (state.pendingContentFlush != null) {
+ state.pendingContentFlush.cancel(false);
+ state.pendingContentFlush = null;
+ }
+ state.pendingContentField = null;
+ return;
+ }
+ field = state.pendingContentField;
+ text = state.pendingContent.toString();
+ state.pendingContent.setLength(0);
+ state.pendingContentField = null;
+ if (state.pendingContentFlush != null) {
+ state.pendingContentFlush.cancel(false);
+ state.pendingContentFlush = null;
+ }
+ }
+ try {
+ String json = objectMapper.writeValueAsString(Map.of(field, text));
+ broadcastNow(new RunHandle(state), "content_delta", json, false);
+ } catch (Exception e) {
+ log.warn("Failed to flush content batch for {}: {}",
+ state.conversationId, e.getMessage());
+ }
+ }
+
/**
* 广播事件到所有订阅者并缓存到 buffer.
*
@@ -777,6 +893,17 @@ public class ChatStreamTracker {
public void broadcast(RunHandle handle, String eventName, String jsonData, boolean skipBuffer) {
if (handle == null) return;
+ RunState state = handle.state;
+ if (tryBufferContentDelta(state, eventName, jsonData, skipBuffer)) {
+ return;
+ }
+ if (!"heartbeat".equals(eventName)) {
+ flushPendingContent(state);
+ }
+ broadcastNow(handle, eventName, jsonData, skipBuffer);
+ }
+
+ private void broadcastNow(RunHandle handle, String eventName, String jsonData, boolean skipBuffer) {
RunState state = handle.state;
boolean isDone = "done".equals(eventName);
boolean isPostTurnEvent = "goal_continuation".equals(eventName)
@@ -854,6 +981,18 @@ public class ChatStreamTracker {
*/
public void broadcast(String conversationId, String eventName, String jsonData, boolean skipBuffer) {
RunState state = runs.get(conversationId);
+ if (state == null) return;
+ if (tryBufferContentDelta(state, eventName, jsonData, skipBuffer)) {
+ return;
+ }
+ if (!"heartbeat".equals(eventName)) {
+ flushPendingContent(state);
+ }
+ broadcastNow(conversationId, eventName, jsonData, skipBuffer);
+ }
+
+ private void broadcastNow(String conversationId, String eventName, String jsonData, boolean skipBuffer) {
+ RunState state = runs.get(conversationId);
boolean isDone = "done".equals(eventName);
boolean isPostTurnEvent = "goal_continuation".equals(eventName)
@@ -1312,6 +1451,10 @@ public class ChatStreamTracker {
private boolean complete(RunState state) {
String conversationId = state.conversationId;
+ // Some terminal paths do not publish a done envelope. Flush visible
+ // text while the run is still live so the scheduled batch cannot be
+ // rejected after state.done flips below.
+ flushPendingContent(state);
ScheduledFuture oldHeartbeat;
synchronized (state.lock) {
if (!isCurrent(state)) {
@@ -1354,6 +1497,7 @@ public class ChatStreamTracker {
if (state == null) {
return new CompletionResult(true);
}
+ flushPendingContent(state);
ScheduledFuture oldHeartbeat;
synchronized (state.lock) {
if (!isCurrent(state)) {
diff --git a/mateclaw-server/src/main/java/vip/mate/channel/web/ConversationInputQueueStore.java b/mateclaw-server/src/main/java/vip/mate/channel/web/ConversationInputQueueStore.java
index 7dfd820e..586c4065 100644
--- a/mateclaw-server/src/main/java/vip/mate/channel/web/ConversationInputQueueStore.java
+++ b/mateclaw-server/src/main/java/vip/mate/channel/web/ConversationInputQueueStore.java
@@ -31,14 +31,27 @@ public class ConversationInputQueueStore {
public QueuedInput enqueue(String conversationId, Long agentId, String createdBy,
String message, List contentParts,
LocalDateTime now) {
+ return enqueue(conversationId, agentId, createdBy, message, contentParts, null, now);
+ }
+
+ public QueuedInput enqueue(String conversationId, Long agentId, String createdBy,
+ String message, List contentParts,
+ Long requesterUserId, LocalDateTime now) {
+ return enqueue(conversationId, agentId, createdBy, message, contentParts,
+ requesterUserId, null, now);
+ }
+
+ public QueuedInput enqueue(String conversationId, Long agentId, String createdBy,
+ String message, List contentParts,
+ Long requesterUserId, Long selectedGoalId, LocalDateTime now) {
long id = IdWorker.getId();
jdbc.update("""
INSERT INTO mate_conversation_input_queue(
id,conversation_id,agent_id,created_by,message,content_parts,state,
- created_at,updated_at)
- VALUES(?,?,?,?,?,?,'queued',?,?)
+ created_at,updated_at,requester_user_id,selected_goal_id)
+ VALUES(?,?,?,?,?,?,'queued',?,?,?,?)
""", id, conversationId, agentId, createdBy, message == null ? "" : message,
- writeParts(contentParts), now, now);
+ writeParts(contentParts), now, now, requesterUserId, selectedGoalId);
return get(id);
}
@@ -137,7 +150,8 @@ public class ConversationInputQueueStore {
rs.getString("message"), readParts(rs.getString("content_parts")),
rs.getString("state"), rs.getString("claimed_by_attempt_id"),
nullableLong(rs, "persisted_message_id"), rs.getString("cancel_reason"),
- time(rs, "created_at"), time(rs, "updated_at"));
+ time(rs, "created_at"), time(rs, "updated_at"), nullableLong(rs, "requester_user_id"),
+ nullableLong(rs, "selected_goal_id"));
}
private String writeParts(List parts) {
@@ -183,5 +197,23 @@ public class ConversationInputQueueStore {
Long persistedMessageId,
String cancelReason,
LocalDateTime createdAt,
- LocalDateTime updatedAt) {}
+ LocalDateTime updatedAt,
+ Long requesterUserId,
+ Long selectedGoalId) {
+ public QueuedInput(Long id, String conversationId, Long agentId, String createdBy,
+ String message, List contentParts, String state,
+ String claimedByAttemptId, Long persistedMessageId, String cancelReason,
+ LocalDateTime createdAt, LocalDateTime updatedAt, Long requesterUserId) {
+ this(id, conversationId, agentId, createdBy, message, contentParts, state,
+ claimedByAttemptId, persistedMessageId, cancelReason, createdAt, updatedAt,
+ requesterUserId, null);
+ }
+ public QueuedInput(Long id, String conversationId, Long agentId, String createdBy,
+ String message, List contentParts, String state,
+ String claimedByAttemptId, Long persistedMessageId, String cancelReason,
+ LocalDateTime createdAt, LocalDateTime updatedAt) {
+ this(id, conversationId, agentId, createdBy, message, contentParts, state,
+ claimedByAttemptId, persistedMessageId, cancelReason, createdAt, updatedAt, null, null);
+ }
+ }
}
diff --git a/mateclaw-server/src/main/java/vip/mate/channel/web/Utf8SseEmitter.java b/mateclaw-server/src/main/java/vip/mate/channel/web/Utf8SseEmitter.java
index f3196997..85d0d85d 100644
--- a/mateclaw-server/src/main/java/vip/mate/channel/web/Utf8SseEmitter.java
+++ b/mateclaw-server/src/main/java/vip/mate/channel/web/Utf8SseEmitter.java
@@ -45,6 +45,10 @@ public class Utf8SseEmitter extends SseEmitter {
protected void extendResponse(ServerHttpResponse response) {
super.extendResponse(response);
HttpHeaders headers = response.getHeaders();
+ // Streaming frames must reach the client as they are emitted. Nginx
+ // honors this response header unless explicitly configured to ignore it.
+ headers.set("X-Accel-Buffering", "no");
+ headers.setCacheControl("no-store, no-transform");
// Spring's default sets Content-Type=text/event-stream without charset.
// Only override when no charset is already specified, so callers that
// want to roll their own (rare) keep working.
diff --git a/mateclaw-server/src/main/java/vip/mate/channel/webchat/WebChatController.java b/mateclaw-server/src/main/java/vip/mate/channel/webchat/WebChatController.java
index 45ae4076..08794503 100644
--- a/mateclaw-server/src/main/java/vip/mate/channel/webchat/WebChatController.java
+++ b/mateclaw-server/src/main/java/vip/mate/channel/webchat/WebChatController.java
@@ -1362,6 +1362,8 @@ public class WebChatController {
conversationId, actor, wsId, null).withSender(null, "api", null);
}
+ replayOrigin = replayOrigin.withApprovalId(snapshot.getPendingId());
+
// Neutral replay prompt (aligned with IM + web channels — naming a
// tool here can mislead the LLM on fallthrough).
String replayPrompt = "继续执行已批准的工具调用。";
diff --git a/mateclaw-server/src/main/java/vip/mate/common/result/R.java b/mateclaw-server/src/main/java/vip/mate/common/result/R.java
index 17be7aaf..55558ff0 100644
--- a/mateclaw-server/src/main/java/vip/mate/common/result/R.java
+++ b/mateclaw-server/src/main/java/vip/mate/common/result/R.java
@@ -3,6 +3,7 @@ package vip.mate.common.result;
import lombok.Data;
import java.io.Serializable;
+import java.util.concurrent.atomic.AtomicReference;
/**
* 统一响应结果封装
@@ -24,12 +25,18 @@ public class R implements Serializable {
private T data;
/** i18n holder — set once at startup by I18nAutoConfig, used by ok()/fail() */
- private static volatile vip.mate.i18n.I18nService i18n;
+ private static final AtomicReference I18N = new AtomicReference<>();
- public static void setI18n(vip.mate.i18n.I18nService service) { i18n = service; }
+ public static void setI18n(vip.mate.i18n.I18nService service) { I18N.set(service); }
+
+ /** Clear a closing context's service without clobbering a newer context. */
+ public static void clearI18n(vip.mate.i18n.I18nService service) {
+ I18N.compareAndSet(service, null);
+ }
private static String resolveMsg(ResultCode rc) {
- return i18n != null ? rc.getMsg(i18n) : rc.getMsg();
+ vip.mate.i18n.I18nService service = I18N.get();
+ return service != null ? rc.getMsg(service) : rc.getMsg();
}
public static R ok() {
diff --git a/mateclaw-server/src/main/java/vip/mate/config/JwtAuthFilter.java b/mateclaw-server/src/main/java/vip/mate/config/JwtAuthFilter.java
index 71aaf2a1..745c5b17 100644
--- a/mateclaw-server/src/main/java/vip/mate/config/JwtAuthFilter.java
+++ b/mateclaw-server/src/main/java/vip/mate/config/JwtAuthFilter.java
@@ -95,6 +95,10 @@ public class JwtAuthFilter extends OncePerRequestFilter {
String username = claims.getSubject();
UserEntity user = authService.findByUsername(username);
if (user == null || !Boolean.TRUE.equals(user.getEnabled())) return;
+ // A reused username must not turn an old signed token into the new account's identity.
+ // AuthService issues userId; missing or malformed claims require a fresh login.
+ Long tokenUserId = claims.get("userId", Long.class);
+ if (tokenUserId == null || !tokenUserId.equals(user.getId())) return;
var auth = new UsernamePasswordAuthenticationToken(
username, null,
@@ -105,7 +109,8 @@ public class JwtAuthFilter extends OncePerRequestFilter {
// 滑动窗口续期：Token 接近过期时自动签发新 Token
if (authService.isNearExpiry(claims)) {
- String newToken = authService.renewToken(username);
+ // Renew the validated identity, without resolving a potentially reassigned username again.
+ String newToken = authService.generateToken(user);
if (newToken != null) {
response.setHeader("X-New-Token", newToken);
response.setHeader("Access-Control-Expose-Headers", "X-New-Token");
diff --git a/mateclaw-server/src/main/java/vip/mate/config/SchedulingConfig.java b/mateclaw-server/src/main/java/vip/mate/config/SchedulingConfig.java
index ab832b1e..18c5e410 100644
--- a/mateclaw-server/src/main/java/vip/mate/config/SchedulingConfig.java
+++ b/mateclaw-server/src/main/java/vip/mate/config/SchedulingConfig.java
@@ -41,6 +41,9 @@ public class SchedulingConfig implements SchedulingConfigurer {
scheduler.setPoolSize(POOL_SIZE);
scheduler.setThreadNamePrefix("sched-");
scheduler.setRemoveOnCancelPolicy(true);
+ // Pending future ticks belong to the next application lifetime. Keeping
+ // them queued would consume the grace period and outlive bean teardown.
+ scheduler.setExecuteExistingDelayedTasksAfterShutdownPolicy(false);
scheduler.setAwaitTerminationSeconds(30);
scheduler.setWaitForTasksToCompleteOnShutdown(true);
return scheduler;
diff --git a/mateclaw-server/src/main/java/vip/mate/config/ToolTimeoutProperties.java b/mateclaw-server/src/main/java/vip/mate/config/ToolTimeoutProperties.java
index 775febed..14ea6001 100644
--- a/mateclaw-server/src/main/java/vip/mate/config/ToolTimeoutProperties.java
+++ b/mateclaw-server/src/main/java/vip/mate/config/ToolTimeoutProperties.java
@@ -34,6 +34,7 @@ public class ToolTimeoutProperties {
"web_fetch", "web",
"url_fetch", "web",
"write_file", "file",
+ "append_file", "file",
"edit_file", "file",
"read_file", "file"
);
diff --git a/mateclaw-server/src/main/java/vip/mate/cron/delivery/AbstractCronResultDelivery.java b/mateclaw-server/src/main/java/vip/mate/cron/delivery/AbstractCronResultDelivery.java
index a74d0fc9..437f1c3d 100644
--- a/mateclaw-server/src/main/java/vip/mate/cron/delivery/AbstractCronResultDelivery.java
+++ b/mateclaw-server/src/main/java/vip/mate/cron/delivery/AbstractCronResultDelivery.java
@@ -96,36 +96,44 @@ public abstract class AbstractCronResultDelivery implements CronResultDelivery {
// ---------- SQL state-machine helpers ----------
/**
- * Atomic SQL CAS: transition delivery_status from {@code NONE} or
- * {@code PENDING} → {@code PENDING}. Returns true iff this instance won
- * the race. NONE-eligibility lets fresh runs claim without a separate
- * "first-time" branch; PENDING-eligibility covers the rare same-instance
- * retry inside the listener.
+ * Atomic SQL CAS: transition delivery_status from {@code NONE} (or legacy
+ * {@code NULL}) to {@code PENDING}. An already-pending row is owned by the
+ * worker that claimed it and must never be claimable again.
*
*
SQL semantics gotcha: {@code IN (...)} never matches NULL. Legacy
* rows from before V57 (pre-RFC) may have null delivery_status, so the
- * predicate explicitly tests {@code IS NULL OR IN (NONE, PENDING)} via
+ * predicate explicitly tests {@code IS NULL OR = NONE} via
* a nested OR group rather than putting null inside the IN list.
*/
private boolean claimRun(CronJobRunEntity run) {
return runMapper.update(null, new LambdaUpdateWrapper()
.eq(CronJobRunEntity::getId, run.getId())
.and(w -> w.isNull(CronJobRunEntity::getDeliveryStatus)
- .or().in(CronJobRunEntity::getDeliveryStatus, "NONE", "PENDING"))
+ .or().eq(CronJobRunEntity::getDeliveryStatus, "NONE"))
.set(CronJobRunEntity::getDeliveryStatus, "PENDING")) == 1;
}
private void markDelivered(CronJobRunEntity run, DeliveryOutcome o) {
- runMapper.update(null, new LambdaUpdateWrapper()
+ int updated = runMapper.update(null, new LambdaUpdateWrapper()
.eq(CronJobRunEntity::getId, run.getId())
+ .eq(CronJobRunEntity::getDeliveryStatus, "PENDING")
.set(CronJobRunEntity::getDeliveryStatus, "DELIVERED")
.set(CronJobRunEntity::getDeliveryTarget, o.target()));
+ if (updated == 0) {
+ log.warn("[CronDelivery] Run {} lost its PENDING fence before success was persisted",
+ run.getId());
+ }
}
private void markNotDelivered(CronJobRunEntity run, Exception e) {
- runMapper.update(null, new LambdaUpdateWrapper()
+ int updated = runMapper.update(null, new LambdaUpdateWrapper()
.eq(CronJobRunEntity::getId, run.getId())
+ .eq(CronJobRunEntity::getDeliveryStatus, "PENDING")
.set(CronJobRunEntity::getDeliveryStatus, "NOT_DELIVERED")
.set(CronJobRunEntity::getDeliveryError, StrUtil.maxLength(e.getMessage(), 500)));
+ if (updated == 0) {
+ log.warn("[CronDelivery] Run {} lost its PENDING fence before failure was persisted",
+ run.getId());
+ }
}
}
diff --git a/mateclaw-server/src/main/java/vip/mate/cron/delivery/CronRunStaleCleanup.java b/mateclaw-server/src/main/java/vip/mate/cron/delivery/CronRunStaleCleanup.java
index 7d5efb41..8eed2c05 100644
--- a/mateclaw-server/src/main/java/vip/mate/cron/delivery/CronRunStaleCleanup.java
+++ b/mateclaw-server/src/main/java/vip/mate/cron/delivery/CronRunStaleCleanup.java
@@ -21,7 +21,7 @@ import java.time.LocalDateTime;
* {@code NOT_DELIVERED} with {@code stale-pending-timeout} reason.
* Covers listener crashes / OOMs / forced kills after a successful
* {@code claimRun()} but before {@code markDelivered}.
- *
{@code status='running'} older than 30 min → mark {@code failed}
+ *
{@code status='running'} without a heartbeat for 2 min → mark {@code failed}
* with {@code stale-running-timeout}. Covers
* {@code CronJobLifecycleService.markRunFailed()} itself failing under
* DB jitter (the LLM call already terminated by then).
@@ -38,7 +38,7 @@ public class CronRunStaleCleanup {
private final CronJobRunMapper runMapper;
private static final Duration DELIVERY_STALE = Duration.ofMinutes(15);
- private static final Duration RUN_STALE = Duration.ofMinutes(30);
+ private static final Duration RUN_STALE = Duration.ofMinutes(2);
/**
* RFC-03 Lane G2: in a multi-instance deployment, the sweep is purely
@@ -62,7 +62,7 @@ public class CronRunStaleCleanup {
int staleRunning = runMapper.update(null, new LambdaUpdateWrapper()
.eq(CronJobRunEntity::getStatus, "running")
- .lt(CronJobRunEntity::getStartedAt, now.minus(RUN_STALE))
+ .apply("COALESCE(heartbeat_at, started_at) < {0}", now.minus(RUN_STALE))
.set(CronJobRunEntity::getStatus, "failed")
.set(CronJobRunEntity::getFinishedAt, now)
.set(CronJobRunEntity::getErrorMessage, "stale-running-timeout"));
diff --git a/mateclaw-server/src/main/java/vip/mate/cron/service/CronJobLifecycleService.java b/mateclaw-server/src/main/java/vip/mate/cron/service/CronJobLifecycleService.java
index 5fa8d813..33998212 100644
--- a/mateclaw-server/src/main/java/vip/mate/cron/service/CronJobLifecycleService.java
+++ b/mateclaw-server/src/main/java/vip/mate/cron/service/CronJobLifecycleService.java
@@ -71,7 +71,9 @@ public class CronJobLifecycleService {
run.setConversationId(conversationId);
run.setStatus("running");
run.setTriggerType(triggerType != null ? triggerType : "scheduled");
- run.setStartedAt(LocalDateTime.now());
+ LocalDateTime now = LocalDateTime.now();
+ run.setStartedAt(now);
+ run.setHeartbeatAt(now);
run.setDeliveryStatus("NONE");
runMapper.insert(run);
@@ -130,11 +132,47 @@ public class CronJobLifecycleService {
String message = error != null && error.getMessage() != null ? error.getMessage() : "unknown error";
runMapper.update(null, new LambdaUpdateWrapper()
.eq(CronJobRunEntity::getId, run.getId())
+ .eq(CronJobRunEntity::getStatus, "running")
.set(CronJobRunEntity::getStatus, "failed")
.set(CronJobRunEntity::getFinishedAt, LocalDateTime.now())
.set(CronJobRunEntity::getErrorMessage, StrUtil.maxLength(message, 1000)));
}
+ /**
+ * T-fail — terminal graph failure that arrived as structured stream metadata
+ * rather than a thrown exception. Persist the diagnostic assistant message
+ * for conversation coherence, but never publish success, memory, or delivery
+ * events for an {@code error_fallback} result.
+ */
+ @Transactional(propagation = Propagation.REQUIRES_NEW)
+ public void finishRunFailed(CronJobRunEntity run, AssistantMessage result,
+ String conversationId, AgentService.ChatResult chatResult) {
+ String convId = conversationId != null ? conversationId : run.getConversationId();
+ String text = result != null && result.getText() != null ? result.getText() : "";
+ int totalTokens = chatResult != null
+ ? chatResult.promptTokens() + chatResult.completionTokens() : 0;
+ int updated = runMapper.update(null, new LambdaUpdateWrapper()
+ .eq(CronJobRunEntity::getId, run.getId())
+ .eq(CronJobRunEntity::getStatus, "running")
+ .set(CronJobRunEntity::getStatus, "failed")
+ .set(CronJobRunEntity::getFinishedAt, LocalDateTime.now())
+ .set(CronJobRunEntity::getErrorMessage, StrUtil.maxLength(text, 1000))
+ .set(totalTokens > 0, CronJobRunEntity::getTokenUsage, totalTokens));
+ if (updated == 0) {
+ log.warn("[CronLifecycle] Run {} lost its running fence before graph failure; dropping late result",
+ run.getId());
+ return;
+ }
+
+ if (chatResult != null) {
+ conversationService.saveMessage(convId, "assistant", text, null, "error",
+ chatResult.promptTokens(), chatResult.completionTokens(),
+ chatResult.runtimeModel(), chatResult.runtimeProvider());
+ } else {
+ conversationService.saveMessage(convId, "assistant", text, null, "error");
+ }
+ }
+
/**
* Insert a {@code running} run row for a task type that does not produce
* a conversation (e.g. {@code wiki_process}). No header / user message is
@@ -148,7 +186,9 @@ public class CronJobLifecycleService {
run.setConversationId(null);
run.setStatus("running");
run.setTriggerType(triggerType != null ? triggerType : "scheduled");
- run.setStartedAt(LocalDateTime.now());
+ LocalDateTime now = LocalDateTime.now();
+ run.setStartedAt(now);
+ run.setHeartbeatAt(now);
run.setDeliveryStatus("NONE");
runMapper.insert(run);
return run;
@@ -162,12 +202,16 @@ public class CronJobLifecycleService {
*/
@Transactional(propagation = Propagation.REQUIRES_NEW)
public void markRunSucceeded(CronJobRunEntity run, String description) {
- runMapper.update(null, new LambdaUpdateWrapper()
+ int updated = runMapper.update(null, new LambdaUpdateWrapper()
.eq(CronJobRunEntity::getId, run.getId())
+ .eq(CronJobRunEntity::getStatus, "running")
.set(CronJobRunEntity::getStatus, "succeeded")
.set(CronJobRunEntity::getFinishedAt, LocalDateTime.now())
.set(CronJobRunEntity::getErrorMessage,
description != null ? StrUtil.maxLength(description, 1000) : null));
+ if (updated == 0) {
+ log.warn("[CronLifecycle] Run {} lost its running fence before system completion", run.getId());
+ }
}
/**
@@ -205,11 +249,17 @@ public class CronJobLifecycleService {
int totalTokens = chatResult != null
? chatResult.promptTokens() + chatResult.completionTokens() : 0;
- runMapper.update(null, new LambdaUpdateWrapper()
+ int updated = runMapper.update(null, new LambdaUpdateWrapper()
.eq(CronJobRunEntity::getId, run.getId())
+ .eq(CronJobRunEntity::getStatus, "running")
.set(CronJobRunEntity::getStatus, "succeeded")
.set(CronJobRunEntity::getFinishedAt, LocalDateTime.now())
.set(totalTokens > 0, CronJobRunEntity::getTokenUsage, totalTokens));
+ if (updated == 0) {
+ log.warn("[CronLifecycle] Run {} lost its running fence before completion; dropping late result",
+ run.getId());
+ return;
+ }
if (silent) {
// No-op run: persist a short marker so the tasks_
diff --git a/mateclaw-server/src/main/java/vip/mate/cron/service/CronJobRunner.java b/mateclaw-server/src/main/java/vip/mate/cron/service/CronJobRunner.java
index 796eb306..4b9fcb3a 100644
--- a/mateclaw-server/src/main/java/vip/mate/cron/service/CronJobRunner.java
+++ b/mateclaw-server/src/main/java/vip/mate/cron/service/CronJobRunner.java
@@ -8,6 +8,8 @@ import org.springframework.ai.chat.messages.AssistantMessage;
import org.springframework.stereotype.Component;
import vip.mate.agent.AgentService;
import vip.mate.agent.context.ChatOrigin;
+import vip.mate.agent.context.ExecutionAttribution;
+import vip.mate.agent.graph.state.FinishReason;
import vip.mate.cron.CronChatOriginFactory;
import vip.mate.cron.model.CronJobEntity;
import vip.mate.dashboard.model.CronJobRunEntity;
@@ -42,6 +44,7 @@ import vip.mate.wiki.service.WikiProcessingService;
public class CronJobRunner {
private final CronJobLifecycleService lifecycle;
+ private final CronRunHeartbeatService heartbeat;
private final AgentService agentService;
private final CronChatOriginFactory originFactory;
private final vip.mate.cron.CronConversationResolver conversationResolver;
@@ -144,14 +147,18 @@ public class CronJobRunner {
try {
ChatOrigin origin = originFactory.from(
job, conversationId, started.originMessageId());
- chatResult = runAgent(job, userMessage, origin, conversationId);
+ origin = origin.withExecutionAttribution(new ExecutionAttribution(null, null, run.getId(), null,
+ "cron:" + run.getId()));
+ try (CronRunHeartbeatService.Lease ignored = heartbeat.begin(run.getId())) {
+ chatResult = runAgent(job, userMessage, origin, conversationId);
+ }
result = new AssistantMessage(chatResult.content());
} catch (Exception e) {
log.error("[CronRunner] runAgent failed for job {}: {}", job.getId(), e.getMessage(), e);
try {
lifecycle.markRunFailed(run, e);
} catch (Exception markErr) {
- // CronRunStaleCleanup will sweep status='running' rows older than 30 min.
+ // CronRunStaleCleanup will recover a run after its heartbeat expires.
log.warn("[CronRunner] markRunFailed itself failed for run {}: {} (stale-cleanup will recover)",
run.getId(), markErr.getMessage());
}
@@ -165,6 +172,10 @@ public class CronJobRunner {
// T2 — short tx
try {
+ if (FinishReason.ERROR_FALLBACK.getValue().equals(chatResult.finishReason())) {
+ lifecycle.finishRunFailed(run, result, conversationId, chatResult);
+ return;
+ }
lifecycle.finishRunAndPublish(job, run, userMessage, result, conversationId, silent, chatResult);
} catch (Exception e) {
log.error("[CronRunner] T2 finishRunAndPublish failed for job {}: {}", job.getId(), e.getMessage(), e);
diff --git a/mateclaw-server/src/main/java/vip/mate/cron/service/CronRunHeartbeatService.java b/mateclaw-server/src/main/java/vip/mate/cron/service/CronRunHeartbeatService.java
new file mode 100644
index 00000000..a0151a4e
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/cron/service/CronRunHeartbeatService.java
@@ -0,0 +1,107 @@
+package vip.mate.cron.service;
+
+import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
+import jakarta.annotation.PreDestroy;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Service;
+import vip.mate.dashboard.model.CronJobRunEntity;
+import vip.mate.dashboard.repository.CronJobRunMapper;
+
+import java.time.Clock;
+import java.time.Duration;
+import java.time.LocalDateTime;
+import java.util.Objects;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.ScheduledFuture;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+/** Maintains a durable liveness signal while a cron run is inside a long agent call. */
+@Slf4j
+@Service
+public class CronRunHeartbeatService {
+
+ static final Duration DEFAULT_INTERVAL = Duration.ofSeconds(30);
+
+ private final CronJobRunMapper runMapper;
+ private final ScheduledExecutorService scheduler;
+ private final Duration interval;
+ private final Clock clock;
+ private final boolean ownsScheduler;
+
+ @Autowired
+ public CronRunHeartbeatService(CronJobRunMapper runMapper) {
+ this(runMapper, newScheduler(), DEFAULT_INTERVAL, Clock.systemDefaultZone(), true);
+ }
+
+ CronRunHeartbeatService(CronJobRunMapper runMapper,
+ ScheduledExecutorService scheduler,
+ Duration interval,
+ Clock clock,
+ boolean ownsScheduler) {
+ this.runMapper = Objects.requireNonNull(runMapper, "runMapper");
+ this.scheduler = Objects.requireNonNull(scheduler, "scheduler");
+ this.interval = Objects.requireNonNull(interval, "interval");
+ this.clock = Objects.requireNonNull(clock, "clock");
+ this.ownsScheduler = ownsScheduler;
+ if (interval.isZero() || interval.isNegative()) {
+ throw new IllegalArgumentException("heartbeat interval must be positive");
+ }
+ }
+
+ /**
+ * Start refreshing one run. The returned lease is idempotent and must be
+ * closed when the long call exits, including exceptional exits.
+ */
+ public Lease begin(Long runId) {
+ Objects.requireNonNull(runId, "runId");
+ long periodMillis = interval.toMillis();
+ ScheduledFuture future = scheduler.scheduleAtFixedRate(
+ () -> safeTouch(runId), periodMillis, periodMillis, TimeUnit.MILLISECONDS);
+ AtomicBoolean closed = new AtomicBoolean();
+ return () -> {
+ if (closed.compareAndSet(false, true)) {
+ future.cancel(false);
+ }
+ };
+ }
+
+ private void safeTouch(Long runId) {
+ try {
+ int updated = runMapper.update(null, new LambdaUpdateWrapper()
+ .eq(CronJobRunEntity::getId, runId)
+ .eq(CronJobRunEntity::getStatus, "running")
+ .set(CronJobRunEntity::getHeartbeatAt, LocalDateTime.now(clock)));
+ if (updated == 0) {
+ log.debug("[CronHeartbeat] Run {} is no longer running; heartbeat ignored", runId);
+ }
+ } catch (RuntimeException e) {
+ // ScheduledExecutorService suppresses all later ticks if a task
+ // escapes with an exception. Keep the liveness loop recoverable.
+ log.warn("[CronHeartbeat] Failed to refresh run {}: {}", runId, e.getMessage());
+ }
+ }
+
+ @PreDestroy
+ void shutdown() {
+ if (ownsScheduler) {
+ scheduler.shutdownNow();
+ }
+ }
+
+ private static ScheduledExecutorService newScheduler() {
+ return Executors.newSingleThreadScheduledExecutor(runnable -> {
+ Thread thread = new Thread(runnable, "cron-run-heartbeat");
+ thread.setDaemon(true);
+ return thread;
+ });
+ }
+
+ @FunctionalInterface
+ public interface Lease extends AutoCloseable {
+ @Override
+ void close();
+ }
+}
diff --git a/mateclaw-server/src/main/java/vip/mate/dashboard/model/CronJobRunEntity.java b/mateclaw-server/src/main/java/vip/mate/dashboard/model/CronJobRunEntity.java
index 91dbab9e..5afd2596 100644
--- a/mateclaw-server/src/main/java/vip/mate/dashboard/model/CronJobRunEntity.java
+++ b/mateclaw-server/src/main/java/vip/mate/dashboard/model/CronJobRunEntity.java
@@ -16,6 +16,8 @@ public class CronJobRunEntity {
/** scheduled / manual */
private String triggerType;
private LocalDateTime startedAt;
+ /** Last durable liveness signal while the run is executing. */
+ private LocalDateTime heartbeatAt;
private LocalDateTime finishedAt;
private String errorMessage;
private Integer tokenUsage;
diff --git a/mateclaw-server/src/main/java/vip/mate/execution/evidence/ExecutionEvidenceProperties.java b/mateclaw-server/src/main/java/vip/mate/execution/evidence/ExecutionEvidenceProperties.java
new file mode 100644
index 00000000..d17f342c
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/execution/evidence/ExecutionEvidenceProperties.java
@@ -0,0 +1,34 @@
+package vip.mate.execution.evidence;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.stereotype.Component;
+
+@Component
+@ConfigurationProperties(prefix = "mateclaw.execution-evidence")
+public class ExecutionEvidenceProperties {
+ public enum Mode { OFF, OBSERVE, ENFORCE }
+ private Mode mode = Mode.OBSERVE;
+ private int retentionDays = 90;
+ private int artifactVersionCheckMaxBytes = 1_048_576;
+ public int getArtifactVersionCheckMaxBytes() { return artifactVersionCheckMaxBytes; }
+ public void setArtifactVersionCheckMaxBytes(int value) { artifactVersionCheckMaxBytes = Math.clamp(value, 0, 16_777_216); }
+ private int cleanupMaxBatches = 10;
+ public int getCleanupMaxBatches() { return cleanupMaxBatches; }
+ public void setCleanupMaxBatches(int value) { cleanupMaxBatches = Math.clamp(value, 1, 100); }
+ private int maxObservations = 32;
+ public int getMaxObservations() { return maxObservations; }
+ public void setMaxObservations(int value) { maxObservations = Math.clamp(value, 1, 99); }
+ private int maxSummaryBytes = 2048;
+ private int defaultListLimit = 20;
+ private int maxListLimit = 100;
+ public Mode getMode() { return mode; }
+ public void setMode(Mode mode) { this.mode = mode; }
+ public int getRetentionDays() { return retentionDays; }
+ public void setRetentionDays(int value) { retentionDays = Math.max(1, value); }
+ public int getMaxSummaryBytes() { return maxSummaryBytes; }
+ public void setMaxSummaryBytes(int value) { maxSummaryBytes = Math.clamp(value, 1, 2048); }
+ public int getDefaultListLimit() { return defaultListLimit; }
+ public void setDefaultListLimit(int value) { defaultListLimit = Math.clamp(value, 1, 100); }
+ public int getMaxListLimit() { return maxListLimit; }
+ public void setMaxListLimit(int value) { maxListLimit = Math.clamp(value, 1, 100); }
+}
diff --git a/mateclaw-server/src/main/java/vip/mate/execution/evidence/controller/ExecutionEvidenceController.java b/mateclaw-server/src/main/java/vip/mate/execution/evidence/controller/ExecutionEvidenceController.java
new file mode 100644
index 00000000..4ff14b9d
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/execution/evidence/controller/ExecutionEvidenceController.java
@@ -0,0 +1,53 @@
+package vip.mate.execution.evidence.controller;
+
+import lombok.RequiredArgsConstructor;
+import org.springframework.security.core.Authentication;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import java.util.List;
+import vip.mate.execution.evidence.service.JsonArtifactRecipe;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+import vip.mate.common.result.R;
+import vip.mate.execution.evidence.service.ExecutionEvidenceQueryService;
+
+/** Source-authorized, read-only observations. There is deliberately no evidence write endpoint. */
+@RestController
+@RequestMapping("/api/v1/execution-evidence")
+@RequiredArgsConstructor
+public class ExecutionEvidenceController {
+ private final ExecutionEvidenceQueryService queries;
+
+ @GetMapping
+ public R list(Authentication auth,
+ @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId,
+ @RequestParam String conversationId,
+ @RequestParam(required = false) String cursor,
+ @RequestParam(required = false) Integer limit,
+ @RequestParam(required = false) Long goalId,
+ @RequestParam(required = false) Long teamTaskId) {
+ return R.ok(queries.list(auth == null ? null : auth.getName(), workspaceId, conversationId,
+ cursor, limit, goalId, teamTaskId));
+ }
+
+ @GetMapping("/{id}")
+ public R detail(Authentication auth,
+ @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId,
+ @PathVariable Long id) {
+ return R.ok(queries.detail(auth == null ? null : auth.getName(), workspaceId, id));
+ }
+ public record JsonCheckRequest(List requiredFields) { }
+
+ @PostMapping("/{id}/json-check")
+ public R checkJson(Authentication auth,
+ @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId,
+ @PathVariable Long id, @RequestBody JsonCheckRequest request) {
+ return R.ok(queries.checkJson(auth == null ? null : auth.getName(), workspaceId, id,
+ request == null ? null : request.requiredFields()));
+ }
+
+}
diff --git a/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/AttemptState.java b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/AttemptState.java
new file mode 100644
index 00000000..c0aba699
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/AttemptState.java
@@ -0,0 +1,3 @@
+package vip.mate.execution.evidence.model;
+
+public enum AttemptState { STARTED, SUCCEEDED, FAILED, CANCELLED, UNKNOWN, BLOCKED }
diff --git a/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/BeginResult.java b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/BeginResult.java
new file mode 100644
index 00000000..f473ba2b
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/BeginResult.java
@@ -0,0 +1,4 @@
+package vip.mate.execution.evidence.model;
+
+/** Only the successful inserter may initiate a new execution. */
+public record BeginResult(ExecutionAttempt attempt, boolean created) { }
diff --git a/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/EffectOutcome.java b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/EffectOutcome.java
new file mode 100644
index 00000000..28fadfe4
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/EffectOutcome.java
@@ -0,0 +1,3 @@
+package vip.mate.execution.evidence.model;
+
+public enum EffectOutcome { NONE, CONFIRMED, UNCERTAIN }
diff --git a/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/EvidenceKind.java b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/EvidenceKind.java
new file mode 100644
index 00000000..1bfdef42
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/EvidenceKind.java
@@ -0,0 +1,3 @@
+package vip.mate.execution.evidence.model;
+
+public enum EvidenceKind { TOOL_RETURNED, COMMAND_EXIT, CHECK_RESULT, ARTIFACT_SNAPSHOT }
diff --git a/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/EvidenceObservation.java b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/EvidenceObservation.java
new file mode 100644
index 00000000..bba651cb
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/EvidenceObservation.java
@@ -0,0 +1,15 @@
+package vip.mate.execution.evidence.model;
+
+import java.time.Instant;
+
+/** Allowlisted execution metadata; raw invocation parameters are never accepted. */
+public record EvidenceObservation(String sourceKey, EvidenceKind kind, EvidenceResult result,
+ SourceLevel sourceLevel, Long scopeId, Long generation, String inputFingerprint,
+ String recipeId, Long recipeRevision, String checkScope, String artifactRef,
+ String artifactDigest, String summary, String payloadRef, Instant observedAt, Instant expiresAt) {
+ public EvidenceObservation(String sourceKey, EvidenceKind kind, EvidenceResult result,
+ SourceLevel sourceLevel, String summary) {
+ this(sourceKey, kind, result, sourceLevel, null, null, null, null, null, null,
+ null, null, summary, null, null, null);
+ }
+}
diff --git a/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/EvidenceResult.java b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/EvidenceResult.java
new file mode 100644
index 00000000..c5e84157
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/EvidenceResult.java
@@ -0,0 +1,3 @@
+package vip.mate.execution.evidence.model;
+
+public enum EvidenceResult { OBSERVED, PASS, FAIL, UNKNOWN }
diff --git a/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/EvidenceScope.java b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/EvidenceScope.java
new file mode 100644
index 00000000..c67fc925
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/EvidenceScope.java
@@ -0,0 +1,5 @@
+package vip.mate.execution.evidence.model;
+
+/** Persisted resource identity reserved for managed validation scopes. */
+public record EvidenceScope(Long id, Long workspaceId, String resourceKey, String hostId,
+ String rootId, long generation, int activeMutations, boolean tainted) { }
diff --git a/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/ExecutionAttempt.java b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/ExecutionAttempt.java
new file mode 100644
index 00000000..514fc27f
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/ExecutionAttempt.java
@@ -0,0 +1,6 @@
+package vip.mate.execution.evidence.model;
+
+import java.time.Instant;
+
+public record ExecutionAttempt(Long id, ExecutionIdentity identity, AttemptState state, EffectOutcome effectOutcome,
+ Instant startedAt, Instant finishedAt) { }
diff --git a/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/ExecutionEvidence.java b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/ExecutionEvidence.java
new file mode 100644
index 00000000..eebda5e7
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/ExecutionEvidence.java
@@ -0,0 +1,3 @@
+package vip.mate.execution.evidence.model;
+
+public record ExecutionEvidence(Long id, Long workspaceId, Long attemptId, String conversationId, EvidenceObservation observation) { }
diff --git a/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/ExecutionIdentity.java b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/ExecutionIdentity.java
new file mode 100644
index 00000000..60b4f28f
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/ExecutionIdentity.java
@@ -0,0 +1,6 @@
+package vip.mate.execution.evidence.model;
+
+public record ExecutionIdentity(Long workspaceId, String conversationId, String runtimeKind, String runtimeSessionId,
+ String invocationKey, String logicalCallId, int attemptNo, String providerToolCallId,
+ String toolName, Long goalId, String goalAttemptId, Long teamRunId, Long teamTaskId,
+ Long cronRunId, String approvalId, String ownerFence) { }
diff --git a/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/GoalCriterionEvidence.java b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/GoalCriterionEvidence.java
new file mode 100644
index 00000000..aaad15d2
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/GoalCriterionEvidence.java
@@ -0,0 +1,7 @@
+package vip.mate.execution.evidence.model;
+
+import java.time.Instant;
+
+/** Versioned binding metadata; creating a binding requires separate source authorization. */
+public record GoalCriterionEvidence(Long id, Long workspaceId, Long goalId, String criterionId,
+ long criterionRevision, Long evidenceId, Instant boundAt) { }
diff --git a/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/SourceLevel.java b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/SourceLevel.java
new file mode 100644
index 00000000..590714fe
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/execution/evidence/model/SourceLevel.java
@@ -0,0 +1,3 @@
+package vip.mate.execution.evidence.model;
+
+public enum SourceLevel { PLATFORM_OBSERVED, ADAPTER_ATTESTED, EXTERNAL_REPORTED, LEGACY_TEXT }
diff --git a/mateclaw-server/src/main/java/vip/mate/execution/evidence/service/ExecutionEvidenceLifecycle.java b/mateclaw-server/src/main/java/vip/mate/execution/evidence/service/ExecutionEvidenceLifecycle.java
new file mode 100644
index 00000000..a10d32f3
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/execution/evidence/service/ExecutionEvidenceLifecycle.java
@@ -0,0 +1,35 @@
+package vip.mate.execution.evidence.service;
+
+import org.springframework.context.event.EventListener;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+import vip.mate.workspace.conversation.event.ConversationDeletedEvent;
+import vip.mate.execution.evidence.ExecutionEvidenceProperties;
+
+import java.time.Instant;
+
+/** Metadata retention is independent of source-file retention and respects conversation deletion. */
+@Component
+public class ExecutionEvidenceLifecycle {
+ private final ExecutionEvidenceStore store;
+
+ private final ExecutionEvidenceProperties properties;
+
+ public ExecutionEvidenceLifecycle(ExecutionEvidenceStore store, ExecutionEvidenceProperties properties) {
+ this.store = store;
+ this.properties = properties;
+ }
+
+ @EventListener
+ public void onConversationDeleted(ConversationDeletedEvent event) {
+ store.purgeConversation(event.conversationId());
+ }
+
+ @Scheduled(fixedDelayString = "${mateclaw.execution-evidence.cleanup-interval-ms:60000}")
+ public void cleanup() {
+ Instant now = Instant.now();
+ for (int batch = 0; batch < properties.getCleanupMaxBatches(); batch++) {
+ if (store.purgeExpiredMetadata(now, 100) < 100) break;
+ }
+ }
+}
diff --git a/mateclaw-server/src/main/java/vip/mate/execution/evidence/service/ExecutionEvidenceQueryService.java b/mateclaw-server/src/main/java/vip/mate/execution/evidence/service/ExecutionEvidenceQueryService.java
new file mode 100644
index 00000000..cf748663
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/execution/evidence/service/ExecutionEvidenceQueryService.java
@@ -0,0 +1,180 @@
+package vip.mate.execution.evidence.service;
+
+import org.springframework.stereotype.Service;
+import vip.mate.execution.evidence.ExecutionEvidenceProperties;
+import vip.mate.execution.evidence.model.AttemptState;
+import vip.mate.execution.evidence.model.EffectOutcome;
+import vip.mate.execution.evidence.model.EvidenceKind;
+import vip.mate.execution.evidence.model.EvidenceResult;
+import vip.mate.execution.evidence.model.SourceLevel;
+import vip.mate.auth.service.AuthService;
+import vip.mate.team.service.TeamWorkerConversationGovernanceService;
+import vip.mate.tool.document.GeneratedFileCache;
+import vip.mate.workspace.conversation.ConversationService;
+import vip.mate.workspace.core.service.WorkspaceService;
+import io.micrometer.core.instrument.MeterRegistry;
+import vip.mate.exception.MateClawException;
+import vip.mate.execution.evidence.model.ExecutionEvidence;
+import vip.mate.execution.evidence.model.ExecutionAttempt;
+
+import java.nio.charset.StandardCharsets;
+import java.time.Instant;
+import java.util.Base64;
+import java.util.List;
+import java.util.Objects;
+import java.util.concurrent.TimeUnit;
+
+@Service
+public class ExecutionEvidenceQueryService {
+ public record View(Long id, Long attemptId, String conversationId, String toolName, AttemptState state,
+ EffectOutcome effectOutcome, EvidenceKind kind, EvidenceResult result, SourceLevel sourceLevel,
+ String validity, String summary, Instant observedAt, Instant expiresAt,
+ String artifactRef, String artifactDigest, String checkScope) { }
+ public record Page(List items, String nextCursor) { }
+ private record Cursor(Instant observedAt, Long id) { }
+ private final ExecutionEvidenceStore store;
+ private final ConversationService conversations;
+ private final TeamWorkerConversationGovernanceService teams;
+ private final GeneratedFileCache files;
+ private final AuthService auth;
+ private final WorkspaceService workspaces;
+ private final ExecutionEvidenceProperties properties;
+ private final MeterRegistry metrics;
+
+ public ExecutionEvidenceQueryService(ExecutionEvidenceStore store, ConversationService conversations,
+ TeamWorkerConversationGovernanceService teams, GeneratedFileCache files,
+ AuthService auth, WorkspaceService workspaces, ExecutionEvidenceProperties properties, MeterRegistry metrics) {
+ this.store = store;
+ this.conversations = conversations;
+ this.teams = teams;
+ this.files = files;
+ this.auth = auth;
+ this.workspaces = workspaces;
+ this.properties = properties;
+ this.metrics = metrics;
+ }
+
+ public Page list(String username, Long workspaceId, String conversationId, String cursor, Integer limit,
+ Long goalId, Long teamTaskId) {
+ long started = System.nanoTime();
+ try {
+ Long canonicalWorkspace = authorize(username, workspaceId, conversationId);
+ int bounded = Math.clamp(limit == null ? properties.getDefaultListLimit() : limit, 1, properties.getMaxListLimit());
+ Cursor before = decode(cursor);
+ List rows = store.list(canonicalWorkspace, conversationId, before.observedAt(),
+ before.id(), bounded + 1, goalId, teamTaskId);
+ boolean hasMore = rows.size() > bounded;
+ List page = rows.stream().limit(bounded).toList();
+ if (page.isEmpty()) return new Page(List.of(), null);
+ var attempts = store.findAttempts(canonicalWorkspace, conversationId,
+ page.stream().map(ExecutionEvidence::attemptId).distinct().toList());
+ return new Page(page.stream().map(row -> view(username, row, attempts.get(row.attemptId()), false)).toList(),
+ hasMore ? encode(page.getLast()) : null);
+ } finally {
+ metrics.timer("mateclaw.execution.evidence.query.latency").record(
+ System.nanoTime() - started, TimeUnit.NANOSECONDS);
+ }
+ }
+
+ public View detail(String username, Long workspaceId, Long id) {
+ return authorizedDetail(username, workspaceId, id, true);
+ }
+
+ private View authorizedDetail(String username, Long workspaceId, Long id, boolean inspectVersion) {
+ if (username == null || username.isBlank() || id == null) throw hidden();
+ ExecutionEvidence row = store.findById(id).orElseThrow(this::hidden);
+ Long canonicalWorkspace = authorize(username, workspaceId, row.conversationId());
+ if (!canonicalWorkspace.equals(row.workspaceId())) throw hidden();
+ return view(username, row, store.findAttempt(row.attemptId()).orElseThrow(this::hidden), inspectVersion);
+ }
+
+ public JsonArtifactRecipe.Result checkJson(String username, Long workspaceId, Long id, List fields) {
+ // Reuse source, attempt and file authorization before any content read.
+ View view = authorizedDetail(username, workspaceId, id, false);
+ List required = JsonArtifactRecipe.validate(fields);
+ if (view.kind() != EvidenceKind.ARTIFACT_SNAPSHOT || view.artifactRef() == null
+ || "UNAVAILABLE".equals(view.validity())) {
+ return JsonArtifactRecipe.outcome("UNAVAILABLE", required, List.of());
+ }
+ Long ownerWorkspace = authorize(username, workspaceId, view.conversationId());
+ var read = files.readDurableArtifactSnapshot(view.artifactRef(), ownerWorkspace, view.conversationId(),
+ view.artifactDigest(), properties.getArtifactVersionCheckMaxBytes());
+ return "READ".equals(read.status()) ? JsonArtifactRecipe.check(read.bytes(), required)
+ : JsonArtifactRecipe.outcome(read.status(), required, List.of());
+ }
+
+ private Long authorize(String username, Long workspaceId, String conversationId) {
+ if (username == null || username.isBlank() || conversationId == null || conversationId.isBlank()) throw hidden();
+ var conversation = conversations.findByConversationId(conversationId);
+ if (conversation == null || conversation.getWorkspaceId() == null || Integer.valueOf(1).equals(conversation.getDeleted())
+ || workspaceId != null && !workspaceId.equals(conversation.getWorkspaceId())) throw hidden();
+ if (!conversations.isConversationOwner(conversationId, username)
+ && !teams.canReadTranscript(conversationId, null, null, username)) throw hidden();
+ return conversation.getWorkspaceId();
+ }
+
+ private View view(String username, ExecutionEvidence row, ExecutionAttempt attempt, boolean inspectVersion) {
+ if (attempt == null || !Objects.equals(attempt.id(), row.attemptId())) throw hidden();
+ if (!Objects.equals(attempt.identity().workspaceId(), row.workspaceId())
+ || !Objects.equals(attempt.identity().conversationId(), row.conversationId())) throw hidden();
+ var evidence = row.observation();
+ String validity = "UNKNOWN";
+ String artifact = evidence.artifactRef();
+ String digest = evidence.artifactDigest();
+ String summary = evidence.summary();
+ if (evidence.expiresAt() != null && !evidence.expiresAt().isAfter(Instant.now())) validity = "UNAVAILABLE";
+ if (evidence.kind() == EvidenceKind.ARTIFACT_SNAPSHOT) {
+ var user = auth.findByUsername(username);
+ boolean canReadFile = user != null && ("admin".equalsIgnoreCase(user.getRole())
+ || workspaces.hasPermissionCached(row.workspaceId(), user.getId(), "viewer"));
+ if (!canReadFile) {
+ artifact = null;
+ digest = null;
+ summary = null;
+ validity = "UNAVAILABLE";
+ } else if (!files.isDurablyAvailable(artifact, row.workspaceId(), row.conversationId())) {
+ validity = "UNAVAILABLE";
+ artifact = null;
+ } else if (inspectVersion && !"UNAVAILABLE".equals(validity)) {
+ var version = files.probeDurableArtifactVersion(artifact, row.workspaceId(), row.conversationId(),
+ digest, properties.getArtifactVersionCheckMaxBytes());
+ if (version == GeneratedFileCache.ArtifactVersion.CHANGED) {
+ validity = "STALE";
+ } else if (version == GeneratedFileCache.ArtifactVersion.UNAVAILABLE) {
+ validity = "UNAVAILABLE";
+ artifact = null;
+ }
+ // Equality/budget exhaustion remains UNKNOWN; there is no managed generation fence.
+ }
+ }
+ metrics.counter("mateclaw.execution.evidence.validity", "status", validity).increment();
+ // An available observation is not a freshness or correctness certificate.
+ return new View(row.id(), row.attemptId(), row.conversationId(), attempt.identity().toolName(), attempt.state(),
+ attempt.effectOutcome(), evidence.kind(), evidence.result(), evidence.sourceLevel(), validity,
+ summary, evidence.observedAt(), evidence.expiresAt(), artifact, digest, evidence.checkScope());
+ }
+
+ private Cursor decode(String cursor) {
+ if (cursor == null || cursor.isBlank()) return new Cursor(null, null);
+ try {
+ if (cursor.length() > 256) throw new IllegalArgumentException();
+ String[] parts = new String(Base64.getUrlDecoder().decode(cursor), StandardCharsets.UTF_8).split("\\|", -1);
+ if (parts.length != 2) throw new IllegalArgumentException();
+ long id = Long.parseLong(parts[1]);
+ if (id <= 0) throw new IllegalArgumentException();
+ return new Cursor(Instant.parse(parts[0]), id);
+ } catch (RuntimeException invalid) {
+ throw new MateClawException(400, "Invalid execution evidence cursor");
+ }
+ }
+
+ private String encode(ExecutionEvidence row) {
+ return Base64.getUrlEncoder().withoutPadding().encodeToString(
+ (row.observation().observedAt() + "|" + row.id()).getBytes(StandardCharsets.UTF_8));
+ }
+
+ private MateClawException hidden() {
+ metrics.counter("mateclaw.execution.evidence.query.denied").increment();
+ return new MateClawException(404, "Execution evidence not found");
+ }
+}
diff --git a/mateclaw-server/src/main/java/vip/mate/execution/evidence/service/ExecutionEvidenceRecorder.java b/mateclaw-server/src/main/java/vip/mate/execution/evidence/service/ExecutionEvidenceRecorder.java
new file mode 100644
index 00000000..2f78a0f7
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/execution/evidence/service/ExecutionEvidenceRecorder.java
@@ -0,0 +1,128 @@
+package vip.mate.execution.evidence.service;
+
+import io.micrometer.core.instrument.MeterRegistry;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.ai.chat.model.ToolContext;
+import org.springframework.ai.tool.ToolCallback;
+import org.springframework.stereotype.Service;
+import vip.mate.agent.context.ChatOrigin;
+import vip.mate.execution.evidence.ExecutionEvidenceProperties;
+import vip.mate.execution.evidence.model.AttemptState;
+import vip.mate.execution.evidence.model.EffectOutcome;
+import vip.mate.execution.evidence.model.EvidenceKind;
+import vip.mate.execution.evidence.model.EvidenceObservation;
+import vip.mate.execution.evidence.model.EvidenceResult;
+import vip.mate.execution.evidence.model.ExecutionAttempt;
+import vip.mate.execution.evidence.model.SourceLevel;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.concurrent.CancellationException;
+import java.util.concurrent.TimeUnit;
+
+/** Observes the actual callback boundary. It never interprets returned text as a check result. */
+@Service
+public class ExecutionEvidenceRecorder {
+ private static final Logger log = LoggerFactory.getLogger(ExecutionEvidenceRecorder.class);
+ private final ExecutionEvidenceStore store;
+ private final ExecutionIdentityResolver identities;
+ private final ExecutionEvidenceProperties properties;
+ private final MeterRegistry metrics;
+
+ public ExecutionEvidenceRecorder(ExecutionEvidenceStore store, ExecutionIdentityResolver identities,
+ ExecutionEvidenceProperties properties, MeterRegistry metrics) {
+ this.store = store;
+ this.identities = identities;
+ this.properties = properties;
+ this.metrics = metrics;
+ metrics.gauge("mateclaw.execution.evidence.attempts.unresolved", store, ExecutionEvidenceStore::countUnresolved);
+ if (properties.getMode() == ExecutionEvidenceProperties.Mode.ENFORCE) {
+ throw new IllegalStateException("Execution evidence enforcement requires managed verification scopes; use observe or off");
+ }
+ }
+
+ public String invoke(ToolCallback callback, String arguments, ToolContext context,
+ String invocationKey, String providerCallId) {
+ if (properties.getMode() == ExecutionEvidenceProperties.Mode.OFF) return callback.call(arguments, context);
+ ExecutionAttempt attempt = null;
+ boolean duplicate = false;
+ long began = System.nanoTime();
+ try {
+ var identity = identities.resolve(ChatOrigin.from(context), invocationKey, providerCallId,
+ callback.getToolDefinition().name());
+ if (identity != null) {
+ var reservation = store.reserve(identity);
+ attempt = reservation.attempt();
+ duplicate = !reservation.created();
+ }
+ else metrics.counter("mateclaw.execution.evidence.unattributed").increment();
+ } catch (IllegalStateException conflict) {
+ throw conflict;
+ } catch (RuntimeException failure) {
+ failure("begin");
+ } finally {
+ metrics.timer("mateclaw.execution.evidence.capture.latency", "phase", "begin")
+ .record(System.nanoTime() - began, TimeUnit.NANOSECONDS);
+ }
+ // An existing receipt is not a license to repeat an approved side effect.
+ if (duplicate) {
+ throw new IllegalStateException("Execution already observed; recover the existing approval result");
+ }
+ boolean direct = callback.getToolMetadata() != null && callback.getToolMetadata().returnDirect();
+ var sink = new ExecutionObservationSink(direct, properties.getMaxObservations());
+ try {
+ ToolContext observedContext = context;
+ if (attempt != null) {
+ var values = new HashMap(context.getContext());
+ ChatOrigin canonical = ChatOrigin.from(context).withWorkspace(attempt.identity().workspaceId(),
+ ChatOrigin.from(context).workspaceBasePath());
+ values.put(ChatOrigin.CTX_KEY, canonical);
+ observedContext = sink.attach(new ToolContext(values));
+ }
+ String result = callback.call(arguments, observedContext);
+ finish(attempt, sink, null, "Tool callback returned");
+ return result;
+ } catch (RuntimeException | Error error) {
+ AttemptState state = error instanceof CancellationException || Thread.currentThread().isInterrupted()
+ ? AttemptState.CANCELLED : AttemptState.FAILED;
+ finish(attempt, sink, state, "Tool callback did not complete normally");
+ throw error;
+ }
+ }
+
+ private void finish(ExecutionAttempt attempt, ExecutionObservationSink sink, AttemptState overrideState, String summary) {
+ var captured = sink.sealAndSnapshot();
+ AttemptState state = overrideState != null ? overrideState : captured.state();
+ if (attempt == null) return;
+ long began = System.nanoTime();
+ try {
+ if (!identities.isCurrent(attempt.identity())) {
+ failure("owner_lost");
+ return;
+ }
+ var observations = new ArrayList<>(captured.observations());
+ observations.add(new EvidenceObservation("callback", EvidenceKind.TOOL_RETURNED,
+ state == AttemptState.SUCCEEDED ? EvidenceResult.OBSERVED
+ : state == AttemptState.UNKNOWN || state == AttemptState.CANCELLED
+ ? EvidenceResult.UNKNOWN : EvidenceResult.FAIL,
+ SourceLevel.PLATFORM_OBSERVED, summary));
+ store.finish(attempt.id(), attempt.identity().ownerFence(), state,
+ state == AttemptState.BLOCKED ? EffectOutcome.NONE : EffectOutcome.UNCERTAIN, observations);
+ for (var observation : observations) {
+ metrics.counter("mateclaw.execution.evidence.observations", "kind", observation.kind().name()).increment();
+ }
+ } catch (RuntimeException failure) {
+ // Preserve STARTED as uncertain; the existing recovery authority owns any retry.
+ failure("finish");
+ } finally {
+ metrics.timer("mateclaw.execution.evidence.capture.latency", "phase", "finish")
+ .record(System.nanoTime() - began, TimeUnit.NANOSECONDS);
+ }
+ }
+
+ private void failure(String phase) {
+ metrics.counter("mateclaw.execution.evidence.capture.failures", "phase", phase).increment();
+ log.warn("Execution evidence capture unavailable (phase={}); consult execution recovery state", phase);
+ }
+}
diff --git a/mateclaw-server/src/main/java/vip/mate/execution/evidence/service/ExecutionEvidenceStore.java b/mateclaw-server/src/main/java/vip/mate/execution/evidence/service/ExecutionEvidenceStore.java
new file mode 100644
index 00000000..9b244991
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/execution/evidence/service/ExecutionEvidenceStore.java
@@ -0,0 +1,341 @@
+package vip.mate.execution.evidence.service;
+
+import com.baomidou.mybatisplus.core.toolkit.IdWorker;
+import org.springframework.dao.DuplicateKeyException;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Service;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.transaction.PlatformTransactionManager;
+import org.springframework.transaction.TransactionDefinition;
+import org.springframework.transaction.support.TransactionTemplate;
+import vip.mate.common.text.SecretRedactor;
+import vip.mate.execution.evidence.ExecutionEvidenceProperties;
+import vip.mate.execution.evidence.model.AttemptState;
+import vip.mate.execution.evidence.model.BeginResult;
+import vip.mate.execution.evidence.model.EffectOutcome;
+import vip.mate.execution.evidence.model.EvidenceKind;
+import vip.mate.execution.evidence.model.EvidenceObservation;
+import vip.mate.execution.evidence.model.EvidenceResult;
+import vip.mate.execution.evidence.model.ExecutionAttempt;
+import vip.mate.execution.evidence.model.ExecutionEvidence;
+import vip.mate.execution.evidence.model.ExecutionIdentity;
+import vip.mate.execution.evidence.model.SourceLevel;
+
+import java.nio.charset.StandardCharsets;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.sql.Timestamp;
+import java.time.Instant;
+import java.time.temporal.ChronoUnit;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Collections;
+import java.util.Objects;
+import java.util.Optional;
+
+/** Short, independent transactions never span tool execution. No public write API exists. */
+@Service
+public class ExecutionEvidenceStore {
+ private final JdbcTemplate jdbc;
+ private final TransactionTemplate transaction;
+ private final ExecutionEvidenceProperties properties;
+ private static final String EVIDENCE_QUERY = "SELECT e.*, a.conversation_id FROM mate_execution_evidence e JOIN mate_execution_attempt a ON a.id=e.attempt_id WHERE e.deleted=0 AND a.deleted=0";
+
+ public ExecutionEvidenceStore(JdbcTemplate jdbc, PlatformTransactionManager manager,
+ ExecutionEvidenceProperties properties) {
+ this.jdbc = jdbc;
+ this.properties = properties;
+ transaction = new TransactionTemplate(manager);
+ transaction.setPropagationBehavior(TransactionDefinition.PROPAGATION_REQUIRES_NEW);
+ }
+
+ private ExecutionIdentityResolver ownershipValidator;
+
+ @Autowired
+ public void setOwnershipValidator(ExecutionIdentityResolver validator) {
+ this.ownershipValidator = validator;
+ }
+
+ public ExecutionAttempt begin(ExecutionIdentity identity) {
+ return reserve(identity).attempt();
+ }
+
+ public BeginResult reserve(ExecutionIdentity identity) {
+ validate(identity);
+ try {
+ return transaction.execute(status -> {
+ if (ownershipValidator != null) ownershipValidator.lockCurrentForUpdate(identity, false);
+ var existing = byInvocation(identity);
+ if (existing.isPresent()) return new BeginResult(sameIdentity(existing.get(), identity), false);
+ long id = IdWorker.getId();
+ Instant now = now();
+ jdbc.update("""
+ INSERT INTO mate_execution_attempt
+ (id,workspace_id,conversation_id,runtime_kind,runtime_session_id,invocation_key,
+ logical_call_id,attempt_no,provider_tool_call_id,tool_name,goal_id,goal_attempt_id,
+ team_run_id,team_task_id,cron_run_id,approval_id,owner_fence,state,effect_outcome,started_at)
+ VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,'STARTED','UNCERTAIN',?)
+ """, id, identity.workspaceId(), identity.conversationId(), identity.runtimeKind(),
+ identity.runtimeSessionId(), identity.invocationKey(), identity.logicalCallId(),
+ identity.attemptNo(), identity.providerToolCallId(), identity.toolName(), identity.goalId(),
+ identity.goalAttemptId(), identity.teamRunId(), identity.teamTaskId(), identity.cronRunId(),
+ identity.approvalId(), identity.ownerFence(), timestamp(now));
+ return new BeginResult(new ExecutionAttempt(id, identity, AttemptState.STARTED, EffectOutcome.UNCERTAIN, now, null), true);
+ });
+ } catch (DuplicateKeyException conflict) {
+ return new BeginResult(sameIdentity(byInvocation(identity).orElseThrow(() ->
+ new IllegalStateException("Logical execution attempt already exists")), identity), false);
+ }
+ }
+
+ public List finish(Long attemptId, String ownerFence, AttemptState state,
+ EffectOutcome effect, List observations) {
+ if (state == null || state == AttemptState.STARTED || effect == null || observations == null)
+ throw new IllegalArgumentException("A terminal execution outcome is required");
+ if (observations.size() > 100) throw new IllegalArgumentException("Too many observations");
+ return transaction.execute(status -> {
+ var snapshot = findAttempt(attemptId).orElseThrow(() -> new IllegalStateException("Execution attempt unavailable"));
+ boolean currentOwner = ownershipValidator == null || ownershipValidator.lockCurrentForUpdate(snapshot.identity(), true);
+ var rows = jdbc.query("SELECT * FROM mate_execution_attempt WHERE id=? AND deleted=0 FOR UPDATE",
+ this::attempt, attemptId);
+ if (rows.isEmpty()) throw new IllegalStateException("Execution attempt unavailable");
+ var attempt = rows.getFirst();
+ if (!Objects.equals(attempt.identity().ownerFence(), ownerFence))
+ throw new IllegalStateException("Execution owner fence rejected");
+ var existing = jdbc.query(EVIDENCE_QUERY + " AND e.attempt_id=? ORDER BY e.id", this::evidence, attemptId);
+ var bySource = new LinkedHashMap();
+ existing.forEach(row -> bySource.put(row.observation().sourceKey(), row));
+ var normalized = new LinkedHashMap();
+ for (var observation : observations) {
+ var prior = bySource.get(observation.sourceKey());
+ var baseline = prior == null ? normalized.get(observation.sourceKey()) : prior.observation();
+ var clean = normalize(observation, baseline);
+ var duplicate = normalized.putIfAbsent(clean.sourceKey(), clean);
+ if (duplicate != null && !duplicate.equals(clean)) throw conflict();
+ if (prior != null && !prior.observation().equals(clean)) throw conflict();
+ }
+ if (attempt.state() != AttemptState.STARTED) {
+ if (attempt.state() != state || attempt.effectOutcome() != effect
+ || bySource.size() != normalized.size() || !bySource.keySet().equals(normalized.keySet()))
+ throw conflict();
+ return existing;
+ }
+ if (!currentOwner) throw new IllegalStateException("Execution owner fence rejected");
+ int updated = jdbc.update("""
+ UPDATE mate_execution_attempt SET state=?,effect_outcome=?,finished_at=?,update_time=?
+ WHERE id=? AND owner_fence=? AND state='STARTED' AND deleted=0
+ """, state.name(), effect.name(), timestamp(now()), timestamp(now()), attemptId, ownerFence);
+ if (updated != 1) throw new IllegalStateException("Execution owner fence rejected");
+ for (var observation : normalized.values()) {
+ long id = IdWorker.getId();
+ jdbc.update("""
+ INSERT INTO mate_execution_evidence
+ (id,workspace_id,attempt_id,source_key,kind,result,source_level,scope_id,generation,
+ input_fingerprint,recipe_id,recipe_revision,check_scope,artifact_ref,artifact_digest,
+ summary,payload_ref,observed_at,expires_at) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+ """, id, attempt.identity().workspaceId(), attemptId, observation.sourceKey(),
+ observation.kind().name(), observation.result().name(), observation.sourceLevel().name(),
+ observation.scopeId(), observation.generation(), observation.inputFingerprint(),
+ observation.recipeId(), observation.recipeRevision(), observation.checkScope(),
+ observation.artifactRef(), observation.artifactDigest(), observation.summary(),
+ observation.payloadRef(), timestamp(observation.observedAt()), timestamp(observation.expiresAt()));
+ }
+ return jdbc.query(EVIDENCE_QUERY + " AND e.attempt_id=? ORDER BY e.id", this::evidence, attemptId);
+ });
+ }
+
+ /** Delete bounded, unreferenced terminal metadata; unresolved executions and bindings remain pinned. */
+ public int purgeExpiredMetadata(Instant now, int batchLimit) {
+ Objects.requireNonNull(now, "Retention time required");
+ if (batchLimit < 1) throw new IllegalArgumentException("Positive cleanup batch required");
+ var cutoff = timestamp(now.minus(properties.getRetentionDays(), ChronoUnit.DAYS));
+ return transaction.execute(status -> {
+ var ids = jdbc.queryForList("""
+ SELECT a.id FROM mate_execution_attempt a
+ WHERE a.state IN ('SUCCEEDED','FAILED','CANCELLED','BLOCKED') AND a.update_time=?)
+ AND NOT EXISTS (SELECT 1 FROM mate_execution_evidence e
+ JOIN mate_goal_criterion_evidence b ON b.evidence_id=e.id WHERE e.attempt_id=a.id)
+ ORDER BY a.id LIMIT ? FOR UPDATE
+ """, Long.class, cutoff, cutoff, Math.min(batchLimit,100));
+ for (var id : ids) {
+ // Foreign keys also prevent deletion if a new binding races the candidate selection.
+ jdbc.update("DELETE FROM mate_execution_evidence WHERE attempt_id=?", id);
+ jdbc.update("DELETE FROM mate_execution_attempt WHERE id=?", id);
+ }
+ return ids.size();
+ });
+ }
+
+ /** Erase copied content while retaining non-content tombstones for existing evidence bindings. */
+ public int purgeConversation(String conversationId) {
+ required(conversationId,128);
+ return transaction.execute(status -> {
+ // Lock attempts before receipts, matching finish, so a late writer cannot restore deleted content.
+ jdbc.update("""
+ UPDATE mate_execution_attempt SET
+ effect_outcome=CASE WHEN state='STARTED' THEN 'UNCERTAIN' ELSE effect_outcome END,
+ finished_at=CASE WHEN state='STARTED' THEN ? ELSE finished_at END,
+ state=CASE WHEN state='STARTED' THEN 'UNKNOWN' ELSE state END,
+ failure_reason=NULL,deleted=1,update_time=?
+ WHERE conversation_id=? AND deleted=0
+ """, timestamp(now()), timestamp(now()), conversationId);
+ return jdbc.update("""
+ UPDATE mate_execution_evidence SET summary=NULL,input_fingerprint=NULL,check_scope=NULL,
+ artifact_ref=NULL,artifact_digest=NULL,payload_ref=NULL,recipe_id=NULL,
+ deleted=1,update_time=? WHERE deleted=0 AND attempt_id IN
+ (SELECT id FROM mate_execution_attempt WHERE conversation_id=?)
+ """, timestamp(now()), conversationId);
+ });
+ }
+
+ public long countUnresolved() {
+ Long count = jdbc.queryForObject("SELECT COUNT(*) FROM mate_execution_attempt WHERE deleted=0 AND state IN ('STARTED','UNKNOWN')", Long.class);
+ return count == null ? 0 : count;
+ }
+
+ public Optional findAttempt(Long id) {
+ return jdbc.query("SELECT * FROM mate_execution_attempt WHERE id=? AND deleted=0", this::attempt, id).stream().findFirst();
+ }
+
+ /** Load one page of attempts without allowing cross-conversation reads. */
+ public Map findAttempts(Long workspaceId, String conversationId, List ids) {
+ scope(workspaceId, conversationId);
+ Objects.requireNonNull(ids, "Attempt IDs required");
+ if (ids.size() > properties.getMaxListLimit())
+ throw new IllegalArgumentException("Attempt batch exceeds page limit");
+ if (ids.isEmpty()) return Map.of();
+ if (ids.stream().anyMatch(Objects::isNull))
+ throw new IllegalArgumentException("Attempt ID required");
+ var distinct = ids.stream().distinct().toList();
+ var args = new ArrayList