mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-11-20 11:20:35 +00:00
* fix(agents): count each delegation once when a provider reuses its call id Tool-call ids are unique per response, not per conversation. Some providers number every response's calls from call_0, so two task calls in one run can share an id. The delegation ledger used (run_id, tool_call_id) as a delegation's identity: - extract_delegations built one id -> entry map over the whole run, so a later call_0 replaced the earlier delegation's description and took its result while it was still running. - merge_delegations replaced the same (run_id, id), keeping one entry. - SubagentLimitMiddleware counted distinct ids, so the per-run cap (subagents.max_total_per_run) never advanced past the first call_0 and a run could launch any number of subagents one response at a time. Each entry now also records dispatch_message_id, the AIMessage that issued the call, and results pair through pair_tool_call_results, which answers a call only from its own response. The reducer, DurableContext's change filter and the cap use the extended identity. An entry without a dispatch id still updates its run's entry for that call id, and a dispatch-scoped entry adopts a ledger entry written before the field existed, so runs in flight across the upgrade are not counted twice. The steer path names the dispatching AIMessage from the tool request's state, so its delegation update and the graph's own capture stay one entry. * fix(agents): close an earlier run's dangling dispatch by its own response _close_delegations_left_by_earlier_runs decided "answered" by (run_id, tool_call_id). When a stopped run had dispatched call_0 twice, the first reply kept the second, dangling entry in_progress, so the lead kept hearing "already delegated" for work nothing would finish. Entries that carry dispatch_message_id are now decided by pairing that response's calls through pair_tool_call_results. Legacy entries and dispatches no longer in history keep the id-based inference. Also pin that two runs reusing call_0 stay two ledger entries, and cross-reference the three delegation identity helpers. * fix(agents): settle an approval-gated task delegation in the ledger With `task` in `hitl_approval.tools`, the paused run records the dispatch as in_progress and the resume run executes it. The resume run opens with no HumanMessage, so its capture window starts after the pre-existing messages and never contains the dispatching AIMessage: the result was dropped and the entry stayed in_progress with no result_brief, forever. DurableContext now pairs results the resumed window receives with the last pre-existing dispatch and settles the issuing run's entry, keeping its run_id instead of re-tagging it. HITL denials of `task` carry `cancelled` subagent status, so a rejected or denied delegation settles too. * fix(agents): address review on the delegation ledger - Steer path: hold each wait's dispatch AIMessage locally and pass it to the observer, so a later response reusing the call id while the first call is still observed cannot take over its args or dispatch id. - New-turn close: a dispatch whose reply carries subagent status settles from that reply instead of staying in_progress, covering a crash between the tools checkpoint and the next capture. - Reuse thread_state.delegation_key instead of a duplicate identity helper in DurableContext. - CHANGELOG: reference #8128. * docs(changelog): drop the #8128 entry per review
280 lines
15 KiB
Python
280 lines
15 KiB
Python
"""Intercept the bound tool call, after argument resolution and before execution."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import asyncio
|
|
import copy
|
|
from collections.abc import Mapping
|
|
from typing import Any
|
|
from uuid import uuid4
|
|
|
|
from jsonschema import Draft202012Validator
|
|
from langchain.agents.middleware import AgentMiddleware
|
|
from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
|
|
from langgraph.config import get_config
|
|
from langgraph.errors import GraphBubbleUp
|
|
from langgraph.func import task
|
|
from langgraph.types import interrupt
|
|
|
|
from deerflow.agents.interaction_policy import resolve_run_interaction_policy
|
|
from deerflow.agents.middlewares.tool_call_metadata import clone_ai_message_with_tool_calls
|
|
from deerflow.approvals.policy import action_fingerprint, canonical_json, digest, effective_outcome, is_routine_tool, permits_thread_grant, resolve_mode, tool_descriptor
|
|
from deerflow.approvals.reviewer import REVIEW_POLICY_VERSION, review_operation
|
|
from deerflow.runtime.run_origin import origin_kind_of
|
|
from deerflow.utils.messages import get_original_user_content_text
|
|
|
|
APPROVAL_RUNTIME_KEY = "__tool_approval_runtime"
|
|
|
|
|
|
def _context(request) -> dict:
|
|
context = getattr(request.runtime, "context", None)
|
|
return context if isinstance(context, dict) else {}
|
|
|
|
|
|
def user_instructions(messages) -> list[str]:
|
|
return [
|
|
get_original_user_content_text(message.content, message.additional_kwargs)
|
|
for message in messages
|
|
if isinstance(message, HumanMessage) and not message.additional_kwargs.get("deerflow_producer_kind") and not message.additional_kwargs.get("untrusted_input")
|
|
]
|
|
|
|
|
|
def denial(request, reason: str) -> ToolMessage:
|
|
additional_kwargs: dict[str, Any] = {}
|
|
if request.tool_call["name"] == "task":
|
|
# A denied delegation never ran. Stamp the subagent status contract so
|
|
# the delegation ledger settles it as cancelled instead of leaving it
|
|
# in_progress; the ledger never infers status from result text.
|
|
from deerflow.subagents.status_contract import make_subagent_additional_kwargs
|
|
|
|
additional_kwargs = make_subagent_additional_kwargs("cancelled", error=reason)
|
|
return ToolMessage(
|
|
content=f"The tool was not executed. {reason} Do not retry without new user authorization.",
|
|
name=request.tool_call["name"],
|
|
tool_call_id=request.tool_call["id"],
|
|
status="error",
|
|
additional_kwargs=additional_kwargs,
|
|
)
|
|
|
|
|
|
class ToolApprovalMiddleware(AgentMiddleware):
|
|
"""Ask, Auto and Full share exact operation binding and mandatory inner guards.
|
|
|
|
Root calls use durable LangGraph interrupts. Children keep their original
|
|
invocation suspended through a host-owned approval bridge; they never replay
|
|
an entire delegated task to obtain a decision.
|
|
"""
|
|
|
|
def __init__(self, policy, *, app_config, reviewer=None, supports_resume=True, model_name=None):
|
|
self.policy = policy.model_copy(deep=True)
|
|
self.app_config = app_config
|
|
self.reviewer = reviewer
|
|
self.supports_resume = supports_resume
|
|
self.model_name = model_name
|
|
self.policy_digest = digest({"policy": policy.model_dump(), "reviewer_policy": REVIEW_POLICY_VERSION})
|
|
|
|
def release_policy_parameters(self):
|
|
return {"policy_digest": self.policy_digest}
|
|
|
|
def before_model(self, state, runtime):
|
|
context = getattr(runtime, "context", None) or {}
|
|
bridge = context.get(APPROVAL_RUNTIME_KEY)
|
|
if bridge is not None and not context.get("is_subagent"):
|
|
bridge.set_user_messages(user_instructions(state.get("messages", [])))
|
|
|
|
async def abefore_model(self, state, runtime):
|
|
self.before_model(state, runtime)
|
|
|
|
def after_model(self, state, runtime):
|
|
last = next((message for message in reversed(state.get("messages", [])) if isinstance(message, AIMessage)), None)
|
|
if last is None or not last.tool_calls:
|
|
return None
|
|
ids = [call.get("id") for call in last.tool_calls]
|
|
if all(isinstance(call_id, str) and call_id for call_id in ids) and len(set(ids)) == len(ids):
|
|
return None
|
|
# Neither an interrupt nor a ToolMessage can safely address these calls.
|
|
# Drop the whole group, including ordinary calls sharing an approval id,
|
|
# and synchronize every provider surface before any tool can execute.
|
|
note = "Approval could not be requested because this tool call has no usable id (missing, empty, or duplicated). The tool was not executed. Do not retry unless the user explicitly asks."
|
|
content = [*last.content, {"type": "text", "text": note}] if isinstance(last.content, list) else f"{last.content}\n\n{note}" if last.content else note
|
|
return {"messages": [clone_ai_message_with_tool_calls(last, [], content=content)]}
|
|
|
|
async def aafter_model(self, state, runtime):
|
|
return self.after_model(state, runtime)
|
|
|
|
async def _prepare(self, request) -> dict:
|
|
context = _context(request)
|
|
bridge = context.get(APPROVAL_RUNTIME_KEY)
|
|
mode = bridge.mode if bridge is not None else resolve_mode(self.policy, context)
|
|
descriptor = tool_descriptor(request.tool)
|
|
args = copy.deepcopy(request.tool_call["args"])
|
|
fingerprint = action_fingerprint(descriptor, args, self.policy_digest)
|
|
plan = {
|
|
"request_id": f"tool_approval:{uuid4().hex}",
|
|
"tool_call_id": request.tool_call["id"],
|
|
"tool_name": request.tool_call["name"],
|
|
"descriptor": descriptor,
|
|
"args": args,
|
|
"fingerprint": fingerprint,
|
|
"policy_digest": self.policy_digest,
|
|
"mode": mode,
|
|
"owner": context.get("user_id"),
|
|
"thread_id": context.get("thread_id"),
|
|
"grant_allowed": permits_thread_grant(descriptor) and bridge is not None,
|
|
"outcome": "ask",
|
|
"reason": "Human approval is required for this operation.",
|
|
}
|
|
name = request.tool_call["name"]
|
|
last_ai = next((message for message in reversed(request.state.get("messages", [])) if isinstance(message, AIMessage)), None)
|
|
calls = last_ai.tool_calls if last_ai is not None else [request.tool_call]
|
|
ids = [call.get("id") for call in calls]
|
|
if (self.policy.max_actions and len(calls) > self.policy.max_actions) or len(ids) != len(set(ids)):
|
|
return {**plan, "outcome": "deny", "reason": "Too many tool calls or duplicate tool-call identities in this turn."}
|
|
if name in self.policy.deny_tools:
|
|
return {**plan, "outcome": "deny", "reason": "The deployment policy denies this tool."}
|
|
if name in self.policy.always_ask_tools:
|
|
return {**plan, "grant_allowed": False}
|
|
if mode == "ask" and self.policy.non_interactive == "allow" and self.supports_resume and not context.get("is_subagent"):
|
|
interactive = resolve_run_interaction_policy({"context": context}).allows_clarification
|
|
if not interactive or origin_kind_of(get_config().get("metadata") or {}) is not None:
|
|
return {**plan, "outcome": "allow", "reason": "The operator explicitly allows unattended operations."}
|
|
if mode == "full" or name in self.policy.allow_tools:
|
|
return {**plan, "outcome": "allow", "reason": "Allowed by the selected permission mode or operator rule."}
|
|
if name not in self.policy.tools and is_routine_tool(descriptor, request.tool):
|
|
return {**plan, "outcome": "allow", "reason": "Trusted host read or navigation tool."}
|
|
if not self.policy.review_unknown_tools and name not in self.policy.tools:
|
|
return {**plan, "outcome": "allow", "reason": "The operator limits review to explicitly selected tools."}
|
|
if bridge is not None and await bridge.has_grant(fingerprint):
|
|
return {**plan, "outcome": "allow", "basis": "thread_grant", "reason": "Exact operation approved for this thread."}
|
|
if mode == "auto":
|
|
instructions = bridge.user_messages if bridge is not None else ([] if context.get("is_subagent") else user_instructions(request.state.get("messages", [])))
|
|
action = {"tool": descriptor, "arguments": args}
|
|
if self.reviewer is not None:
|
|
try:
|
|
async with asyncio.timeout(self.policy.reviewer_timeout_seconds):
|
|
verdict = await self.reviewer(action, instructions)
|
|
except Exception:
|
|
verdict = {"outcome": "ask", "reason": "Automatic review failed; human approval is required."}
|
|
else:
|
|
verdict = await review_operation(action, instructions, app_config=self.app_config, model_name=self.model_name or context.get("model_name"), usage_recorder=bridge.record_usage if bridge else None, context=context)
|
|
if not isinstance(verdict, dict):
|
|
verdict = {}
|
|
plan.update(outcome=effective_outcome(verdict), reason=str(verdict.get("reason", "Human approval is required."))[:1000], review=verdict)
|
|
return plan
|
|
|
|
def _payload(self, plan: dict, context: dict) -> dict:
|
|
action = {key: plan[key] for key in ("request_id", "tool_call_id", "tool_name", "args", "fingerprint", "reason")}
|
|
action.update(args_summary=plan["args"], args_schema=plan["descriptor"]["schema"], source=plan["descriptor"]["source"], grant_allowed=plan["grant_allowed"])
|
|
decisions = ["approve", "reject", "edit"]
|
|
if plan["grant_allowed"]:
|
|
decisions.append("approve_thread")
|
|
return {
|
|
"version": 2,
|
|
"kind": "hitl_approval",
|
|
"max_payload_bytes": self.policy.max_payload_bytes,
|
|
"request_id": plan["request_id"],
|
|
"actions": [action],
|
|
"allowed_decisions": decisions,
|
|
"pending_tool_call_ids": [plan["tool_call_id"]],
|
|
"agent_id": context.get("agent_id"),
|
|
}
|
|
|
|
def _validate_response(self, plan, response):
|
|
responses = response.get("responses") if isinstance(response, Mapping) else None
|
|
if not isinstance(responses, list):
|
|
raise ValueError("Invalid approval response.")
|
|
matching = [item for item in responses if isinstance(item, dict) and item.get("request_id") == plan["request_id"]]
|
|
if len(matching) != 1 or matching[0].get("tool_call_id") != plan["tool_call_id"]:
|
|
raise ValueError("Stale or mismatched approval response.")
|
|
response = matching[0]
|
|
decision = response.get("option_id")
|
|
if decision not in ("approve", "approve_thread", "edit", "reject"):
|
|
raise ValueError("Unsupported approval decision.")
|
|
if decision == "approve_thread" and not plan["grant_allowed"]:
|
|
raise ValueError("This tool does not support a persistent thread grant.")
|
|
args = response.get("args") if decision == "edit" else plan["args"]
|
|
if not isinstance(args, dict):
|
|
raise ValueError("Edited arguments must be a JSON object.")
|
|
if len(canonical_json(args).encode()) > self.policy.max_payload_bytes:
|
|
raise ValueError("Edited arguments exceed the approval size limit.")
|
|
schema = plan["descriptor"]["schema"]
|
|
Draft202012Validator(schema).validate(args)
|
|
# Injected runtime fields are never editable, even when the provider's
|
|
# public JSON schema permits additional properties.
|
|
properties = schema.get("properties")
|
|
if isinstance(properties, dict) and set(args) - set(properties):
|
|
raise ValueError("Edited arguments contain unknown or injected fields.")
|
|
return decision, args
|
|
|
|
async def _decide(self, request, plan):
|
|
context = _context(request)
|
|
if plan["policy_digest"] != self.policy_digest or plan["owner"] != context.get("user_id") or plan["thread_id"] != context.get("thread_id"):
|
|
return denial(request, "The policy or request owner changed while approval was pending.")
|
|
if plan["fingerprint"] != action_fingerprint(tool_descriptor(request.tool), request.tool_call["args"], self.policy_digest):
|
|
return denial(request, "The tool or its arguments changed after review.")
|
|
bridge = context.get(APPROVAL_RUNTIME_KEY)
|
|
if plan.get("basis") == "thread_grant" and (bridge is None or not await bridge.has_grant(plan["fingerprint"])):
|
|
return denial(request, "The thread grant was revoked. Request fresh approval.")
|
|
if plan["outcome"] == "deny":
|
|
if bridge is not None:
|
|
await bridge.record_decision(plan, "deny")
|
|
return denial(request, plan["reason"])
|
|
if plan["outcome"] == "allow":
|
|
if bridge is not None:
|
|
await bridge.record_decision(plan, "allow")
|
|
return request
|
|
payload = self._payload(plan, context)
|
|
if len(canonical_json(payload).encode()) > self.policy.max_payload_bytes:
|
|
return denial(request, "The complete approval card exceeds the size limit.")
|
|
interactive = resolve_run_interaction_policy({"context": context}).allows_clarification
|
|
if not interactive or origin_kind_of(get_config().get("metadata") or {}) is not None:
|
|
return denial(request, "This run cannot collect human approval.")
|
|
if context.get("is_subagent"):
|
|
if bridge is None or not bridge.interactive:
|
|
return denial(request, "No parent approval channel is available.")
|
|
response = await bridge.wait_for_decision(plan, payload)
|
|
elif self.supports_resume:
|
|
response = interrupt(payload)
|
|
else:
|
|
return denial(request, "This runtime does not support approval resume.")
|
|
try:
|
|
decision, args = self._validate_response(plan, response)
|
|
except Exception:
|
|
return denial(request, "Invalid, stale, or schema-incompatible approval response.")
|
|
if bridge is not None:
|
|
await bridge.record_decision(plan, decision, arguments=args)
|
|
if decision == "reject":
|
|
reason = next((item.get("value", "") for item in response["responses"] if item.get("request_id") == plan["request_id"]), "")
|
|
return denial(request, f"The user rejected the operation. {str(reason)[:2000]}")
|
|
# The handler includes mandatory authorization and guardrail middleware;
|
|
# it evaluates the edited arguments as well as the original ones.
|
|
return request.override(tool_call={**request.tool_call, "args": args})
|
|
|
|
async def awrap_tool_call(self, request, handler):
|
|
@task(name="prepare_tool_approval")
|
|
async def prepare():
|
|
return await self._prepare(request)
|
|
|
|
try:
|
|
plan = await prepare()
|
|
decision = await self._decide(request, plan)
|
|
except GraphBubbleUp:
|
|
raise
|
|
except Exception:
|
|
return denial(request, "The approval service is unavailable. The operation requires a fresh review.")
|
|
return decision if isinstance(decision, ToolMessage) else await handler(decision)
|
|
|
|
def wrap_tool_call(self, request, handler):
|
|
@task(name="prepare_tool_approval")
|
|
def prepare():
|
|
return asyncio.run(self._prepare(request))
|
|
|
|
try:
|
|
plan = prepare().result()
|
|
decision = asyncio.run(self._decide(request, plan))
|
|
except GraphBubbleUp:
|
|
raise
|
|
except Exception:
|
|
return denial(request, "The approval service is unavailable. The operation requires a fresh review.")
|
|
return decision if isinstance(decision, ToolMessage) else handler(decision)
|