feat(loop): Top5#4 工具循环增强（对齐 OpenClaw agent-loop）——重复检测/并行串行/钩子/errorKind/repair
- 重复调用安全网（critical-tool-loop）：指纹=name+canonical JSON(args)；批内重复第二次跳过回喂
「duplicate call」；跨轮关键重复(同指纹重现)→首次 block+criticalSeen，再次连续重复→终止整轮
StopReasonToolLoopTerminated（替代裸 8 轮针对同调用的硬截止）。
- 并行/串行混合：invokeParallel 默认并行，信号量(ToolParallelism 默认4)限并发，结果按调用索引
写回按原序渲染；串行触发=Options.ToolExecution:sequential 或 SetToolExecutionMode(name,sequential)
（对齐 OpenClaw「一个 sequential 标记→整组串行」）；goroutine 不泄漏、ctx 取消快速返回。
- 工具钩子：ToolLoopHooks(BatchAdmit/CallAdmit/AfterCall/AfterOutcome) 经 Options.Hooks 注入，
均 nil-tolerant；供后续敏感操作代审复用（design/11）。terminate 用 every 语义。
- status 分类：ToolError.Kind() 区分 argument-validation(JSON-Schema 失败)/execution；
失败消息渲染 {kind,message} 让模型区分重发参数 vs 执行失败。
- tool-call-repair：LenientJSONUnmarshal 修 fence 包裹/尾逗号畸形；agent.extractToolCalls 与
loop.decodeToolCalls 走它；不可修复退化为文本不崩整轮。意图调用未区分回喂提示(后置)。
- tool_execution_update：流式路径 emitToolExecution 发 StreamKindToolExecution(start/end/end:error)。
go build/vet/test 全绿(46包)。TestRun_MaxRounds 改每轮不同参(原同 echo 被安全网拦，预期新行为)。
-race 受宿主 TSan VMA 限制无法运行(与代码无关)。
This commit is contained in:
Aska committed
1 parent
2248ddce15
commit
35cb2d3942
11 files changed
+1079
-74
No files matched your search
+395
-36
@@ -3,7 +3,9 @@ package loop
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"sync"
|
||||
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/agent"
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
|
||||
@@ -11,38 +13,378 @@ import (
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/trace"
|
||||
)
|
||||
|
||||
// runToolCalls executes each requested tool call, appending a RoleTool result
|
||||
// message (success or failure) so the model can continue. It returns the updated
|
||||
// message slice and the number of tool calls invoked. Invocation is delegated to
|
||||
// the dispatched tool, which applies the per-tool deadline; a missing dispatcher
|
||||
// is fed back as an error so the loop never panics or crashes on an unhandled
|
||||
// call.
|
||||
func (l *Loop) runToolCalls(ctx context.Context, messages []model.Message, calls []agent.ToolCall) ([]model.Message, int, error) {
|
||||
// ToolExecutionMode tokens accepted by Options.ToolExecution. Empty selects
|
||||
// toolExecParallel.
|
||||
const (
|
||||
toolExecParallel = "parallel"
|
||||
toolExecSequential = "sequential"
|
||||
)
|
||||
|
||||
// criticalToolLoopTerminalReason is surfaced as Result.Text and on every blocked
|
||||
// call when the critical-tool-loop safety net stops the run.
|
||||
const criticalToolLoopTerminalReason = "critical tool-loop detected: an identical tool call was repeated across rounds; the run is stopping"
|
||||
|
||||
// ToolCallVeto is returned by a CallAdmit hook to block a single call.
|
||||
type ToolCallVeto struct {
|
||||
Block bool
|
||||
Reason string
|
||||
}
|
||||
|
||||
// ToolOutcome is the normalized result of executing one tool call. It is what an
|
||||
// after-call / after-outcome hook observes and may rewrite before the loop
|
||||
// renders it back to the model.
|
||||
type ToolOutcome struct {
|
||||
// Result is the value the tool returned (nil on failure or skip).
|
||||
Result any
|
||||
// Err is non-nil when the call failed to execute; it is nil on success.
|
||||
Err error
|
||||
// ErrKind classifies a failure as tool.KindArgumentValidation or
|
||||
// tool.KindExecution (the task's errorKind status classification). Empty on
|
||||
// success.
|
||||
ErrKind string
|
||||
// Skipped is true when the call never executed (duplicate / blocked / vetoed).
|
||||
Skipped bool
|
||||
// Reason is a human-readable explanation for a skipped call.
|
||||
Reason string
|
||||
// Terminate, when set by a hook, signals that the whole round should stop
|
||||
// once every call in the batch is also marked terminate.
|
||||
Terminate bool
|
||||
}
|
||||
|
||||
// ToolLoopHooks groups the optional per-batch / per-call tool-loop hooks. Every
|
||||
// field is nil-tolerant. These are the extension points the loop keeps open for
|
||||
// "敏感操作代审" (design/11 batch admission) and the future async-tool path, so
|
||||
// the audit layer and the loop are decoupled.
|
||||
type ToolLoopHooks struct {
|
||||
// BatchAdmit is called once per batch before any call executes. Returning
|
||||
// (false, reason) blocks the whole batch: every call becomes a skipped result
|
||||
// carrying reason. nil = always admit.
|
||||
BatchAdmit func(ctx context.Context, calls []agent.ToolCall) (bool, string)
|
||||
// CallAdmit is called per call before it executes. A non-nil veto with
|
||||
// Block=true blocks that single call. nil = always admit.
|
||||
CallAdmit func(ctx context.Context, call agent.ToolCall) *ToolCallVeto
|
||||
// AfterCall rewrites a call's outcome after the tool executes. A nil return
|
||||
// keeps the original. It runs before AfterOutcome.
|
||||
AfterCall func(ctx context.Context, call agent.ToolCall, outcome ToolOutcome) *ToolOutcome
|
||||
// AfterOutcome observes/rewrites the finalized outcome (after AfterCall and
|
||||
// after any skip/block decision) immediately before the result is rendered
|
||||
// back to the model. nil = keep the outcome.
|
||||
AfterOutcome func(ctx context.Context, call agent.ToolCall, outcome ToolOutcome) *ToolOutcome
|
||||
}
|
||||
|
||||
// toolRunResult is the outcome of running one tool batch.
|
||||
type toolRunResult struct {
|
||||
messages []model.Message
|
||||
executed int
|
||||
terminate bool
|
||||
}
|
||||
|
||||
// toolLoopState carries the per-run state of the critical-tool-loop safety net.
|
||||
// It is scoped to a single Run call, so concurrent runs never share it.
|
||||
type toolLoopState struct {
|
||||
criticalSeen bool // a critical loop was already reported this run
|
||||
prevFP map[string]bool // fingerprints seen in the immediately previous batch
|
||||
}
|
||||
|
||||
// toolCallAction is the execution decision for one call after classification.
|
||||
type toolCallAction struct {
|
||||
run bool // execute the call
|
||||
reason string // when run==false, the human reason fed back to the model
|
||||
}
|
||||
|
||||
// runToolCalls executes a batch of model-requested tool calls. It classifies
|
||||
// duplicate invocations (the critical-tool-loop safety net), applies the optional
|
||||
// batch/per-call hooks, runs the surviving calls in parallel (bounded) or
|
||||
// serially, and feeds every outcome back as a RoleTool message in the original
|
||||
// call order. It returns the number of calls actually invoked (executed), the
|
||||
// updated message slice, and whether the round should terminate.
|
||||
//
|
||||
// Invocation is delegated to the dispatched tool, which applies the per-tool
|
||||
// deadline; a missing dispatcher is fed back as an error so the loop never
|
||||
// panics or crashes on an unhandled call.
|
||||
func (l *Loop) runToolCalls(ctx context.Context, messages []model.Message, calls []agent.ToolCall, st *toolLoopState) (toolRunResult, error) {
|
||||
d := l.dispatcher()
|
||||
out := messages
|
||||
executed := 0
|
||||
for _, tc := range calls {
|
||||
var (
|
||||
result any
|
||||
invokeErr error
|
||||
)
|
||||
if d == nil {
|
||||
invokeErr = fmt.Errorf("no tool dispatcher configured for %q", tc.Name)
|
||||
} else {
|
||||
_, toolSpan := l.span(ctx, "tool."+tc.Name, trace.SpanKindTool)
|
||||
result, invokeErr = d.Invoke(ctx, tc.Name, tc.Args)
|
||||
if invokeErr != nil {
|
||||
l.spanProp(toolSpan, "error", invokeErr.Error())
|
||||
l.finishSpan(toolSpan, trace.SpanStatusError)
|
||||
} else {
|
||||
l.spanProp(toolSpan, "result", result)
|
||||
l.finishSpan(toolSpan, trace.SpanStatusOK)
|
||||
res := toolRunResult{messages: messages}
|
||||
if len(calls) == 0 {
|
||||
return res, nil
|
||||
}
|
||||
|
||||
actions, terminate := classifyToolBatch(st, calls)
|
||||
if terminate {
|
||||
res.terminate = true
|
||||
}
|
||||
|
||||
// BatchAdmit hook (audit / political review): block the whole batch.
|
||||
if l.hooks.BatchAdmit != nil {
|
||||
if ok, reason := l.hooks.BatchAdmit(ctx, calls); !ok {
|
||||
if reason == "" {
|
||||
reason = "tool batch blocked by policy"
|
||||
}
|
||||
for i := range calls {
|
||||
actions[i] = toolCallAction{run: false, reason: reason}
|
||||
}
|
||||
}
|
||||
executed++
|
||||
out = append(out, toolResultMessage(tc, result, invokeErr))
|
||||
}
|
||||
return out, executed, nil
|
||||
|
||||
// CallAdmit hook: per-call veto over the calls we intend to run.
|
||||
if l.hooks.CallAdmit != nil {
|
||||
for i := range calls {
|
||||
if !actions[i].run {
|
||||
continue
|
||||
}
|
||||
if veto := l.hooks.CallAdmit(ctx, calls[i]); veto != nil && veto.Block {
|
||||
reason := veto.Reason
|
||||
if reason == "" {
|
||||
reason = "tool call blocked by policy"
|
||||
}
|
||||
actions[i] = toolCallAction{run: false, reason: reason}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Decide serial vs parallel: explicit sequential mode, or any call whose tool
|
||||
// is declared sequential (a single sequential marker makes the whole group
|
||||
// serial, matching OpenClaw's launchParallelToolCalls).
|
||||
sequential := l.toolExec == toolExecSequential
|
||||
if !sequential && d != nil {
|
||||
for i := range calls {
|
||||
if actions[i].run && d.IsSequential(calls[i].Name) {
|
||||
sequential = true
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
outcomes := make([]ToolOutcome, len(calls))
|
||||
if sequential {
|
||||
for i := range calls {
|
||||
if actions[i].run {
|
||||
outcomes[i] = l.invokeOne(ctx, d, calls[i])
|
||||
res.executed++
|
||||
} else {
|
||||
outcomes[i] = skippedOutcome(actions[i].reason)
|
||||
}
|
||||
}
|
||||
} else {
|
||||
idxs := make([]int, 0, len(calls))
|
||||
for i := range calls {
|
||||
if actions[i].run {
|
||||
idxs = append(idxs, i)
|
||||
} else {
|
||||
outcomes[i] = skippedOutcome(actions[i].reason)
|
||||
}
|
||||
}
|
||||
l.invokeParallel(ctx, d, calls, idxs, outcomes)
|
||||
res.executed += len(idxs)
|
||||
}
|
||||
|
||||
// AfterCall hook (only for calls that actually executed).
|
||||
if l.hooks.AfterCall != nil {
|
||||
for i := range calls {
|
||||
if outcomes[i].Skipped {
|
||||
continue
|
||||
}
|
||||
if after := l.hooks.AfterCall(ctx, calls[i], outcomes[i]); after != nil {
|
||||
outcomes[i] = *after
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// AfterOutcome hook (runs on every finalized outcome, skipped or not).
|
||||
if l.hooks.AfterOutcome != nil {
|
||||
for i := range calls {
|
||||
if after := l.hooks.AfterOutcome(ctx, calls[i], outcomes[i]); after != nil {
|
||||
outcomes[i] = *after
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// A hook may ask to terminate the round by marking every call terminate
|
||||
// (OpenClaw's shouldTerminateToolBatch).
|
||||
if !res.terminate && shouldTerminateBatch(outcomes) {
|
||||
res.terminate = true
|
||||
}
|
||||
|
||||
// Render results in the original call order so the model sees a stable feed.
|
||||
for i := range calls {
|
||||
res.messages = append(res.messages, toolResultMessage(calls[i], outcomes[i]))
|
||||
}
|
||||
return res, nil
|
||||
}
|
||||
|
||||
// classifyToolBatch partitions a batch into run/skip decisions, enforcing the
|
||||
// critical-tool-loop safety net:
|
||||
//
|
||||
// - A call identical (same name + arguments) to one earlier in the same batch
|
||||
// is skipped with a duplicate hint (never executes).
|
||||
// - A call identical to one from a previous round is a critical-loop repeat:
|
||||
// the first occurrence blocks the repeated call and sets criticalSeen, so the
|
||||
// model gets a turn to reassess; a second consecutive occurrence terminates
|
||||
// the whole run.
|
||||
//
|
||||
// It returns (actions, terminate). When terminate is true every call is blocked
|
||||
// with criticalToolLoopTerminalReason and the round must end.
|
||||
func classifyToolBatch(st *toolLoopState, calls []agent.ToolCall) ([]toolCallAction, bool) {
|
||||
seen := make(map[string]bool, len(calls))
|
||||
actions := make([]toolCallAction, len(calls))
|
||||
repeat := false
|
||||
for i, call := range calls {
|
||||
fp := toolFingerprint(call)
|
||||
if seen[fp] {
|
||||
// Duplicate of a call already in this batch.
|
||||
if st.prevFP[fp] {
|
||||
actions[i] = toolCallAction{run: false, reason: repeatedCallReason()}
|
||||
repeat = true
|
||||
} else {
|
||||
actions[i] = toolCallAction{run: false, reason: duplicateCallReason()}
|
||||
}
|
||||
continue
|
||||
}
|
||||
seen[fp] = true
|
||||
if st.prevFP[fp] {
|
||||
// Repeated from the previous round — a critical loop.
|
||||
actions[i] = toolCallAction{run: false, reason: repeatedCallReason()}
|
||||
repeat = true
|
||||
} else {
|
||||
actions[i] = toolCallAction{run: true}
|
||||
}
|
||||
}
|
||||
|
||||
// Remember which fingerprints were live this round for the next round's
|
||||
// cross-round repeat detection.
|
||||
st.prevFP = seen
|
||||
|
||||
terminate := false
|
||||
if repeat {
|
||||
if st.criticalSeen {
|
||||
terminate = true
|
||||
for i := range actions {
|
||||
actions[i] = toolCallAction{run: false, reason: criticalToolLoopTerminalReason}
|
||||
}
|
||||
} else {
|
||||
st.criticalSeen = true
|
||||
}
|
||||
}
|
||||
return actions, terminate
|
||||
}
|
||||
|
||||
// invokeOne executes a single tool call under its per-tool deadline, emitting a
|
||||
// tool span, streaming tool_execution_update progress and normalizing the
|
||||
// outcome.
|
||||
func (l *Loop) invokeOne(ctx context.Context, d *tool.Dispatcher, tc agent.ToolCall) ToolOutcome {
|
||||
if d == nil {
|
||||
return ToolOutcome{Err: fmt.Errorf("no tool dispatcher configured for %q", tc.Name), ErrKind: tool.KindExecution}
|
||||
}
|
||||
l.emitToolExecution(tc.Name, "start")
|
||||
_, toolSpan := l.span(ctx, "tool."+tc.Name, trace.SpanKindTool)
|
||||
result, err := d.Invoke(ctx, tc.Name, tc.Args)
|
||||
phase := "end"
|
||||
if err != nil {
|
||||
phase = "end:error"
|
||||
}
|
||||
l.emitToolExecution(tc.Name, phase)
|
||||
out := ToolOutcome{Result: result, Err: err, ErrKind: errorKind(err)}
|
||||
if err != nil {
|
||||
l.spanProp(toolSpan, "error", err.Error())
|
||||
l.spanProp(toolSpan, "error_kind", out.ErrKind)
|
||||
l.finishSpan(toolSpan, trace.SpanStatusError)
|
||||
} else {
|
||||
l.spanProp(toolSpan, "result", result)
|
||||
l.finishSpan(toolSpan, trace.SpanStatusOK)
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// emitToolExecution forwards a tool_execution_update progress event to the
|
||||
// frontend when the loop is on the streaming path (OnStream configured); it is a
|
||||
// no-op otherwise. phase is a short label like "start" or "end:error".
|
||||
func (l *Loop) emitToolExecution(name, phase string) {
|
||||
if l.onStream == nil {
|
||||
return
|
||||
}
|
||||
l.onStream(model.StreamEvent{Kind: model.StreamKindToolExecution, Delta: phase + ":" + name})
|
||||
}
|
||||
|
||||
// invokeParallel runs calls at idxs concurrently, capped at the loop's
|
||||
// parallelism, writing each outcome back into out at its call index so callers
|
||||
// can render results in the original order. The semaphore bounds concurrency and
|
||||
// in-flight goroutines release their slot on completion, so a canceled context
|
||||
// (which makes every Invoke return promptly) cannot leak goroutines.
|
||||
func (l *Loop) invokeParallel(ctx context.Context, d *tool.Dispatcher, calls []agent.ToolCall, idxs []int, out []ToolOutcome) {
|
||||
if len(idxs) == 0 {
|
||||
return
|
||||
}
|
||||
sem := make(chan struct{}, l.toolParallelism)
|
||||
var wg sync.WaitGroup
|
||||
for _, i := range idxs {
|
||||
wg.Add(1)
|
||||
sem <- struct{}{}
|
||||
go func(i int) {
|
||||
defer wg.Done()
|
||||
defer func() { <-sem }()
|
||||
out[i] = l.invokeOne(ctx, d, calls[i])
|
||||
}(i)
|
||||
}
|
||||
wg.Wait()
|
||||
}
|
||||
|
||||
// returned by classifyToolBatch for the two skip reasons.
|
||||
func duplicateCallReason() string {
|
||||
return "duplicate call with identical arguments already issued in this batch"
|
||||
}
|
||||
|
||||
func repeatedCallReason() string {
|
||||
return "already used with identical arguments in a previous round; do not repeat it"
|
||||
}
|
||||
|
||||
// skippedOutcome builds a Skipped outcome carrying the human reason.
|
||||
func skippedOutcome(reason string) ToolOutcome {
|
||||
if reason == "" {
|
||||
reason = "tool call skipped"
|
||||
}
|
||||
return ToolOutcome{Skipped: true, Reason: reason}
|
||||
}
|
||||
|
||||
// shouldTerminateBatch reports whether every call in the batch asked to terminate
|
||||
// (OpenClaw's shouldTerminateToolBatch), so a hook can stop the round.
|
||||
func shouldTerminateBatch(outcomes []ToolOutcome) bool {
|
||||
if len(outcomes) == 0 {
|
||||
return false
|
||||
}
|
||||
for _, o := range outcomes {
|
||||
if !o.Terminate {
|
||||
return false
|
||||
}
|
||||
}
|
||||
return true
|
||||
}
|
||||
|
||||
// toolFingerprint canonicalizes a tool call (name + args) so identical calls can
|
||||
// be detected. Args are JSON-marshaled, so equivalent objects with different key
|
||||
// orders collapse to the same fingerprint; a marshal failure falls back to %v.
|
||||
func toolFingerprint(call agent.ToolCall) string {
|
||||
b, err := json.Marshal(call.Args)
|
||||
if err != nil {
|
||||
b = []byte(fmt.Sprintf("%v", call.Args))
|
||||
}
|
||||
return call.Name + "\x00" + string(b)
|
||||
}
|
||||
|
||||
// errorKind classifies an invocation error into a tool.Kind* label so the model
|
||||
// can distinguish an argument-validation failure (re-issue a corrected call) from
|
||||
// an execution failure. A nil error yields "" (success).
|
||||
func errorKind(err error) string {
|
||||
if err == nil {
|
||||
return ""
|
||||
}
|
||||
var te *tool.ToolError
|
||||
if errors.As(err, &te) {
|
||||
return te.Kind()
|
||||
}
|
||||
if errors.Is(err, tool.ErrInvalidArgs) {
|
||||
return tool.KindArgumentValidation
|
||||
}
|
||||
return tool.KindExecution
|
||||
}
|
||||
|
||||
// dispatcher returns the loop's tool dispatcher, falling back to the agent's own
|
||||
@@ -58,15 +400,32 @@ func (l *Loop) dispatcher() *tool.Dispatcher {
|
||||
}
|
||||
|
||||
// toolResultMessage renders a tool call's outcome as a RoleTool message ready to
|
||||
// be fed back to the model. Errors are included in the text so the LLM can
|
||||
// react to a failed or timed-out call.
|
||||
func toolResultMessage(tc agent.ToolCall, result any, invokeErr error) model.Message {
|
||||
text := fmt.Sprintf("tool %s result: %s", tc.Name, formatToolResult(result))
|
||||
if invokeErr != nil {
|
||||
text = fmt.Sprintf("tool %s failed: %v", tc.Name, invokeErr)
|
||||
}
|
||||
// be fed back to the model. Skipped calls carry their reason; failures carry a
|
||||
// structured {kind,message} so the LLM can react appropriately; success carries
|
||||
// the value.
|
||||
func toolResultMessage(tc agent.ToolCall, out ToolOutcome) model.Message {
|
||||
return model.Message{Role: model.RoleTool, ToolCallName: tc.Name,
|
||||
Content: []model.Content{{Type: model.ContentTypeText, Text: text}}}
|
||||
Content: []model.Content{{Type: model.ContentTypeText, Text: toolResultText(tc, out)}}}
|
||||
}
|
||||
|
||||
// toolResultText renders the text payload of a tool result message.
|
||||
func toolResultText(tc agent.ToolCall, out ToolOutcome) string {
|
||||
switch {
|
||||
case out.Skipped:
|
||||
if out.Reason == "" {
|
||||
return fmt.Sprintf("tool %s skipped", tc.Name)
|
||||
}
|
||||
return fmt.Sprintf("tool %s skipped: %s", tc.Name, out.Reason)
|
||||
case out.Err != nil:
|
||||
if kind := out.ErrKind; kind != "" {
|
||||
if payload, err := json.Marshal(map[string]string{"kind": kind, "message": out.Err.Error()}); err == nil {
|
||||
return fmt.Sprintf("tool %s failed: %s", tc.Name, payload)
|
||||
}
|
||||
}
|
||||
return fmt.Sprintf("tool %s failed: %v", tc.Name, out.Err)
|
||||
default:
|
||||
return fmt.Sprintf("tool %s result: %s", tc.Name, formatToolResult(out.Result))
|
||||
}
|
||||
}
|
||||
|
||||
// formatToolResult renders a tool return value as text for the model. Strings are
|
||||
|
||||
Reference in new issue
Block a user