args) {
if (ctx == null || call == null || def == null) return null;
try {
ToolExecutionRecordDao dao = executionRecordDao();
if (dao == null) return null;
ToolExecutionRecord r = new ToolExecutionRecord();
r.setExecutionId(IdGenerator.prefixed("tex_"));
r.setRunId(ctx.getRunId());
r.setThreadId(ctx.getThreadId());
r.setToolCallId(ctx.getToolCallId());
r.setToolName(call.getName());
r.setSideEffect(def.getSideEffect() == null ? null : def.getSideEffect().name());
r.setStatus("started");
r.setArgumentsJson(recordedArgumentsJson(executor, args));
r.setStartedAt(new Date());
dao.save(r);
return r.getExecutionId();
} catch (Throwable t) {
try { Tools.log("[ToolExecutionRecord] start failed", t); } catch (Throwable ignore) { /* ignore */ }
return null;
}
}
private void finishToolExecution(String executionId, String status, String resultJson,
String errorMessage, long durationMs) {
if (executionId == null || executionId.isEmpty()) return;
try {
ToolExecutionRecordDao dao = executionRecordDao();
if (dao == null) return;
dao.finish(status, resultJson, truncate(errorMessage, 2000),
durationMs < 0 ? null : Long.valueOf(durationMs), new Date(), executionId);
} catch (Throwable t) {
try { Tools.log("[ToolExecutionRecord] finish failed: " + executionId, t); }
catch (Throwable ignore) { /* ignore */ }
}
}
private ToolExecutionRecordDao executionRecordDao() {
try {
ToolExecutionRecordDao d = Tools.getBean(ToolExecutionRecordDao.class);
if (d != null) return d;
} catch (Throwable ignore) { /* fallback */ }
return executionRecordDao;
}
private static String truncate(String s, int max) {
if (s == null || max <= 0 || s.length() <= max) return s;
return s.substring(0, max);
}
/**
* 工具执行线程池 / Per-tool executor.
*
* 仅在 {@code defaultTimeoutMs > 0} 的工具走 Future.get(timeout) 路径时用。
* 零超时工具仍在调用线程同步跑，避免不必要的线程切换。
*/
private final ExecutorService toolPool = Executors.newCachedThreadPool(r -> {
Thread t = new Thread(r, "lobster-tool-exec");
t.setDaemon(true);
return t;
});
public ToolResult dispatch(ToolContext ctx, ToolCall call) {
long start = System.currentTimeMillis();
// —— 调度前取消检查 —— //
if (ctx != null && ctx.isCancelled()) {
auditLogger.record(ctx, call.getName(), Collections.emptyMap(),
"cancelled", 0);
return ToolResult.error("tool cancelled before dispatch");
}
BuiltinToolDefinition def = toolRegistry.find(call.getName());
if (def == null) {
ToolResult err = ToolResult.error("tool not found: " + call.getName());
auditLogger.record(ctx, call.getName(), Collections.emptyMap(),
"error.not_found", (int) (System.currentTimeMillis() - start));
return err;
}
Map args;
try {
args = JsonUtil.fromJsonToMap(call.getArgumentsJson());
} catch (Throwable t) {
ToolResult err = ToolResult.error("invalid arguments JSON: " + t.getMessage());
auditLogger.record(ctx, call.getName(), Collections.emptyMap(),
"error.bad_args", (int) (System.currentTimeMillis() - start));
return err;
}
// —— args 解析完立即取 executor —— //
// 脱敏钩子必须在所有 audit 路径（denied / rate_limit / ok / error / cancelled / exception）
// 生效。之前 denied/rate_limit 直接 record(args) 会把 code_exec.code 原文落审计，违反红线.
ToolExecutor executor = toolRegistry.executor(call.getName());
ToolResult permissionDenied = checkMcpReplayPermission(ctx, call, def, executor, args, start);
if (permissionDenied != null) return permissionDenied;
ToolResult recorded = replayRecordedToolResult(ctx, call, def, executor, args);
if (recorded != null) {
String replayAudit = recorded.getStatus() == ToolResultStatus.error
? "error.replay_blocked" : "replayed";
auditLogger.record(ctx, call.getName(), Collections.emptyMap(),
replayAudit, (int) (System.currentTimeMillis() - start));
return recorded;
}
String executionId = startToolExecution(ctx, call, def, executor, args);
if (executionId == null && !isReadOnly(def)) {
ToolResult err = ToolResult.error("tool execution record unavailable; side-effectful tool was not executed");
auditLogger.record(ctx, call.getName(), Collections.emptyMap(),
"error.record_unavailable", (int) (System.currentTimeMillis() - start));
return err;
}
try {
permissionChecker.check(def, ctx.getUserContext());
} catch (LobsterException e) {
Map auditArgs = redactOrDefault(executor, args, null);
auditLogger.record(ctx, call.getName(), auditArgs, "denied", (int) (System.currentTimeMillis() - start));
finishToolExecution(executionId, "denied", null, e.getMessage(), System.currentTimeMillis() - start);
return ToolResult.error(e.getMessage());
}
try {
Integer override = def.getRateLimitPerMinute();
int perMinute = (override != null && override > 0) ? override : rateLimitFor(def.getRiskLevel());
rateLimiter.acquire(ctx.getUserId(), def.getToolName(), perMinute);
} catch (LobsterException e) {
Map auditArgs = redactOrDefault(executor, args, null);
auditLogger.record(ctx, call.getName(), auditArgs, "rate_limit", (int) (System.currentTimeMillis() - start));
finishToolExecution(executionId, "rate_limit", null, e.getMessage(), System.currentTimeMillis() - start);
return ToolResult.error(e.getMessage());
}
// —— 实际执行：按定义是否声明 timeout 走两条路径 —— //
final ToolContext finalCtx = ctx;
final Map finalArgs = args;
Callable task = () -> executor.execute(finalCtx, finalArgs);
long effectiveTimeoutMs = effectiveTimeoutMs(def, ctx);
try {
ToolResult result;
if (effectiveTimeoutMs > 0) {
result = runWithTimeout(task, effectiveTimeoutMs, call.getName());
} else {
result = task.call();
}
if (result == null) result = ToolResult.error("tool returned null");
String auditResult = result.getStatus() == ToolResultStatus.ok ? "ok"
: (result.getStatus() == ToolResultStatus.pending ? "pending" : "error");
Map auditArgs = redactOrDefault(executor, args, result);
auditLogger.record(ctx, call.getName(), auditArgs, auditResult, (int) (System.currentTimeMillis() - start));
finishToolExecution(executionId, auditResult, result.toToolMessageContent(), null,
System.currentTimeMillis() - start);
return result;
} catch (ToolCancelledException tc) {
Map auditArgs = redactOrDefault(executor, args, null);
auditLogger.record(ctx, call.getName(), auditArgs, "cancelled",
(int) (System.currentTimeMillis() - start));
finishToolExecution(executionId, "cancelled", null, tc.getMessage(), System.currentTimeMillis() - start);
return ToolResult.error(tc.getMessage() == null ? "tool cancelled" : tc.getMessage());
} catch (Throwable t) {
try {
Tools.log("[ToolExecutor] " + call.getName() + " failed", t);
} catch (Throwable ignore) { /* ignore */ }
Map auditArgs = redactOrDefault(executor, args, null);
auditLogger.record(ctx, call.getName(), auditArgs, "exception",
(int) (System.currentTimeMillis() - start));
finishToolExecution(executionId, "exception", null,
t.getMessage() == null ? t.getClass().getSimpleName() : t.getMessage(),
System.currentTimeMillis() - start);
return ToolResult.error("tool " + call.getName() + " failed: " + (t.getMessage() == null ? t.getClass().getSimpleName() : t.getMessage()));
}
}
/**
* 调 executor.redactAuditDetail.
* Fail-closed：如果 redact 实现抛异常或调不到 executor，不再回落到原始 args
* —— 某些工具 args 本身就含敏感正文（code_exec 的 code 是典型例子），一次实现 bug
* 不能让原文落审计. 退路：抹掉已知敏感字段、只留安全元信息.
*
* @return 永不返 null；要么是 executor 给的脱敏 map，要么是强制剥敏的 fallback.
*/
private Map redactOrDefault(ToolExecutor executor, Map args, ToolResult result) {
if (executor != null) {
try {
Map d = executor.redactAuditDetail(args, result);
if (d != null) return d;
} catch (Throwable t) {
try { Tools.log("[ToolExecutor] redactAuditDetail failed — falling back to hard-redact", t); }
catch (Throwable ignore) { /* ignore */ }
return hardRedact(args);
}
}
// executor.redactAuditDetail 返 null → 默认策略仍把敏感字段抹掉
return hardRedact(args);
}
private ToolResult checkMcpReplayPermission(ToolContext ctx, ToolCall call,
BuiltinToolDefinition def,
ToolExecutor executor,
Map args,
long start) {
if (def == null || def.getCategory() != ToolCategory.MCP) return null;
try {
permissionChecker.check(def, ctx == null ? null : ctx.getUserContext());
return null;
} catch (LobsterException e) {
Map auditArgs = redactOrDefault(executor, args, null);
auditLogger.record(ctx, call.getName(), auditArgs, "denied",
(int) (System.currentTimeMillis() - start));
return ToolResult.error(e.getMessage());
}
}
private ToolResult replayRecordedToolResult(ToolContext ctx, ToolCall call,
BuiltinToolDefinition def,
ToolExecutor executor,
Map args) {
if (ctx == null || call == null || ctx.getRunId() == null || ctx.getToolCallId() == null) return null;
try {
ToolExecutionRecordDao dao = executionRecordDao();
if (dao == null) return null;
List records = dao.listByRunAndCall(ctx.getRunId(), ctx.getToolCallId());
if (records == null || records.isEmpty()) return null;
ToolExecutionRecord latest = records.get(0);
if (latest == null || latest.getStatus() == null) return null;
if (!matchesRecordedToolCall(latest, call, executor, args)) {
if ("READ".equals(latest.getSideEffect())) return null;
return ToolResult.error("tool execution identity mismatch after backend recovery; not re-executed to avoid duplicate side effects");
}
String status = latest.getStatus();
if ("started".equals(status)) {
if ("READ".equals(latest.getSideEffect())) return null;
return ToolResult.error("tool execution state is unknown after backend recovery; not re-executed to avoid duplicate side effects");
}
return resultFromRecord(latest);
} catch (Throwable t) {
try { Tools.log("[ToolExecutionRecord] replay lookup failed", t); } catch (Throwable ignore) { /* ignore */ }
if (!isReadOnly(def)) {
return ToolResult.error("tool execution record lookup failed; side-effectful tool was not executed to avoid duplicate side effects");
}
return null;
}
}
private boolean matchesRecordedToolCall(ToolExecutionRecord record, ToolCall call,
ToolExecutor executor, Map args) {
if (record == null || call == null) return false;
if (!Objects.equals(record.getToolName(), call.getName())) return false;
RecordedArguments recorded = parseRecordedArguments(record.getArgumentsJson());
if (recorded.fingerprint != null) {
return Objects.equals(recorded.fingerprint, fingerprintArguments(args));
}
if (containsSensitiveKey(args)) return false;
if (!recorded.legacyComparable) return false;
return Objects.equals(canonicalJson(recorded.redactedArgs),
canonicalJson(redactOrDefault(executor, args, null)));
}
private String recordedArgumentsJson(ToolExecutor executor, Map args) {
Map record = new LinkedHashMap<>();
record.put("_recordVersion", Integer.valueOf(2));
record.put("argumentsFingerprint", fingerprintArguments(args));
record.put("redactedArgs", redactOrDefault(executor, args, null));
return JsonUtil.toJson(record);
}
private String fingerprintArguments(Map args) {
String canonical = canonicalJson(args == null ? Collections.emptyMap() : args);
try {
MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] bytes = digest.digest(canonical.getBytes(StandardCharsets.UTF_8));
StringBuilder sb = new StringBuilder(bytes.length * 2);
for (byte b : bytes) sb.append(String.format("%02x", b & 0xff));
return sb.toString();
} catch (Throwable t) {
throw new LobsterException("tool.args_fingerprint_failed",
"Failed to fingerprint tool arguments", t);
}
}
private String canonicalJson(Object value) {
return JsonUtil.toJson(normalizeForFingerprint(value));
}
@SuppressWarnings("unchecked")
private RecordedArguments parseRecordedArguments(String rawJson) {
if (rawJson == null || rawJson.isEmpty()) {
return new RecordedArguments(null, Collections.emptyMap(), true);
}
try {
Map parsed = JsonUtil.fromJsonToMap(rawJson);
if (parsed == null) {
return new RecordedArguments(null, Collections.emptyMap(), true);
}
Object fp = parsed.get("argumentsFingerprint");
Object redacted = parsed.get("redactedArgs");
if (fp != null && redacted instanceof Map) {
return new RecordedArguments(String.valueOf(fp),
(Map) redacted, false);
}
boolean comparable = !containsRedactedMarker(parsed);
return new RecordedArguments(null, parsed, comparable);
} catch (Throwable ignore) {
return new RecordedArguments(null, Collections.emptyMap(), false);
}
}
private boolean containsRedactedMarker(Object value) {
if (value instanceof Map) {
for (Object v : ((Map) value).values()) {
if (containsRedactedMarker(v)) return true;
}
return false;
}
if (value instanceof Iterable) {
for (Object item : (Iterable) value) {
if (containsRedactedMarker(item)) return true;
}
return false;
}
return value instanceof String && ((String) value).startsWith(" e : ((Map) value).entrySet()) {
Object key = e.getKey();
if (key != null && SENSITIVE_KEYS.contains(String.valueOf(key).toLowerCase())) {
return true;
}
if (containsSensitiveKey(e.getValue())) return true;
}
return false;
}
if (value instanceof Iterable) {
for (Object item : (Iterable) value) {
if (containsSensitiveKey(item)) return true;
}
}
return false;
}
private static final class RecordedArguments {
final String fingerprint;
final Map redactedArgs;
final boolean legacyComparable;
RecordedArguments(String fingerprint, Map redactedArgs,
boolean legacyComparable) {
this.fingerprint = fingerprint;
this.redactedArgs = redactedArgs == null
? Collections.emptyMap() : redactedArgs;
this.legacyComparable = legacyComparable;
}
}
@SuppressWarnings("unchecked")
private Object normalizeForFingerprint(Object value) {
if (value instanceof Map) {
TreeMap sorted = new TreeMap<>();
for (Map.Entry e : ((Map) value).entrySet()) {
if (e.getKey() != null) {
sorted.put(String.valueOf(e.getKey()), normalizeForFingerprint(e.getValue()));
}
}
return sorted;
}
if (value instanceof Iterable) {
List