- * 提供 approve / deny 端点，供前端在收到 tool_approval_requested SSE 事件后调用。
- * 批准后自动触发工具重放，结果通过 SSE 流推送给前端。
+ * Web approve / deny actions ride the SSE {@code POST /chat/stream} path with
+ * {@code /approve} or {@code /deny} text commands ({@link vip.mate.channel.web.ChatController}
+ * intercepts), so a write-style {@code POST /approve} REST endpoint was deleted
+ * in RFC-067 PR 6 — it bypassed the unified workflow lifecycle and let any
+ * future caller silently regress to the pre-RFC ghost-approval state.
+ *
+ * Only {@link #getPendingApprovals} remains, used by the frontend for hydration
+ * after page refresh.
*
* @author MateClaw Team
*/
@@ -31,71 +35,11 @@ public class ApprovalController {
private final ApprovalWorkflowService approvalService;
private final ConversationService conversationService;
- private final ChatStreamTracker streamTracker;
/**
- * 批准或拒绝工具执行
- *
- * 用于页面刷新后恢复审批卡片（hydration）。
+ * Hydration query for page refresh: returns every pending approval still
+ * waiting in the conversation. The frontend uses this to rebuild the
+ * approval banner after a reload.
*/
@Operation(summary = "查询待审批记录")
@GetMapping("/{conversationId}/pending-approvals")
@@ -115,11 +59,4 @@ public class ApprovalController {
List> pending = approvalService.getPendingByConversation(conversationId);
return R.ok(pending);
}
-
- @Data
- public static class ApprovalRequest {
- private String pendingId;
- /** "approved" 或 "denied" */
- private String decision;
- }
}
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 30e92af0..53cca423 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
@@ -295,27 +295,38 @@ public class ChatController {
})
.doOnComplete(() -> {
if (!finalized.compareAndSet(false, true)) return;
+ // RFC-067 §4.6: replay can re-trigger an approval (the approved tool
+ // call may chain into another guarded tool). Derive status the same
+ // way as the normal stream so awaiting_approval doesn't get masked
+ // as completed.
+ boolean replayWasStopped = streamTracker.isStopRequested(conversationId);
+ ChatStreamTracker.InterruptType replayInterrupt = streamTracker.getInterruptType(conversationId);
+ boolean replayIsError = accumulator.getContent() != null
+ && accumulator.getContent().startsWith("[错误] ");
+ String persistStatus = derivePersistStatus(
+ accumulator.isAwaitingApproval(), replayIsError,
+ replayWasStopped, replayInterrupt);
try {
MessageEntity savedAssistant = null;
List parts = accumulator.toAssistantParts();
String text = accumulator.getContent();
if (!text.isBlank() || !parts.isEmpty()) {
savedAssistant = conversationService.saveMessage(conversationId, "assistant", text, parts,
- "completed",
+ persistStatus,
accumulator.getPromptTokens(),
accumulator.getCompletionTokens(),
accumulator.getRuntimeModelName(),
accumulator.getRuntimeProviderId(),
- accumulator.toMetadataJson()); // 包含 toolCalls 元数据
+ accumulator.toMetadataJson()); // includes toolCalls metadata
}
broadcastEvent(conversationId, "message_complete", Map.of(
- "status", "completed",
+ "status", persistStatus,
"hasThinking", !accumulator.getThinking().isBlank(),
"hasContent", !text.isBlank()
));
int msgCount = conversationService.getMessageCount(conversationId);
broadcastEvent(conversationId, "done", buildDonePayload(
- conversationId, "completed", savedAssistant, 0, 0, true, msgCount));
+ conversationId, persistStatus, savedAssistant, 0, 0, true, msgCount));
} catch (Exception e) {
log.warn("SSE replay complete error: {}", e.getMessage());
} finally {
@@ -477,16 +488,8 @@ public class ChatController {
boolean isInterruptFollowup = interruptType == ChatStreamTracker.InterruptType.USER_INTERRUPT_WITH_FOLLOWUP;
boolean isError = accumulator.getContent() != null
&& accumulator.getContent().startsWith("[错误] ");
- String persistStatus;
- if (accumulator.isAwaitingApproval()) {
- persistStatus = "awaiting_approval";
- } else if (isError) {
- persistStatus = "error";
- } else if (!wasStopped) {
- persistStatus = "completed";
- } else {
- persistStatus = isInterruptFollowup ? "interrupted" : "stopped";
- }
+ String persistStatus = derivePersistStatus(
+ accumulator.isAwaitingApproval(), isError, wasStopped, interruptType);
try {
MessageEntity savedAssistant = null;
List assistantParts = accumulator.toAssistantParts();
@@ -1069,13 +1072,24 @@ public class ChatController {
})
.doOnComplete(() -> {
if (!finalized.compareAndSet(false, true)) return;
+ // RFC-067 §4.6: queued stream can hit a tool_approval_requested event
+ // mid-flight. Derive status via the shared helper so awaiting_approval
+ // is not silently downgraded to completed (which would prematurely fire
+ // expirePendingApprovals on the frontend and ghost-clear the banner).
+ boolean queuedWasStopped = streamTracker.isStopRequested(conversationId);
+ ChatStreamTracker.InterruptType queuedInterrupt = streamTracker.getInterruptType(conversationId);
+ boolean queuedIsError = accumulator.getContent() != null
+ && accumulator.getContent().startsWith("[错误] ");
+ String persistStatus = derivePersistStatus(
+ accumulator.isAwaitingApproval(), queuedIsError,
+ queuedWasStopped, queuedInterrupt);
try {
MessageEntity savedAssistant = null;
List parts = accumulator.toAssistantParts();
String text = accumulator.getContent();
if (!text.isBlank() || !parts.isEmpty()) {
savedAssistant = conversationService.saveMessage(conversationId, "assistant", text, parts,
- "completed",
+ persistStatus,
accumulator.getPromptTokens(),
accumulator.getCompletionTokens(),
accumulator.getRuntimeModelName(),
@@ -1083,12 +1097,12 @@ public class ChatController {
accumulator.toMetadataJson());
}
broadcastEvent(conversationId, "message_complete", Map.of(
- "status", "completed",
+ "status", persistStatus,
"hasThinking", !accumulator.getThinking().isBlank(),
"hasContent", !text.isBlank()
));
broadcastEvent(conversationId, "done", buildDonePayload(
- conversationId, "completed", savedAssistant,
+ conversationId, persistStatus, savedAssistant,
accumulator.getPromptTokens(), accumulator.getCompletionTokens(), true,
conversationService.getMessageCount(conversationId)));
} catch (Exception e) {
@@ -1173,6 +1187,35 @@ public class ChatController {
streamTracker.broadcast(conversationId, name, payload);
}
+ /**
+ * Derive the persistence status for an assistant message at stream finalization
+ * (RFC-067 §4.6). Five-way state machine:
+ *
+ *
{@code awaiting_approval} — accumulator hit a tool_approval_requested
+ * event; the turn is paused, not finished. queued / replay paths must not
+ * collapse this to {@code completed}.
+ *
{@code error} — content carries the typed-error prefix from the LLM
+ * client. BaseAgent history sanitization skips these on the next prompt
+ * so error text doesn't poison the conversation.
+ *
{@code completed} — clean finish, default case.
+ *
{@code interrupted} — user halted the running turn AND queued a
+ * follow-up message (interrupt-with-followup).
+ *
{@code stopped} — user pressed Stop without follow-up.
+ *
+ * Package-private so {@link vip.mate.channel.web.ChatControllerPersistStatusTest}
+ * can exercise the truth table directly without spinning up the controller.
+ */
+ static String derivePersistStatus(boolean isAwaitingApproval,
+ boolean isError,
+ boolean wasStopped,
+ ChatStreamTracker.InterruptType interruptType) {
+ if (isAwaitingApproval) return "awaiting_approval";
+ if (isError) return "error";
+ if (!wasStopped) return "completed";
+ return interruptType == ChatStreamTracker.InterruptType.USER_INTERRUPT_WITH_FOLLOWUP
+ ? "interrupted" : "stopped";
+ }
+
private Map buildDonePayload(String conversationId, String status, MessageEntity savedAssistant,
int promptTokens, int completionTokens,
boolean persisted, Integer messageCount) {
@@ -1204,10 +1247,20 @@ public class ChatController {
* Invoked from {@link ChatStreamTracker#onShutdown()} so any in-flight turn doesn't
* lose its already-streamed content + tool calls when the process exits.
*
+ * Status routing (RFC-067 §4.6):
+ *
+ *
If the accumulator was awaiting approval at shutdown, the message keeps
+ * {@code awaiting_approval}. After restart, {@code recoverFromDb} re-registers
+ * the pending in memory and the existing approval banner remains coherent
+ * with both DB and metadata. Falling back to {@code interrupted_shutdown}
+ * here would orphan the message metadata (UI would render "interrupted"
+ * while the approval is still recoverable).
+ *
Otherwise {@code interrupted_shutdown} as before.
+ *
* Idempotent w.r.t. the normal doOnComplete/doOnError save: if those paths already
- * persisted the message, this writes a second row with status="interrupted_shutdown",
- * which is rare in practice (race window is sub-second between dispose and save) and
- * acceptable. Skipping save when nothing to save avoids empty rows.
+ * persisted the message, this writes a second row, which is rare in practice
+ * (race window is sub-second between dispose and save) and acceptable. Skipping
+ * save when nothing to save avoids empty rows.
*/
private void emergencySaveAccumulator(String conversationId, StreamAccumulator accumulator) {
try {
@@ -1216,17 +1269,21 @@ public class ChatController {
if (text.isBlank() && parts.isEmpty()) {
return;
}
- String savedText = text.isBlank() ? "[已中断 — 服务重启]" : text;
+ boolean awaitingApproval = accumulator.isAwaitingApproval();
+ String status = awaitingApproval ? "awaiting_approval" : "interrupted_shutdown";
+ String savedText = text.isBlank()
+ ? (awaitingApproval ? "[等待审批 — 服务重启]" : "[已中断 — 服务重启]")
+ : text;
conversationService.saveMessage(conversationId, "assistant", savedText, parts,
- "interrupted_shutdown",
+ status,
accumulator.getPromptTokens(),
accumulator.getCompletionTokens(),
accumulator.getRuntimeModelName(),
accumulator.getRuntimeProviderId(),
accumulator.toMetadataJson());
log.info("[ChatController] Emergency-saved in-flight assistant message: " +
- "conversationId={}, textLen={}, partsCount={}",
- conversationId, text.length(), parts.size());
+ "conversationId={}, status={}, textLen={}, partsCount={}",
+ conversationId, status, text.length(), parts.size());
} catch (Exception e) {
log.error("[ChatController] Emergency save failed for {}: {}",
conversationId, e.getMessage(), e);
diff --git a/mateclaw-server/src/main/java/vip/mate/workspace/conversation/ConversationService.java b/mateclaw-server/src/main/java/vip/mate/workspace/conversation/ConversationService.java
index fb5a3dc3..5eb4a5eb 100644
--- a/mateclaw-server/src/main/java/vip/mate/workspace/conversation/ConversationService.java
+++ b/mateclaw-server/src/main/java/vip/mate/workspace/conversation/ConversationService.java
@@ -561,7 +561,19 @@ public class ConversationService {
if (raw == null || raw.isBlank() || !raw.contains("pendingApproval")) continue;
try {
- java.util.Map meta = objectMapper.readValue(raw, new TypeReference<>() {});
+ // H2's JSON column returns the metadata as a JSON-encoded string
+ // (wrapped + escaped) when read through MyBatis. MessageVO.parseMetadataToObject
+ // (the read-to-frontend path) already handles this; we mirror the same
+ // unwrap here. Without it, readValue tokenizes the leading `"` as a
+ // String token and explodes with "Cannot construct LinkedHashMap from
+ // String value", silently turning every approve / deny / Stop sweep
+ // into a no-op (messagesRewritten=0).
+ String json = raw.trim();
+ if (json.startsWith("\"") && json.endsWith("\"")) {
+ json = objectMapper.readValue(json, String.class);
+ }
+ java.util.Map meta = objectMapper.readValue(json,
+ new TypeReference>() {});
Object pa = meta.get("pendingApproval");
if (!(pa instanceof java.util.Map)) continue;
@SuppressWarnings("unchecked")
@@ -579,6 +591,23 @@ public class ConversationService {
meta.put("currentPhase", "resolved");
}
+ // RFC-067 §4.10 (PR 9): flip the matching toolCall + segment entries
+ // inside this message's metadata. Both DENIED and APPROVED need this
+ // because the LLM streamed tool_call_started → segment.status='running'
+ // before the user's decision arrived, and replay creates a NEW assistant
+ // message rather than updating the original — so without this fix the
+ // gate message's tool card stays as an orange spinner forever.
+ // DENIED → success=false + result='[已拒绝]' → red ✗
+ // APPROVED → success=true + result='[已批准]' → green ✓ on the gate
+ // row; the actual execution result still appears in the
+ // replayed assistant message that follows.
+ Object toolName = pendingApproval.get("toolName");
+ Object toolArgs = pendingApproval.get("arguments");
+ String tnStr = toolName == null ? null : String.valueOf(toolName);
+ String taStr = toolArgs == null ? null : String.valueOf(toolArgs);
+ flipResolvedToolCalls(meta, tnStr, taStr, decision);
+ flipResolvedSegments(meta, tnStr, taStr, decision);
+
msg.setMetadata(objectMapper.writeValueAsString(meta));
if ("awaiting_approval".equals(msg.getStatus())) {
msg.setStatus(decision.messageStatus);
@@ -586,8 +615,10 @@ public class ConversationService {
messageMapper.updateById(msg);
rewritten++;
} catch (Exception e) {
- log.warn("[ConversationService] Failed to rewrite pendingApproval status for message {}: {}",
- msg.getId(), e.getMessage());
+ String preview = raw.length() > 200 ? raw.substring(0, 200) + "..." : raw;
+ log.warn("[ConversationService] Failed to rewrite pendingApproval status for message {} " +
+ "(rawLen={}, preview={}): {}",
+ msg.getId(), raw.length(), preview, e.getMessage());
}
}
if (rewritten > 0) {
@@ -598,6 +629,91 @@ public class ConversationService {
return rewritten;
}
+ /**
+ * Flip the gate message's tool-call entry to a terminal state matching the
+ * approval decision (RFC-067 §4.10).
+ *
+ * Driven by {@link MetadataDecision}:
+ *
+ *
{@link MetadataDecision#APPROVED} → {@code status='completed'} +
+ * {@code success=true} + {@code result='[已批准]'}. The actual tool
+ * execution result appears in the replayed assistant message that
+ * follows — not on this gate row.
+ *
{@link MetadataDecision#DENIED} → {@code status='completed'} +
+ * {@code success=false} + {@code result='[已拒绝]'}. MessageBubble
+ * renders this as a red ✗.
+ *
+ * Both paths flip status off {@code awaiting_approval} / {@code running} so
+ * MessageBubble's icon precedence (running > awaiting_approval > success
+ * branches) can reach the right terminal icon. Without the flip the card
+ * stays as an orange spinner forever — replay creates a new message
+ * instead of overwriting the gate row, so nothing else updates it.
+ * Best-effort: if metadata.toolCalls is missing or no entry matches, this
+ * is a silent no-op.
+ */
+ @SuppressWarnings("unchecked")
+ private void flipResolvedToolCalls(java.util.Map meta,
+ String toolName, String toolArgs,
+ MetadataDecision decision) {
+ Object tc = meta.get("toolCalls");
+ if (!(tc instanceof java.util.List)) return;
+ boolean approved = decision == MetadataDecision.APPROVED;
+ String resultText = approved ? "[已批准]" : "[已拒绝]";
+ for (Object entry : (java.util.List