Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
feat(agent): add steering support to the SDK and WebUI (#3638)
qbc9a2d631fc7fa
diff --git a/examples/web_ui/frontend/src/api/chat.ts b/examples/web_ui/frontend/src/api/chat.tsindex 7fae0c264..128689ac9 100644--- a/examples/web_ui/frontend/src/api/chat.ts+++ b/examples/web_ui/frontend/src/api/chat.ts@@ -10,6 +10,10 @@ export interface ChatQueueItem {created_at: string;/** One message or an ordered message group executed as one turn. */input: Msg | Msg[];+ /** Current deferred-send or steering lifecycle state. */+ state: 'queued' | 'steering' | 'failed';+ /** Visible preparation failure for a failed steering attempt. */+ error: string | null;}export interface ChatQueueResponse {@@ -87,6 +91,22 @@ export const chatApi = {session_id: sessionId,}),+ /**+ * Reserve one pending item for the reply that is currently active.+ *+ * @param itemId - Stable id of the pending item.+ * @param agentId - Agent that owns the target session.+ * @param sessionId - Session whose reply should be steered.+ * @param replyId - Active reply observed by the client.+ * @returns Complete queue snapshot with the item marked as steering.+ */+ steerQueued: (itemId: string, agentId: string, sessionId: string, replyId: string) =>+ client.post<ChatQueueResponse>(`/chat/queue/${encodeURIComponent(itemId)}/steer`, {+ agent_id: agentId,+ session_id: sessionId,+ reply_id: replyId,+ }),+/*** Apply an exact permutation of the current pending queue.*diff --git a/examples/web_ui/frontend/src/components/chat/ASMessageBubble.tsx b/examples/web_ui/frontend/src/components/chat/ASMessageBubble.tsxindex a0cb43b20..aa6d1760b 100644--- a/examples/web_ui/frontend/src/components/chat/ASMessageBubble.tsx+++ b/examples/web_ui/frontend/src/components/chat/ASMessageBubble.tsx@@ -2,6 +2,7 @@ import { ReplyFinishedReason } from '@agentscope-ai/agentscope/event';import type {ContentBlock,DataBlock,+ HintBlock,Msg,TextBlock,ThinkingBlock,@@ -15,6 +16,7 @@ import {CheckCircle,ChevronRight,CirclePlay,+ CornerDownRight,Copy,FileText,FileVideo2,@@ -67,6 +69,60 @@ interface ToolCallGroupBlock {type ExtendedContentBlock = ContentBlock | ToolCallGroupBlock;+const STEERING_HINT_SOURCE = 'chat_input_steering';++const isSteeringHint = (block: ExtendedContentBlock): block is HintBlock =>+ block.type === 'hint' && block.source === STEERING_HINT_SOURCE;++const getHintItems = (block: HintBlock): (TextBlock | DataBlock)[] =>+ typeof block.hint === 'string'+ ? [+ {+ type: 'text',+ id: `${block.id}-text`,+ text: block.hint,+ created_at: block.created_at,+ },+ ]+ : block.hint;++interface SteeringMessageBubbleProps {+ blocks: ContentBlock[];+ status: 'steering' | 'steered';+}++/** User-facing projection of a prompt steering the active reply. */+export function SteeringMessageBubble({ blocks, status }: SteeringMessageBubbleProps) {+ const { t } = useTranslation();+ return (+ <div className="flex w-full flex-col items-end gap-1">+ <Bubble align="end" variant="muted">+ <BubbleContent className="flex flex-col gap-2">+ {blocks.map((block) => (+ <ASBlock block={block} key={block.id} />+ ))}+ </BubbleContent>+ </Bubble>+ <div+ className="flex items-center gap-1 px-1 text-xs text-muted-foreground"+ role="status"+ aria-live="polite"+ >+ {status === 'steering' ? (+ <Loader2 className="size-3 animate-spin" aria-hidden="true" />+ ) : (+ <CornerDownRight className="size-3" aria-hidden="true" />+ )}+ <span>+ {status === 'steering'+ ? t('chatQueue.stateSteering')+ : t('chatQueue.stateSteered')}+ </span>+ </div>+ </div>+ );+}+/*** Pair every tool_call with its tool_result (by id) and collect *consecutive** tool calls into a single `tool_call_group`, regardless of tool name — so a@@ -459,13 +515,21 @@ function ASMessageBubbleComponent({ message }: MessageBubbleProps) {<MessageContent>{blocks.filter((block) => block.type !== 'data')- .map((block, index) => (- <Bubble key={index} variant={isUser ? 'muted' : 'ghost'}>- <BubbleContent>- <ASBlock block={block} />- </BubbleContent>- </Bubble>- ))}+ .map((block, index) =>+ isSteeringHint(block) ? (+ <SteeringMessageBubble+ blocks={getHintItems(block)}+ status="steered"+ key={block.id}+ />+ ) : (+ <Bubble key={index} variant={isUser ? 'muted' : 'ghost'}>+ <BubbleContent>+ <ASBlock block={block} />+ </BubbleContent>+ </Bubble>+ ),+ )}{message.finished_reason === ReplyFinishedReason.ERROR && (<Alertvariant="destructive"@@ -697,17 +761,7 @@ export function ASBlock({ block, ...props }: ASBlockProps) {} else {hintLabel = t('common.message');}- const items: (TextBlock | DataBlock)[] =- typeof block.hint === 'string'- ? [- {- type: 'text',- id: `${block.id}-text`,- text: block.hint,- created_at: block.created_at,- },- ]- : block.hint;+ const items = getHintItems(block);return (<Collapsible><CollapsibleTrigger asChild>diff --git a/examples/web_ui/frontend/src/components/chat/ChatContent.tsx b/examples/web_ui/frontend/src/components/chat/ChatContent.tsxindex bbcbf2298..560434776 100644--- a/examples/web_ui/frontend/src/components/chat/ChatContent.tsx+++ b/examples/web_ui/frontend/src/components/chat/ChatContent.tsx@@ -11,7 +11,7 @@ import React, { useEffect, useMemo, useState } from 'react';import type { GitStatus } from '@/api';import type { ChatQueueItem } from '@/api/chat';-import { ASMessageBubble } from '@/components/chat/ASMessageBubble.tsx';+import { ASMessageBubble, SteeringMessageBubble } from '@/components/chat/ASMessageBubble.tsx';import { ConfirmCard } from '@/components/chat/ConfirmCard.tsx';import { FlipCard } from '@/components/chat/FlipCard.tsx';import { QueuedMessages } from '@/components/chat/QueuedMessages.tsx';@@ -80,6 +80,7 @@ interface ChatContentProps {queuedCount: number;queuedItems: ChatQueueItem[];queueReorderDisabled: boolean;+ activeReplyId: string | null;disabled: boolean;onSend: (content: ContentBlock[]) => Promise<void> | void;onUserConfirm: (@@ -94,6 +95,7 @@ interface ChatContentProps {onInterrupt?: () => void;onUpdateQueued: (itemId: string, text: string) => Promise<void>;onDeleteQueued: (itemId: string) => Promise<void>;+ onSteerQueued: (itemId: string, replyId: string) => Promise<void>;onMoveQueued: (itemId: string, direction: -1 | 1) => Promise<void>;onReorderQueued: (itemIds: string[]) => Promise<void>;voiceState?: RealtimeConnectionState;@@ -132,6 +134,7 @@ const ChatContentComponent: React.FC<ChatContentProps> = ({queuedCount,queuedItems,queueReorderDisabled,+ activeReplyId,disabled,onSend,onUserConfirm,@@ -140,6 +143,7 @@ const ChatContentComponent: React.FC<ChatContentProps> = ({onInterrupt,onUpdateQueued,onDeleteQueued,+ onSteerQueued,onMoveQueued,onReorderQueued,voiceState,@@ -156,10 +160,29 @@ const ChatContentComponent: React.FC<ChatContentProps> = ({onRefreshGit,}) => {const { t, i18n } = useTranslation();+ const { deferredItems, steeringMessages } = useMemo(() => {+ const deferred: ChatQueueItem[] = [];+ const steering: Array<{ id: string; content: ContentBlock[] }> = [];+ for (const item of queuedItems) {+ if (item.state !== 'steering') {+ deferred.push(item);+ continue;+ }+ const messages = Array.isArray(item.input) ? item.input : [item.input];+ for (const message of messages) {+ steering.push({+ id: `${item.id}:${message.id}`,+ content: message.content,+ });+ }+ }+ return { deferredItems: deferred, steeringMessages: steering };+ }, [queuedItems]);+// Only a session that finished loading with nothing in it is empty.// Treating "no messages yet" as empty would flash the greeting over// every session that does have history.- const isEmpty = !loading && msgs.length === 0;+ const isEmpty = !loading && msgs.length === 0 && steeringMessages.length === 0;// A spinner that appears and vanishes inside a couple of frames reads// as a flicker, not as feedback — so hold it back until the load has@@ -236,6 +259,17 @@ const ChatContentComponent: React.FC<ChatContentProps> = ({</MessageScrollerItem>);})}+ {steeringMessages.map((message) => (+ <MessageScrollerItem+ key={message.id}+ messageId={`steering:${message.id}`}+ >+ <SteeringMessageBubble+ blocks={message.content}+ status="steering"+ />+ </MessageScrollerItem>+ ))}{msgs.length > 0 &&msgs[msgs.length - 1].finished_reason ===ReplyFinishedReason.EXCEED_MAX_ITERS &&@@ -310,10 +344,12 @@ const ChatContentComponent: React.FC<ChatContentProps> = ({)}</FlipCard><QueuedMessages- items={queuedItems}+ items={deferredItems}reorderDisabled={queueReorderDisabled}+ activeReplyId={activeReplyId}onUpdate={onUpdateQueued}onDelete={onDeleteQueued}+ onSteer={onSteerQueued}onMove={onMoveQueued}onReorder={onReorderQueued}/>diff --git a/examples/web_ui/frontend/src/components/chat/QueuedMessages.tsx b/examples/web_ui/frontend/src/components/chat/QueuedMessages.tsxindex 967acf599..c630a2fac 100644--- a/examples/web_ui/frontend/src/components/chat/QueuedMessages.tsx+++ b/examples/web_ui/frontend/src/components/chat/QueuedMessages.tsx@@ -1,5 +1,15 @@import { getTextContent } from '@agentscope-ai/agentscope/message';-import { ArrowDown, ArrowUp, Check, GripVertical, Loader2, Pencil, Trash2, X } from 'lucide-react';+import {+ ArrowDown,+ ArrowUp,+ Check,+ CornerDownRight,+ GripVertical,+ Loader2,+ Pencil,+ Trash2,+ X,+} from 'lucide-react';import { type ReactNode, useState } from 'react';import type { ChatQueueItem } from '@/api/chat';@@ -12,8 +22,10 @@ import { cn } from '@/lib/utils';interface QueuedMessagesProps {items: ChatQueueItem[];reorderDisabled: boolean;+ activeReplyId: string | null;onUpdate: (itemId: string, text: string) => Promise<void>;onDelete: (itemId: string) => Promise<void>;+ onSteer: (itemId: string, replyId: string) => Promise<void>;onMove: (itemId: string, direction: -1 | 1) => Promise<void>;onReorder: (itemIds: string[]) => Promise<void>;}@@ -58,8 +70,10 @@ function QueueActionButton({ label, disabled, onClick, children }: QueueActionBuexport function QueuedMessages({items,reorderDisabled,+ activeReplyId,onUpdate,onDelete,+ onSteer,onMove,onReorder,}: QueuedMessagesProps) {@@ -108,7 +122,8 @@ export function QueuedMessages({// Optimistic ids are local-only and cannot be sent to mutation// endpoints until POST /chat returns the stable server id.const busy = busyId === item.id || item.id.startsWith('optimistic:');- const reorderBusy = busy || reorderDisabled;+ const steering = item.state === 'steering';+ const reorderBusy = busy || reorderDisabled || steering;const editable = !Array.isArray(item.input);return (<div@@ -175,6 +190,21 @@ export function QueuedMessages({{itemText(item) || t('chatQueue.attachmentOnly')}</p>)}+ <span+ className={cn(+ 'shrink-0 rounded-full px-2 py-0.5 text-[11px] font-medium',+ item.state === 'steering' && 'bg-primary/10 text-primary',+ item.state === 'failed' && 'bg-destructive/10 text-destructive',+ item.state === 'queued' && 'bg-muted text-muted-foreground',+ )}+ title={item.error ?? undefined}+ >+ {item.state === 'steering'+ ? t('chatQueue.stateSteering')+ : item.state === 'failed'+ ? t('chatQueue.stateFailed')+ : t('chatQueue.stateQueued')}+ </span>{busy ? (<Loader2 className="size-4 shrink-0 animate-spin text-muted-foreground" />@@ -201,6 +231,19 @@ export function QueuedMessages({</>) : (<>+ {activeReplyId && (+ <QueueActionButton+ disabled={steering}+ label={t('chatQueue.steer')}+ onClick={() =>+ void run(item.id, () =>+ onSteer(item.id, activeReplyId),+ )+ }+ >+ <CornerDownRight className="size-3.5" />+ </QueueActionButton>+ )}<QueueActionButtondisabled={reorderBusy || index === 0}label={t('chatQueue.moveUp')}@@ -216,7 +259,7 @@ export function QueuedMessages({<ArrowDown className="size-3.5" /></QueueActionButton><QueueActionButton- disabled={!editable}+ disabled={!editable || steering}label={t('chatQueue.edit')}onClick={() => {setDraft(itemText(item));@@ -226,6 +269,7 @@ export function QueuedMessages({<Pencil className="size-3.5" /></QueueActionButton><QueueActionButton+ disabled={steering}label={t('chatQueue.delete')}onClick={() => void run(item.id, () => onDelete(item.id))}>diff --git a/examples/web_ui/frontend/src/hooks/useChatQueue.ts b/examples/web_ui/frontend/src/hooks/useChatQueue.tsindex 97b02fc9e..31ca511d8 100644--- a/examples/web_ui/frontend/src/hooks/useChatQueue.ts+++ b/examples/web_ui/frontend/src/hooks/useChatQueue.ts@@ -152,6 +152,8 @@ export function useChatQueue(id: optimisticId,created_at: message.created_at,input: message,+ state: 'queued',+ error: null,},]);return optimisticId;@@ -283,6 +285,40 @@ export function useChatQueue([agentId, sessionId, session, applyMutationSnapshot, onError],);+ const steerQueued = useCallback(+ async (itemId: string, replyId: string) => {+ if (!agentId || !sessionId || activeSessionRef.current !== session) return;+ const previousItem = itemsRef.current.find((item) => item.id === itemId);+ if (!previousItem) return;+ updateItems(+ itemsRef.current.map((item) =>+ item.id === itemId+ ? { ...item, state: 'steering' as const, error: null }+ : item,+ ),+ );+ const snapshotVersion = snapshotVersionRef.current;+ try {+ const response = await chatApi.steerQueued(itemId, agentId, sessionId, replyId);+ applyMutationSnapshot(response.items, snapshotVersion);+ } catch (error) {+ if (activeSessionRef.current === session) {+ if (snapshotVersion === snapshotVersionRef.current) {+ updateItems(+ itemsRef.current.map((item) =>+ item.id === itemId ? previousItem : item,+ ),+ );+ }+ void refreshQueue();+ onError(error as Error);+ }+ throw error;+ }+ },+ [agentId, sessionId, session, applyMutationSnapshot, onError, updateItems, refreshQueue],+ );+const reorderQueued = useCallback(async (visibleItemIds: string[]) => {if (!agentId || !sessionId || activeSessionRef.current !== session) return;@@ -356,13 +392,16 @@ export function useChatQueue([conversationMessageIds, items],);const reorderDisabled = useMemo(- () => items.some((item) => item.id.startsWith(OPTIMISTIC_ITEM_PREFIX)),+ () =>+ items.some(+ (item) => item.id.startsWith(OPTIMISTIC_ITEM_PREFIX) || item.state === 'steering',+ ),[items],);return {items: visibleItems,- visibleCount: visibleItems.length,+ visibleCount: visibleItems.filter((item) => item.state !== 'steering').length,pendingCount: items.length,reorderDisabled,addOptimistic,@@ -373,6 +412,7 @@ export function useChatQueue(finishItem,updateQueued,deleteQueued,+ steerQueued,moveQueued,reorderQueued,};diff --git a/examples/web_ui/frontend/src/hooks/useMessages.ts b/examples/web_ui/frontend/src/hooks/useMessages.tsindex a4bc4564f..9a9269d22 100644--- a/examples/web_ui/frontend/src/hooks/useMessages.ts+++ b/examples/web_ui/frontend/src/hooks/useMessages.ts@@ -164,6 +164,9 @@ export function useMessages(// state over a session that does have messages.const [loadedKey, setLoadedKey] = useState<string | null>(null);const [phase, setPhase] = useState<ReplyPhase>('idle');+ // Only a running reply accepts steering. Parked replies retain their+ // streaming phase and currentReplyRef for confirmation and Stop.+ const [activeReplyId, setActiveReplyId] = useState<string | null>(null);const [error, setError] = useState<Error | null>(null);// Pending subagent HITL cards projected onto this (leader) session.const [subagentHitl, setSubagentHitl] = useState<SubagentHitlEntry[]>([]);@@ -180,6 +183,7 @@ export function useMessages(finishItem,updateQueued,deleteQueued,+ steerQueued,moveQueued,reorderQueued,} = useChatQueue(agentId, sessionId, setError);@@ -272,6 +276,7 @@ export function useMessages(clearInterruptTimer();currentReplyRef.current = null;setPhase('idle');+ setActiveReplyId(null);setError(failure);toast.error(failure.message);} else if (custom.name === 'chat_input_cancelled') {@@ -281,7 +286,15 @@ export function useMessages(clearInterruptTimer();currentReplyRef.current = null;setPhase('idle');+ setActiveReplyId(null);toast.info(message);+ } else if (custom.name === 'chat_input_injected') {+ const value = custom.value as ChatInputTerminalValue;+ finishItem(value);+ toast.success(t('chatQueue.injected'));+ } else if (custom.name === 'chat_input_steer_failed') {+ const value = custom.value as ChatInputTerminalValue;+ toast.error(value.message ?? t('chatQueue.steerFailed'));}return;}@@ -307,6 +320,7 @@ export function useMessages(msgsRef.current = [...msgsRef.current, msg];currentReplyRef.current = msg;}+ setActiveReplyId(e.reply_id);clearInterruptTimer();setPhase('streaming');} else {@@ -334,6 +348,14 @@ export function useMessages(currentReplyRef.current = updated;}}+ if (+ event.type === EventType.REQUIRE_USER_CONFIRM ||+ event.type === EventType.REQUIRE_EXTERNAL_EXECUTION+ ) {+ setActiveReplyId((active) =>+ !event.reply_id || active === event.reply_id ? null : active,+ );+ }if (event.type === EventType.REPLY_END &&(!event.reply_id ||@@ -342,6 +364,7 @@ export function useMessages() {clearInterruptTimer();setPhase('idle');+ setActiveReplyId(null);currentReplyRef.current = null;}}@@ -393,6 +416,7 @@ export function useMessages(setError(null);clearInterruptTimer();setPhase('idle');+ setActiveReplyId(null);setSubagentHitl([]);audioManager?.disposeAll();@@ -425,9 +449,13 @@ export function useMessages(// while parked leaves the UI stuck on ``idle`` with no// way to abort.const tail = messages[messages.length - 1];- if (is_running || hasPendingToolCall(tail)) {+ const pendingToolCall = hasPendingToolCall(tail);+ if (is_running || pendingToolCall) {setPhase('streaming');- if (hasPendingToolCall(tail)) {+ if (is_running && !pendingToolCall && tail?.role === 'assistant') {+ setActiveReplyId(tail.id);+ }+ if (pendingToolCall) {// Prime the ref so continuation events (which// arrive without a fresh REPLY_START) apply to// the right msg.@@ -712,6 +740,8 @@ export function useMessages(reorderQueued,phase: ownsConversation ? phase : ('idle' as ReplyPhase),error: ownsConversation ? error : null,+ activeReplyId: ownsConversation && phase === 'streaming' ? activeReplyId : null,+ steerQueued,send,onUserConfirm,onSubagentConfirm,diff --git a/examples/web_ui/frontend/src/i18n/locales/en.json b/examples/web_ui/frontend/src/i18n/locales/en.jsonindex cd7e7ce6a..0bdc57bc1 100644--- a/examples/web_ui/frontend/src/i18n/locales/en.json+++ b/examples/web_ui/frontend/src/i18n/locales/en.json@@ -115,8 +115,15 @@"moveDown": "Move down","edit": "Edit","delete": "Delete",+ "steer": "Steer current reply","save": "Save","cancel": "Cancel",+ "stateQueued": "Queued",+ "stateSteering": "Steering",+ "stateSteered": "Steered",+ "stateFailed": "Failed",+ "injected": "The queued message was injected into the current reply.",+ "steerFailed": "The queued message could not steer the current reply.","processFailed": "The queued message could not be processed.","processingCancelled": "Queued message processing was interrupted."},diff --git a/examples/web_ui/frontend/src/i18n/locales/zh.json b/examples/web_ui/frontend/src/i18n/locales/zh.jsonindex 6d25c0263..a0625bff3 100644--- a/examples/web_ui/frontend/src/i18n/locales/zh.json+++ b/examples/web_ui/frontend/src/i18n/locales/zh.json@@ -115,8 +115,15 @@"moveDown": "下移","edit": "编辑","delete": "删除",+ "steer": "引导当前回复","save": "保存","cancel": "取消",+ "stateQueued": "排队中",+ "stateSteering": "引导中",+ "stateSteered": "已引导",+ "stateFailed": "失败",+ "injected": "排队消息已注入当前回复。",+ "steerFailed": "排队消息未能引导当前回复。","processFailed": "排队消息处理失败。","processingCancelled": "排队消息处理已中断。"},diff --git a/examples/web_ui/frontend/src/pages/chat/ChatViewport.tsx b/examples/web_ui/frontend/src/pages/chat/ChatViewport.tsxindex 0ae50a4ee..ecf0738ca 100644--- a/examples/web_ui/frontend/src/pages/chat/ChatViewport.tsx+++ b/examples/web_ui/frontend/src/pages/chat/ChatViewport.tsx@@ -264,12 +264,14 @@ export function ChatViewport({ agentId, sessionId, onSessionsChanged }: ChatViewmsgs,loading: messagesLoading,phase,+ activeReplyId,queuedCount,queuedItems,queueReorderDisabled,send,updateQueued,deleteQueued,+ steerQueued,moveQueued,reorderQueued,onUserConfirm,@@ -924,6 +926,7 @@ export function ChatViewport({ agentId, sessionId, onSessionsChanged }: ChatViewgit={workspaceStatus?.git ?? null}onRefreshGit={refetchWorkspaceStatus}phase={phase}+ activeReplyId={activeReplyId}queuedCount={queuedCount}queuedItems={queuedItems}queueReorderDisabled={queueReorderDisabled}@@ -933,6 +936,7 @@ export function ChatViewport({ agentId, sessionId, onSessionsChanged }: ChatViewonInterrupt={interrupt}onUpdateQueued={updateQueued}onDeleteQueued={deleteQueued}+ onSteerQueued={steerQueued}onMoveQueued={moveQueued}onReorderQueued={reorderQueued}voiceState={realtimeVoice.state}diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.pyindex fc8f8f4ab..e2f946f63 100644--- a/src/agentscope/agent/_agent.py+++ b/src/agentscope/agent/_agent.py@@ -9,6 +9,7 @@ import warningsfrom asyncio import Queuefrom copy import deepcopy+from contextlib import aclosingfrom fnmatch import fnmatchfrom datetime import datetimefrom typing import (@@ -322,13 +323,13 @@ class Agent:agent won't re-send the requiring events for the unconfirmedor unexecuted tool calls."""- async for chunk in self._reply(- inputs=inputs,- structured_schema=structured_schema,- ):- if isinstance(chunk, Msg) and not yield_final_msg:- continue- yield chunk+ async with aclosing(+ self._reply(inputs=inputs, structured_schema=structured_schema),+ ) as stream:+ async for chunk in stream:+ if isinstance(chunk, Msg) and not yield_final_msg:+ continue+ yield chunkasync def reply(self,@@ -930,11 +931,14 @@ class Agent:structured_schema: Type[BaseModel] | None = structured_schema,) -> AsyncGenerator[AgentEvent | Msg, None]:if index >= len(self._reply_middlewares):- async for item in self._reply_impl(- inputs=inputs,- structured_schema=structured_schema,- ):- yield item+ async with aclosing(+ self._reply_impl(+ inputs=inputs,+ structured_schema=structured_schema,+ ),+ ) as stream:+ async for item in stream:+ yield itemelse:mw = self._reply_middlewares[index]input_kwargs = {@@ -945,28 +949,34 @@ class Agent:async def next_handler(**kwargs: Any,) -> AsyncGenerator[AgentEvent | Msg, None]:- async for item in execute_chain(- index + 1,- **{**input_kwargs, **kwargs},- ):+ async with aclosing(+ execute_chain(+ index + 1,+ **{**input_kwargs, **kwargs},+ ),+ ) as stream:+ async for item in stream:+ yield item++ async with aclosing(+ mw.on_reply(+ agent=self,+ input_kwargs=input_kwargs,+ next_handler=next_handler,+ ),+ ) as stream:+ async for item in stream:yield item- async for item in mw.on_reply(- agent=self,- input_kwargs=input_kwargs,- next_handler=next_handler,- ):- yield item-agen = execute_chain()self._receive_reply_end = False- async for item in agen:- # Set before the yield: the suspended `_reply_impl` checks the- # flag once resumed by the next pull- if isinstance(item, ReplyEndEvent):- self._receive_reply_end = True- yield item+ async with aclosing(agen):+ async for item in agen:+ # Set before yielding so the suspended loop can observe it.+ if isinstance(item, ReplyEndEvent):+ self._receive_reply_end = True+ yield itemasync def _close_unfinished_tool_calls(self,@@ -1096,6 +1106,10 @@ class Agent:# - if incoming event and agent is waiting for an event# - if event is None and agent is not waiting for an event# ===================================================================+ if event is not None:+ # Receive cancellation redirected by the service before a+ # continuation can apply a decision or execute a tool.+ await asyncio.sleep(0)is_awaiting = await self._check_incoming_event(event)# ===================================================================@@ -1121,6 +1135,10 @@ class Agent:reply_id=self.state.reply_id,name=self.name,)+ # A consumer may re-arm cancellation while registering or+ # publishing REPLY_START. Receive it inside this cleanup scope+ # even when subsequent model/tool awaits complete inline.+ await asyncio.sleep(0)# Update the structured output tool for new requirements or# from the previous replydiff --git a/src/agentscope/app/_bus_ops.py b/src/agentscope/app/_bus_ops.pyindex 57eeea681..00b364bf6 100644--- a/src/agentscope/app/_bus_ops.py+++ b/src/agentscope/app/_bus_ops.py@@ -59,6 +59,10 @@ class ChatQueueBusyError(RuntimeError):"""Raised when a short queue mutation lock cannot be acquired."""+class ChatSteeringUnavailableError(RuntimeError):+ """Raised when a queued turn cannot steer the requested active reply."""++@asynccontextmanagerasync def chat_input_mutation(bus: "MessageBus",@@ -359,6 +363,7 @@ async def enqueue_chat_input("agent_id": agent_id,"created_at": datetime.now(timezone.utc).isoformat(),"input": serialized,+ "state": "queued",}async with _chat_input_user_quota(bus, user_id):if (@@ -451,6 +456,310 @@ async def list_chat_inputs(return [_public_chat_input(payload) for payload in payloads]+async def register_active_chat_reply(+ bus: "MessageBus",+ session_id: str,+ reply_id: str,+) -> None:+ """Register the reply currently holding a session's run lock.++ Internal lifecycle writes wait for the mutation lock instead of using the+ bounded foreground timeout. The registry entry is the authoritative target+ checked by the public Steer endpoint.++ Args:+ bus (`MessageBus`):+ Application message bus.+ session_id (`str`):+ Session whose reply started or resumed.+ reply_id (`str`):+ Active reply identifier.+ """+ async with bus.acquire_lock(+ MessageBusKeys.chat_input_mutation_lock(session_id),+ ttl_secs=MessageBusKeys.CHAT_INPUT_MUTATION_TTL_SECS,+ ):+ await bus.registry_set(+ MessageBusKeys.chat_active_reply_registry(),+ session_id,+ reply_id,+ )+++async def steer_chat_input(+ bus: "MessageBus",+ user_id: str,+ session_id: str,+ agent_id: str,+ item_id: str,+ reply_id: str,+) -> list[dict]:+ """Reserve one pending queue item for the requested active reply.++ The item stays in the durable FIFO until middleware acknowledges actual+ context injection. Repeating the same request is idempotent.++ Args:+ bus (`MessageBus`):+ Application message bus.+ user_id (`str`):+ User that must own the pending item.+ session_id (`str`):+ Session that owns the queue and active reply.+ agent_id (`str`):+ Agent that must own the pending item.+ item_id (`str`):+ Pending queue item to steer with.+ reply_id (`str`):+ Reply observed as active by the client.++ Returns:+ `list[dict]`:+ Complete public queue snapshot after reservation.++ Raises:+ `LookupError`:+ The item is no longer pending.+ `ChatSteeringUnavailableError`:+ The reply is stale, idle, or the item targets another reply.+ `ChatQueueBusyError`:+ The foreground mutation lock cannot be acquired promptly.+ """+ async with chat_input_mutation(bus, session_id):+ active_replies = await bus.registry_getall(+ MessageBusKeys.chat_active_reply_registry(),+ )+ active_reply_id = active_replies.get(session_id)+ is_running = await bus.is_locked(+ MessageBusKeys.session_lock(session_id),+ )+ if not is_running or active_reply_id != reply_id:+ raise ChatSteeringUnavailableError(+ f"Reply '{reply_id}' is no longer active.",+ )++ payloads = await _read_chat_input_payloads(bus, session_id)+ item = _owned_chat_input(+ payloads,+ user_id,+ session_id,+ agent_id,+ item_id,+ )+ item_state = item.get("state", "queued")+ target_reply_id = item.get("target_reply_id")+ if item_state == "steering":+ if target_reply_id != reply_id:+ raise ChatSteeringUnavailableError(+ f"Queued message '{item_id}' is steering another reply.",+ )+ return [_public_chat_input(payload) for payload in payloads]+ if item_state not in ("queued", "failed"):+ raise ChatSteeringUnavailableError(+ f"Queued message '{item_id}' cannot be steered now.",+ )++ item["state"] = "steering"+ item["target_reply_id"] = reply_id+ item.pop("error", None)+ await bus.queue_replace(+ MessageBusKeys.chat_inputs(session_id),+ [queue_entry(payload) for payload in payloads],+ )+ return await _notify_chat_queue_changed(bus, session_id, payloads)+++async def list_steering_chat_inputs(+ bus: "MessageBus",+ session_id: str,+ reply_id: str,+) -> list[dict]:+ """Read items reserved for one reply without removing them.++ Args:+ bus (`MessageBus`):+ Application message bus.+ session_id (`str`):+ Session whose queue should be inspected.+ reply_id (`str`):+ Active reply that must own the steering reservation.++ Returns:+ `list[dict]`:+ Public copies of matching items in FIFO order.+ """+ async with bus.acquire_lock(+ MessageBusKeys.chat_input_mutation_lock(session_id),+ ttl_secs=MessageBusKeys.CHAT_INPUT_MUTATION_TTL_SECS,+ ):+ payloads = await _read_chat_input_payloads(bus, session_id)+ return [+ _public_chat_input(payload)+ for payload in payloads+ if payload.get("state", "queued") == "steering"+ and payload.get("target_reply_id") == reply_id+ ]+++async def acknowledge_steering_chat_inputs(+ bus: "MessageBus",+ session_id: str,+ reply_id: str,+ item_ids: list[str],+) -> list[dict]:+ """Remove steering items after they were appended to agent context.++ Args:+ bus (`MessageBus`):+ Application message bus.+ session_id (`str`):+ Session whose FIFO contains the items.+ reply_id (`str`):+ Reply that consumed the items.+ item_ids (`list[str]`):+ Exact queue item ids to acknowledge.++ Returns:+ `list[dict]`:+ Public copies of the removed items.++ Raises:+ `LookupError`:+ Any requested item is no longer reserved for this reply.+ """+ requested_ids = set(item_ids)+ async with bus.acquire_lock(+ MessageBusKeys.chat_input_mutation_lock(session_id),+ ttl_secs=MessageBusKeys.CHAT_INPUT_MUTATION_TTL_SECS,+ ):+ active_replies = await bus.registry_getall(+ MessageBusKeys.chat_active_reply_registry(),+ )+ if active_replies.get(session_id) != reply_id:+ raise LookupError(+ f"Reply '{reply_id}' is no longer active.",+ )+ payloads = await _read_chat_input_payloads(bus, session_id)+ removed = [+ payload+ for payload in payloads+ if payload.get("id") in requested_ids+ and payload.get("state", "queued") == "steering"+ and payload.get("target_reply_id") == reply_id+ ]+ if {payload.get("id") for payload in removed} != requested_ids:+ raise LookupError(+ "One or more steering messages are no longer pending.",+ )+ remaining = [payload for payload in payloads if payload not in removed]+ await bus.queue_replace(+ MessageBusKeys.chat_inputs(session_id),+ [queue_entry(payload) for payload in remaining],+ )+ for payload in removed:+ await discard_input(bus, payload)+ await _notify_chat_queue_changed(bus, session_id, remaining)+ return [_public_chat_input(payload) for payload in removed]+++async def fail_steering_chat_input(+ bus: "MessageBus",+ session_id: str,+ reply_id: str,+ item_id: str,+ error: str,+) -> None:+ """Keep a failed steering item in the FIFO with a visible error.++ Args:+ bus (`MessageBus`):+ Application message bus.+ session_id (`str`):+ Session whose queue owns the item.+ reply_id (`str`):+ Reply the item attempted to steer.+ item_id (`str`):+ Failed queue item id.+ error (`str`):+ User-facing failure description.+ """+ async with bus.acquire_lock(+ MessageBusKeys.chat_input_mutation_lock(session_id),+ ttl_secs=MessageBusKeys.CHAT_INPUT_MUTATION_TTL_SECS,+ ):+ payloads = await _read_chat_input_payloads(bus, session_id)+ changed = False+ for payload in payloads:+ if (+ payload.get("id") == item_id+ and payload.get("state", "queued") == "steering"+ and payload.get("target_reply_id") == reply_id+ ):+ payload["state"] = "failed"+ payload["error"] = error+ payload.pop("target_reply_id", None)+ changed = True+ break+ if changed:+ await bus.queue_replace(+ MessageBusKeys.chat_inputs(session_id),+ [queue_entry(payload) for payload in payloads],+ )+ await _notify_chat_queue_changed(bus, session_id, payloads)+++async def finish_active_chat_reply(+ bus: "MessageBus",+ session_id: str,+ reply_id: str,+) -> list[str]:+ """Clear an active reply and restore its unconsumed steering items.++ Args:+ bus (`MessageBus`):+ Application message bus.+ session_id (`str`):+ Session whose run is finishing.+ reply_id (`str`):+ Reply whose active registry entry should be cleared.++ Returns:+ `list[str]`:+ Queue item ids restored to deferred-send state.+ """+ async with bus.acquire_lock(+ MessageBusKeys.chat_input_mutation_lock(session_id),+ ttl_secs=MessageBusKeys.CHAT_INPUT_MUTATION_TTL_SECS,+ ):+ active_replies = await bus.registry_getall(+ MessageBusKeys.chat_active_reply_registry(),+ )+ if active_replies.get(session_id) != reply_id:+ return []+ await bus.registry_del(+ MessageBusKeys.chat_active_reply_registry(),+ session_id,+ )+ payloads = await _read_chat_input_payloads(bus, session_id)+ restored_ids: list[str] = []+ for payload in payloads:+ if (+ payload.get("state", "queued") == "steering"+ and payload.get("target_reply_id") == reply_id+ ):+ payload["state"] = "queued"+ payload.pop("target_reply_id", None)+ payload.pop("error", None)+ restored_ids.append(payload["id"])+ if restored_ids:+ await bus.queue_replace(+ MessageBusKeys.chat_inputs(session_id),+ [queue_entry(payload) for payload in payloads],+ )+ await _notify_chat_queue_changed(bus, session_id, payloads)+ return restored_ids++async def update_chat_input(bus: "MessageBus",user_id: str,@@ -497,8 +806,15 @@ async def update_chat_input(agent_id,item_id,)+ if item.get("state", "queued") == "steering":+ raise LookupError(+ f"Queued message '{item_id}' is currently steering.",+ )previous = dict(item)item["input"] = serialized+ item["state"] = "queued"+ item.pop("target_reply_id", None)+ item.pop("error", None)item["input_ref"] = uuid.uuid4().hexawait bus.registry_set(MessageBusKeys.chat_input_payloads(session_id),@@ -553,6 +869,10 @@ async def delete_chat_input(agent_id,item_id,)+ if item.get("state", "queued") == "steering":+ raise LookupError(+ f"Queued message '{item_id}' is currently steering.",+ )payloads.remove(item)await bus.queue_replace(MessageBusKeys.chat_inputs(session_id),@@ -600,6 +920,13 @@ async def reorder_chat_inputs("""async with chat_input_mutation(bus, session_id):payloads = await _read_chat_input_payloads(bus, session_id)+ if any(+ payload.get("state", "queued") == "steering"+ for payload in payloads+ ):+ raise ValueError(+ "The queue cannot be reordered while a message is steering.",+ )owned = [payloadfor payload in payloads@@ -814,6 +1141,8 @@ def _public_chat_input(payload: dict) -> dict:"id": payload["id"],"created_at": payload["created_at"],"input": payload["input"],+ "state": payload.get("state", "queued"),+ "error": payload.get("error"),}diff --git a/src/agentscope/app/_router/_chat.py b/src/agentscope/app/_router/_chat.pyindex e3ba14d11..639db387f 100644--- a/src/agentscope/app/_router/_chat.py+++ b/src/agentscope/app/_router/_chat.py@@ -35,6 +35,7 @@ from ._schema import (ChatRequest,ChatTriggerResponse,ReorderChatQueueRequest,+ SteerChatQueueItemRequest,UpdateChatQueueItemRequest,)from .._manager import ChatRunRegistry@@ -48,11 +49,13 @@ from ..storage import StorageBasefrom .._bus_ops import (ChatQueueBusyError,ChatQueueFullError,+ ChatSteeringUnavailableError,delete_chat_input,enqueue_chat_input,enqueue_run_trigger,list_chat_inputs,reorder_chat_inputs,+ steer_chat_input,update_chat_input,)from ...event import UserConfirmResultEvent, ExternalExecutionResultEvent@@ -200,6 +203,72 @@ async def reorder_chat_queue(return ChatQueueResponse(items=items)+@chat_router.post(+ "/queue/{item_id}/steer",+ response_model=ChatQueueResponse,+ summary="Steer an active reply with one pending user turn",+)+async def steer_chat_queue_item(+ item_id: Annotated[+ str,+ Path(description="Stable id of the pending item to inject."),+ ],+ request: SteerChatQueueItemRequest,+ user_id: str = Depends(get_current_user_id),+ storage: StorageBase = Depends(get_storage),+ message_bus: MessageBus = Depends(get_message_bus),+) -> ChatQueueResponse:+ """Reserve a pending item for non-interrupting reply steering.++ Args:+ item_id (`str`):+ Stable id of the pending item to inject.+ request (`SteerChatQueueItemRequest`):+ Target session, agent, and active reply id.+ user_id (`str`):+ Injected authenticated user id.+ storage (`StorageBase`):+ Injected persistent session storage.+ message_bus (`MessageBus`):+ Injected message bus containing queue and active-reply state.++ Returns:+ `ChatQueueResponse`:+ Complete queue snapshot with the selected item steering.++ Raises:+ `HTTPException`:+ HTTP 404 for a missing session, HTTP 409 for a stale reply or+ started item, or HTTP 503 when the queue is busy.+ """+ await _ensure_session(+ storage,+ user_id,+ request.agent_id,+ request.session_id,+ )+ try:+ items = await steer_chat_input(+ message_bus,+ user_id,+ request.session_id,+ request.agent_id,+ item_id,+ request.reply_id,+ )+ except (LookupError, ChatSteeringUnavailableError) as exc:+ raise HTTPException(+ status_code=status.HTTP_409_CONFLICT,+ detail=str(exc),+ ) from exc+ except ChatQueueBusyError as exc:+ raise HTTPException(+ status_code=status.HTTP_503_SERVICE_UNAVAILABLE,+ detail=str(exc),+ ) from exc+ return ChatQueueResponse(items=items)++@chat_router.patch("/queue/{item_id}",response_model=ChatQueueResponse,diff --git a/src/agentscope/app/_router/_schema/__init__.py b/src/agentscope/app/_router/_schema/__init__.pyindex 8b02b8720..1ceb3e62b 100644--- a/src/agentscope/app/_router/_schema/__init__.py+++ b/src/agentscope/app/_router/_schema/__init__.py@@ -17,6 +17,7 @@ from ._chat import (ChatQueueItem,ChatQueueResponse,ReorderChatQueueRequest,+ SteerChatQueueItemRequest,UpdateChatQueueItemRequest,)from ._health import ComponentStatus, HealthResponse@@ -176,6 +177,7 @@ __all__ = ["ChatQueueItem","ChatQueueResponse","ReorderChatQueueRequest",+ "SteerChatQueueItemRequest","UpdateChatQueueItemRequest",# Credential"CreateCredentialRequest",diff --git a/src/agentscope/app/_router/_schema/_chat.py b/src/agentscope/app/_router/_schema/_chat.pyindex b43cd7bda..dd705058d 100644--- a/src/agentscope/app/_router/_schema/_chat.py+++ b/src/agentscope/app/_router/_schema/_chat.py@@ -69,6 +69,14 @@ class ChatQueueItem(BaseModel):input: Msg | NonEmptyMsgList = Field(description="One message or non-empty ordered message list.",)+ state: Literal["queued", "steering", "failed"] = Field(+ default="queued",+ description="Current deferred-send or steering state.",+ )+ error: str | None = Field(+ default=None,+ description="Visible steering failure, when state is failed.",+ )class ChatQueueResponse(BaseModel):@@ -93,6 +101,20 @@ class UpdateChatQueueItemRequest(BaseModel):)+class SteerChatQueueItemRequest(BaseModel):+ """Reserve one pending input for a currently active reply."""++ agent_id: str = Field(+ description="Agent that owns the target session.",+ )+ session_id: str = Field(+ description="Session whose pending item will steer the reply.",+ )+ reply_id: str = Field(+ description="Active reply that should consume the pending item.",+ )++class ReorderChatQueueRequest(BaseModel):"""Set the complete pending queue order."""diff --git a/src/agentscope/app/_service/_chat.py b/src/agentscope/app/_service/_chat.pyindex 5c7c6ab60..2c82b87df 100644--- a/src/agentscope/app/_service/_chat.py+++ b/src/agentscope/app/_service/_chat.py@@ -24,8 +24,10 @@ from .._bus_ops import (abandon_inbox_consumer,deliver_to_inbox,enqueue_run_trigger,+ finish_active_chat_reply,has_pending_inbox_or_release,publish_session_event,+ register_active_chat_reply,register_inbox_consumer,)from ..message_bus import MessageBus, MessageBusKeys@@ -44,6 +46,7 @@ from .._manager import BackgroundTaskManager, SchedulerManagerfrom ..workspace_manager import WorkspaceManagerBasefrom ..middleware import (InboxMiddleware,+ SteeringMiddleware,SOPStepSubmitMiddleware,StateChangeMiddleware,ToolOffloadMiddleware,@@ -1085,6 +1088,7 @@ class ChatService:# in-process retrigger plumbing is needed here.# -------------------------------------------------------------middlewares: list = [+ SteeringMiddleware(self._message_bus),InboxMiddleware(self._message_bus),StateChangeMiddleware(message_bus=self._message_bus,@@ -1341,6 +1345,7 @@ class ChatService:agent_id=agent_id,)reply_msg: Msg | None = None+ active_reply_id: str | None = Nonereply_msgs: list[Msg] = []checkpoint_cursor: str | None = Nonereleased = False@@ -1399,6 +1404,23 @@ class ChatService:elif reply_msg is not None:reply_msg.append_event(event)try:+ if isinstance(event, ReplyStartEvent):+ if (+ active_reply_id is not None+ and active_reply_id+ != event.reply_id+ ):+ await finish_active_chat_reply(+ self._message_bus,+ session_id,+ active_reply_id,+ )+ active_reply_id = event.reply_id+ await register_active_chat_reply(+ self._message_bus,+ session_id,+ event.reply_id,+ )checkpoint_cursor = (await publish_session_event(self._message_bus,@@ -1427,6 +1449,7 @@ class ChatService:else:# Case B: continuation (UserConfirmResult# / ExternalExecResult)+ continuation_reply_id = agent.state.reply_idreply_msg = await self._storage.get_message(user_id,session_id,@@ -1445,44 +1468,69 @@ class ChatService:elif input_msg:reply_msg.append_event(input_msg)- # Broadcast the applied decision so- # observers that didn't make it (other tabs,- # the channel card) close it.- if isinstance(- input_msg,- (- UserConfirmResultEvent,- ExternalExecutionResultEvent,- ),- ):+ try:+ if (+ active_reply_id is not None+ and active_reply_id+ != continuation_reply_id+ ):+ await finish_active_chat_reply(+ self._message_bus,+ session_id,+ active_reply_id,+ )+ active_reply_id = continuation_reply_id+ await register_active_chat_reply(+ self._message_bus,+ session_id,+ continuation_reply_id,+ )+ # Broadcast the applied decision so+ # observers that didn't make it (other tabs,+ # the channel card) close it.+ if isinstance(+ input_msg,+ (+ UserConfirmResultEvent,+ ExternalExecutionResultEvent,+ ),+ ):+ checkpoint_cursor = (+ await publish_session_event(+ self._message_bus,+ session_id,+ input_msg.model_dump(mode="json"),+ )+ )++ # Emit a synthetic REPLY_START so SSE clients+ # can detect the continuation.+ #+ # IMPORTANT: The frontend SSE handler must+ # NOT clear its accumulated message buffer+ # upon receiving REPLY_START with the current+ # reply_id. This signals a continuation (e.g.+ # after an approval flow), not a fresh reply.+ continuation_start = ReplyStartEvent(+ session_id=session_id,+ reply_id=continuation_reply_id,+ name=agent_record.data.name,+ )checkpoint_cursor = (await publish_session_event(self._message_bus,session_id,- input_msg.model_dump(mode="json"),+ continuation_start.model_dump(+ mode="json",+ ),))-- # Emit a synthetic REPLY_START so SSE subscribers- # (frontend, channel gateway) can detect the- # continuation without requiring special handling.- #- # IMPORTANT: The frontend SSE handler must- # NOT clear its accumulated message buffer- # upon receiving a- # REPLY_START with the same reply_id as the current- # message. This event signals a continuation (e.g.- # after an approval flow), not a fresh reply.- continuation_start = ReplyStartEvent(- session_id=session_id,- reply_id=agent.state.reply_id,- name=agent_record.data.name,- )- checkpoint_cursor = await publish_session_event(- self._message_bus,- session_id,- continuation_start.model_dump(mode="json"),- )+ except asyncio.CancelledError:+ # Resume the Agent so it closes pending tools+ # and emits the interrupted terminal event.+ current = asyncio.current_task()+ if current is not None:+ current.cancel()async for event in agent.reply_stream(inputs=input_msg,@@ -1631,30 +1679,38 @@ class ChatService:before_id=checkpoint_cursor,)finally:- # A worker whose turn died never reached- # ``TeamSay``. Sent from inside the shielded- # write so an interrupt cannot drop it, and from- # a ``finally`` so a storage failure cannot- # either — the leader has to learn about the- # dead turn even when recording it went wrong.- # COMPLETED / EXCEED_MAX_ITERS stay silent:- # those only escape the member middleware after- # a successful report.- for msg in reply_msgs:- if msg.finished_reason in (- ReplyFinishedReason.ERROR,- ReplyFinishedReason.INTERRUPTED,- ):- await self._notify_leader_of_failure(- user_id,- team_ctx,- worker_name,- msg.finished_reason,- msg.error.message- if msg.error- else "The turn stopped before it "- "finished.",+ try:+ if active_reply_id is not None:+ await finish_active_chat_reply(+ self._message_bus,+ session_id,+ active_reply_id,)+ finally:+ # A worker whose turn died never reached+ # ``TeamSay``. Sent from inside the shielded+ # write so an interrupt cannot drop it, and from+ # a ``finally`` so a storage failure cannot+ # either — the leader has to learn about the+ # dead turn even when recording it went wrong.+ # COMPLETED / EXCEED_MAX_ITERS stay silent:+ # those only escape the member middleware after+ # a successful report.+ for msg in reply_msgs:+ if msg.finished_reason in (+ ReplyFinishedReason.ERROR,+ ReplyFinishedReason.INTERRUPTED,+ ):+ await self._notify_leader_of_failure(+ user_id,+ team_ctx,+ worker_name,+ msg.finished_reason,+ msg.error.message+ if msg.error+ else "The turn stopped before it "+ "finished.",+ )persist_task = asyncio.create_task(_persist())try:diff --git a/src/agentscope/app/_service/_session.py b/src/agentscope/app/_service/_session.pyindex 8c8c0b1e4..867f8fbe4 100644--- a/src/agentscope/app/_service/_session.py+++ b/src/agentscope/app/_service/_session.py@@ -667,6 +667,10 @@ class SessionService:await self._bus.queue_delete(MessageBusKeys.chat_inputs(session_id),)+ await self._bus.registry_del(+ MessageBusKeys.chat_active_reply_registry(),+ session_id,+ )await self._bus.registry_del(MessageBusKeys.chat_input_inflight_registry(),session_id,diff --git a/src/agentscope/app/message_bus/_base.py b/src/agentscope/app/message_bus/_base.pyindex 8589df38f..a943d46b5 100644--- a/src/agentscope/app/message_bus/_base.py+++ b/src/agentscope/app/message_bus/_base.py@@ -817,6 +817,10 @@ class MessageBus(ABC): # pylint: disable=too-many-public-methodsMessageBusKeys.chat_input_inflight_registry(),session_id,)+ await self.registry_del(+ MessageBusKeys.chat_active_reply_registry(),+ session_id,+ )await self.registry_drop(self._BG_TASKS_KEY.format(sid=session_id))# Inbox -----------------------------------------------------------diff --git a/src/agentscope/app/message_bus/_keys.py b/src/agentscope/app/message_bus/_keys.pyindex e9623fa30..19c57a475 100644--- a/src/agentscope/app/message_bus/_keys.py+++ b/src/agentscope/app/message_bus/_keys.py@@ -263,6 +263,7 @@ class MessageBusKeys: # pylint: disable=too-many-public-methods_CHAT_INPUT_MUTATION_LOCK = "agentscope:chat:inputs:mutation:{sid}"_CHAT_INPUT_PENDING_REGISTRY = "agentscope:chat:pending"_CHAT_INPUT_INFLIGHT_REGISTRY = "agentscope:chat:inflight"+ _CHAT_ACTIVE_REPLY_REGISTRY = "agentscope:chat:active_reply"_CHAT_INPUT_RECOVERY_LOCK = "agentscope:chat:recovery:lock"_CHAT_INPUT_RECOVERY_STATE = "agentscope:chat:recovery:state"_CHAT_INPUT_USER_QUOTA_LOCK = "agentscope:chat:quota:lock:{uid}"@@ -368,6 +369,16 @@ class MessageBusKeys: # pylint: disable=too-many-public-methods"""return cls._CHAT_INPUT_INFLIGHT_REGISTRY+ @classmethod+ def chat_active_reply_registry(cls) -> str:+ """Return the registry containing each session's active reply id.++ Returns:+ `str`:+ Global registry mapping session ids to active reply ids.+ """+ return cls._CHAT_ACTIVE_REPLY_REGISTRY+@classmethoddef chat_input_user_quota_lock(cls, user_id: str) -> str:"""Return the per-user pending-turn quota mutex key.diff --git a/src/agentscope/app/middleware/__init__.py b/src/agentscope/app/middleware/__init__.pyindex 6f058d8f9..4888eaf96 100644--- a/src/agentscope/app/middleware/__init__.py+++ b/src/agentscope/app/middleware/__init__.py@@ -2,6 +2,7 @@"""The middlewares module."""from ._inbox_middleware import InboxMiddleware+from ._steering_middleware import SteeringMiddlewarefrom ._protocol import ProtocolMiddlewareBase, AGUIProtocolMiddlewarefrom ._sop_step_middleware import SOPStepSubmitMiddlewarefrom ._state_change_middleware import StateChangeMiddleware@@ -11,6 +12,7 @@ from ._tool_offload_middleware import ToolOffloadMiddleware__all__ = ["InboxMiddleware",+ "SteeringMiddleware","ProtocolMiddlewareBase","AGUIProtocolMiddleware","SOPStepSubmitMiddleware",diff --git a/src/agentscope/app/middleware/_steering_middleware.py b/src/agentscope/app/middleware/_steering_middleware.pynew file mode 100644index 000000000..4e5ec15d4--- /dev/null+++ b/src/agentscope/app/middleware/_steering_middleware.py@@ -0,0 +1,164 @@+# -*- coding: utf-8 -*-+"""Adapt the durable chat queue to SDK steering middleware."""+from pydantic import TypeAdapter++from .._bus_ops import (+ acknowledge_steering_chat_inputs,+ fail_steering_chat_input,+ list_steering_chat_inputs,+ publish_session_event,+)+from ..message_bus import MessageBus+from ..._logging import logger+from ...event import CustomEvent+from ...message import Msg+from ...middleware import (+ SteeringInput,+ SteeringMiddleware as SDKSteeringMiddleware,+ SteeringSource,+)++_MESSAGE_INPUT_ADAPTER: TypeAdapter = TypeAdapter(Msg | list[Msg])+++class _ChatQueueSteeringSource(SteeringSource):+ """Read reserved inputs; ChatService owns the active-reply lifecycle."""++ def __init__(self, message_bus: MessageBus) -> None:+ """Store the application's durable bus."""+ self._bus = message_bus++ async def read(+ self,+ session_id: str,+ reply_id: str,+ ) -> list[SteeringInput]:+ """Hydrate reserved items, retaining invalid ones as failed."""+ items = await list_steering_chat_inputs(+ self._bus,+ session_id,+ reply_id,+ )+ inputs = []+ for item in items:+ try:+ parsed = _MESSAGE_INPUT_ADAPTER.validate_python(item["input"])+ except ValueError as exc:+ error = f"The queued message could not be injected: {exc}"+ await fail_steering_chat_input(+ self._bus,+ session_id,+ reply_id,+ item["id"],+ error,+ )+ await self._notify(+ session_id,+ "chat_input_steer_failed",+ item["id"],+ self._message_ids(item["input"]),+ error,+ )+ else:+ inputs.append(+ SteeringInput(+ id=item["id"],+ messages=parsed+ if isinstance(parsed, list)+ else [parsed],+ ),+ )+ return inputs++ async def acknowledge(+ self,+ session_id: str,+ reply_id: str,+ inputs: list[SteeringInput],+ ) -> None:+ """Remove injected inputs and publish the existing WebUI events."""+ await acknowledge_steering_chat_inputs(+ self._bus,+ session_id,+ reply_id,+ [item.id for item in inputs],+ )+ for item in inputs:+ await self._notify(+ session_id,+ "chat_input_injected",+ item.id,+ [message.id for message in item.messages],+ )++ async def reject(+ self,+ session_id: str,+ reply_id: str,+ item: SteeringInput,+ error: str,+ ) -> None:+ """Keep unsupported content editable in the durable queue."""+ await fail_steering_chat_input(+ self._bus,+ session_id,+ reply_id,+ item.id,+ error,+ )+ await self._notify(+ session_id,+ "chat_input_steer_failed",+ item.id,+ [message.id for message in item.messages],+ error,+ )++ async def _notify(+ self,+ session_id: str,+ name: str,+ item_id: str,+ message_ids: list[str],+ error: str | None = None,+ ) -> None:+ """Do not roll back a committed injection if notification fails."""+ value: dict = {"queue_item_id": item_id, "message_ids": message_ids}+ if error is not None:+ value["message"] = error+ try:+ await publish_session_event(+ self._bus,+ session_id,+ CustomEvent(name=name, value=value).model_dump(mode="json"),+ )+ except Exception:+ logger.exception(+ "Steering transition committed; notification failed for %s.",+ item_id,+ )++ @staticmethod+ def _message_ids(raw_input: object) -> list[str]:+ """Extract available message ids from a malformed queued input."""+ messages = raw_input if isinstance(raw_input, list) else [raw_input]+ return [+ str(message["id"])+ for message in messages+ if isinstance(message, dict) and message.get("id")+ ]+++class SteeringMiddleware(SDKSteeringMiddleware):+ """Use SDK steering with the application's queue and event protocol.++ Args:+ message_bus: Application message bus holding reserved chat inputs.+ """++ def __init__(self, message_bus: MessageBus) -> None:+ """Preserve the service constructor and WebUI hint source."""+ super().__init__(+ _ChatQueueSteeringSource(message_bus),+ hint_source="chat_input_steering",+ )diff --git a/src/agentscope/middleware/__init__.py b/src/agentscope/middleware/__init__.pyindex e2b7f11b6..6fafae112 100644--- a/src/agentscope/middleware/__init__.py+++ b/src/agentscope/middleware/__init__.py@@ -12,6 +12,13 @@ from ._longterm_memory import (from ._tracing import TracingMiddlewarefrom ._tts_middleware import TTSMiddlewarefrom ._model_router import ChatModelCandidate, ModelRouterMiddleware+from ._steering import SteeringMiddleware+from ._steering_queue import (+ SteeringInput,+ SteeringQueue,+ SteeringReceipt,+ SteeringSource,+)__all__ = ["MiddlewareBase",@@ -24,4 +31,9 @@ __all__ = ["TTSMiddleware","ChatModelCandidate","ModelRouterMiddleware",+ "SteeringInput",+ "SteeringMiddleware",+ "SteeringQueue",+ "SteeringReceipt",+ "SteeringSource",]diff --git a/src/agentscope/middleware/_steering.py b/src/agentscope/middleware/_steering.pynew file mode 100644index 000000000..f0ec49b02--- /dev/null+++ b/src/agentscope/middleware/_steering.py@@ -0,0 +1,264 @@+# -*- coding: utf-8 -*-+"""Inject steering inputs at normal Agent reasoning boundaries."""+import asyncio+from contextlib import aclosing+from typing import Any, AsyncGenerator, Callable, TYPE_CHECKING++from ._base import MiddlewareBase+from ._steering_queue import SteeringInput, SteeringSource+from ..event import (+ ExternalExecutionResultEvent,+ HintBlockEvent,+ ReplyStartEvent,+ UserConfirmResultEvent,+)+from ..message import AssistantMsg, DataBlock, HintBlock, Msg, TextBlock++if TYPE_CHECKING:+ from ..agent import Agent+++class SteeringMiddleware(MiddlewareBase):+ """Guide active replies without interrupting model or tool calls.++ Args:+ source: Reply-scoped source of pending steering inputs.+ hint_source: Source label attached to injected hint blocks.++ The source is checked before reasoning and after a text-only response.+ A new input can suppress that response's final candidate; the Agent then+ performs another normal iteration, including compression and budgeting.+ Inputs received during tools wait until the next reasoning call.+ """++ def __init__(+ self,+ source: SteeringSource,+ *,+ hint_source: str = "steering",+ ) -> None:+ """Store the input source and the hint event label."""+ self._source = source+ self._hint_source = hint_source++ async def on_reply(+ self,+ agent: "Agent",+ input_kwargs: dict,+ next_handler: Callable[..., AsyncGenerator],+ ) -> AsyncGenerator[Any, None]:+ """Open and close input windows across reply and resume lifecycles."""+ session_id = agent.state.session_id+ active_reply_id: str | None = None+ try:+ if isinstance(+ input_kwargs.get("inputs"),+ (UserConfirmResultEvent, ExternalExecutionResultEvent),+ ):+ await self._source.start_reply(+ session_id,+ agent.state.reply_id,+ )+ active_reply_id = agent.state.reply_id+ async with aclosing(next_handler(**input_kwargs)) as stream:+ async for event in stream:+ if isinstance(event, ReplyStartEvent):+ if active_reply_id is not None:+ await self._source.finish_reply(+ session_id,+ active_reply_id,+ )+ await self._source.start_reply(+ session_id,+ event.reply_id,+ )+ active_reply_id = event.reply_id+ yield event+ finally:+ # Another middleware may swallow ReplyEndEvent to continue.+ # Close when the invocation actually exits, not at that event.+ if active_reply_id is not None:+ await self._source.finish_reply(session_id, active_reply_id)++ async def on_reasoning(+ self,+ agent: "Agent",+ input_kwargs: dict,+ next_handler: Callable[..., AsyncGenerator],+ ) -> AsyncGenerator[Any, None]:+ """Run one model call, yielding continuation control to the Agent."""+ consumed = False+ async for event in self._consume(agent):+ consumed = True+ yield event+ if consumed:+ # The Agent checked context before entering reasoning. Include+ # newly injected text and attachments before calling the model.+ await agent.compress_context()++ terminal_messages: list[Msg] = []+ async for event in next_handler(**input_kwargs):+ if isinstance(event, Msg):+ terminal_messages.append(event)+ else:+ yield event++ # The forced finalization call must still be allowed to terminate.+ # Its late inputs stay pending and become unconsumed at reply end.+ if (+ terminal_messages+ and agent.state.cur_iter < agent.react_config.max_iters+ ):+ consumed = False+ async for event in self._consume(agent):+ consumed = True+ yield event+ if consumed:+ return++ for message in terminal_messages:+ yield message++ async def _consume(+ self,+ agent: "Agent",+ ) -> AsyncGenerator[HintBlockEvent, None]:+ """Validate inputs and acknowledge only a successful context append."""+ session_id = agent.state.session_id+ reply_id = agent.state.reply_id+ items = await self._source.read(session_id, reply_id)+ prepared: list[SteeringInput] = []+ hints: list[HintBlock] = []+ for item in items:+ try:+ item_hints = self._to_hints(item.id, item.messages)+ except ValueError as exc:+ await self._source.reject(+ session_id,+ reply_id,+ item,+ f"The steering input could not be injected: {exc}",+ )+ else:+ prepared.append(item)+ hints.extend(item_hints)+ if not prepared:+ return++ rollback = self._append_hints(agent, hints)+ acknowledgement = asyncio.create_task(+ self._source.acknowledge(session_id, reply_id, prepared),+ )+ cancellation: asyncio.CancelledError | None = None+ # Cancellation is not evidence that acknowledgement failed: the+ # source may already have removed the inputs. Resolve its outcome+ # before either rolling back or allowing reply persistence to run.+ while not acknowledgement.done():+ try:+ await asyncio.shield(acknowledgement)+ except asyncio.CancelledError as exc:+ if cancellation is None:+ cancellation = exc+ except Exception:+ break+ try:+ acknowledgement.result()+ except BaseException as exc:+ rollback()+ if cancellation is not None:+ raise cancellation from exc+ raise+ # Project every committed hint before propagating cancellation. The+ # service persists replies built from events, not the agent context.+ for hint in hints:+ yield HintBlockEvent(+ reply_id=reply_id,+ block_id=hint.id,+ source=hint.source,+ hint=hint.hint,+ )+ # Receive any further cancellation redirected by the event consumer+ # before the Agent leaves reasoning and starts interruption cleanup.+ try:+ await asyncio.sleep(0)+ except asyncio.CancelledError as exc:+ if cancellation is None:+ cancellation = exc+ if cancellation is not None:+ raise cancellation++ def _to_hints(self, item_id: str, messages: list[Msg]) -> list[HintBlock]:+ """Convert one steering input into correlated multimodal hints.++ Args:+ item_id (`str`):+ Source input identifier used to derive stable block ids.+ messages (`list[Msg]`):+ Parsed messages carried by the steering input.++ Returns:+ `list[HintBlock]`:+ One hint per message, preserving text and data blocks.++ Raises:+ `ValueError`:+ A message is empty or contains a block unsupported by hints.+ """+ if not messages:+ raise ValueError("Steering requires at least one message.")+ hints: list[HintBlock] = []+ for index, message in enumerate(messages):+ content = [+ block+ for block in message.content+ if isinstance(block, (TextBlock, DataBlock))+ ]+ if not content or len(content) != len(message.content):+ raise ValueError(+ f"Message '{message.id}' contains unsupported content.",+ )+ hints.append(+ HintBlock(+ id=f"{item_id}:{index}",+ hint=content,+ source=self._hint_source,+ ),+ )+ return hints++ @staticmethod+ def _append_hints(+ agent: "Agent",+ hints: list[HintBlock],+ ) -> Callable[[], None]:+ """Append hints synchronously and return an exact rollback callback."""+ if agent.state.context:+ last_message = agent.state.context[-1]+ if (+ last_message.role == "assistant"+ and last_message.name == agent.name+ and last_message.id == agent.state.reply_id+ ):+ original_length = len(last_message.content)+ last_message.content.extend(hints)++ def rollback_extension() -> None:+ del last_message.content[original_length:]++ return rollback_extension++ injected_message = AssistantMsg(+ id=agent.state.reply_id,+ name=agent.name,+ content=list(hints),+ )+ agent.state.context.append(injected_message)++ def rollback_message() -> None:+ if (+ agent.state.context+ and agent.state.context[-1] is injected_message+ ):+ agent.state.context.pop()++ return rollback_messagediff --git a/src/agentscope/middleware/_steering_queue.py b/src/agentscope/middleware/_steering_queue.pynew file mode 100644index 000000000..f647e5c98--- /dev/null+++ b/src/agentscope/middleware/_steering_queue.py@@ -0,0 +1,215 @@+# -*- coding: utf-8 -*-+"""Input sources and receipts for cooperative reply steering."""+import asyncio+from abc import ABC, abstractmethod+from dataclasses import dataclass, field+from typing import Literal++from .._utils._common import _generate_id+from ..message import Msg+++@dataclass(frozen=True)+class SteeringInput:+ """One ordered steering input with a source-owned identifier.++ Args:+ id: Identifier used to acknowledge or reject this input.+ messages: Messages whose text and data blocks guide the reply.+ """++ id: str+ messages: list[Msg]+++class SteeringSource(ABC):+ """Supply reply-scoped inputs without coupling agents to a transport.++ Reads must be non-destructive. Acknowledgement removes only the supplied+ inputs and must raise before committing if it cannot accept the change.+ The middleware waits for acknowledgement in a shielded task, including+ when its caller is repeatedly cancelled. Sources must finish committing+ before returning and must not report post-commit cleanup or notification+ failures as acknowledgement failures. Cancellation is propagated only+ after the middleware has resolved whether to retain or roll back hints.+ Committed hint events are yielded before cancellation is propagated so+ event consumers can persist the same inputs as the agent context.+ Lifecycle hooks are optional for externally managed sources.+ """++ async def start_reply(self, session_id: str, reply_id: str) -> None:+ """Open an input window when a reply starts or resumes."""++ async def finish_reply(self, session_id: str, reply_id: str) -> None:+ """Close an input window and settle its unconsumed inputs."""++ @abstractmethod+ async def read(+ self,+ session_id: str,+ reply_id: str,+ ) -> list[SteeringInput]:+ """Read pending inputs for this reply in arrival order."""++ @abstractmethod+ async def acknowledge(+ self,+ session_id: str,+ reply_id: str,+ inputs: list[SteeringInput],+ ) -> None:+ """Acknowledge inputs appended to context without consuming others."""++ @abstractmethod+ async def reject(+ self,+ session_id: str,+ reply_id: str,+ item: SteeringInput,+ error: str,+ ) -> None:+ """Record an input that cannot be injected into context."""+++@dataclass+class SteeringReceipt:+ """Track acceptance separately from context injection.++ Args:+ id: Identifier assigned to the accepted input.++ Attributes:+ status: Pending, injected, unconsumed or failed. Injection means the+ input reached context, not that a model followed the instruction.+ error: Validation error for a failed input, otherwise None.+ """++ id: str+ status: Literal["pending", "injected", "unconsumed", "failed"] = field(+ default="pending",+ init=False,+ )+ error: str | None = field(default=None, init=False)+ _done: asyncio.Event = field(+ default_factory=asyncio.Event,+ init=False,+ repr=False,+ )++ async def wait(self) -> str:+ """Wait for a terminal status; cancelling this wait keeps delivery."""+ await self._done.wait()+ return self.status++ def _finish(+ self,+ status: Literal["injected", "unconsumed", "failed"],+ error: str | None = None,+ ) -> None:+ """Settle a receipt after its input leaves the source."""+ self.status = status+ self.error = error+ self._done.set()+++# Receipts are settled only by their owning queue.+# pylint: disable=protected-access+class SteeringQueue(SteeringSource):+ """An in-process source used on the same event loop as the agent.++ Attach it to a SteeringMiddleware, then submit after ReplyStartEvent.+ The queue is not persistent or thread-safe. A reply that ends or parks+ leaves unconsumed inputs with the caller rather than starting a new turn.+ """++ def __init__(self) -> None:+ """Initialize isolated input windows for active replies."""+ self._pending: dict[+ tuple[str, str],+ dict[str, tuple[SteeringInput, SteeringReceipt]],+ ] = {}++ def submit(+ self,+ inputs: Msg | list[Msg],+ *,+ session_id: str,+ reply_id: str,+ ) -> SteeringReceipt:+ """Accept copied messages for an active reply without waiting.++ Args:+ inputs: One message or a non-empty list of messages.+ session_id: Session of the active reply.+ reply_id: Reply observed by the caller.++ Returns:+ A receipt that can be awaited with its wait method.++ Raises:+ ValueError: The reply is inactive or the message list is empty.+ """+ key = (session_id, reply_id)+ if key not in self._pending:+ raise ValueError(f"Reply '{reply_id}' is not accepting steering.")+ messages = inputs if isinstance(inputs, list) else [inputs]+ if not messages:+ raise ValueError("Steering requires at least one message.")+ item = SteeringInput(+ id=_generate_id(),+ messages=[message.model_copy(deep=True) for message in messages],+ )+ receipt = SteeringReceipt(item.id)+ self._pending[key][item.id] = (item, receipt)+ return receipt++ async def start_reply(self, session_id: str, reply_id: str) -> None:+ """Open a reply window, rejecting overlapping uses of its identity."""+ key = (session_id, reply_id)+ if key in self._pending:+ raise ValueError(f"Reply '{reply_id}' is already accepting input.")+ self._pending[key] = {}++ async def finish_reply(self, session_id: str, reply_id: str) -> None:+ """Return all remaining inputs to their callers as unconsumed."""+ for _, receipt in self._pending.pop(+ (session_id, reply_id),+ {},+ ).values():+ receipt._finish("unconsumed")++ async def read(+ self,+ session_id: str,+ reply_id: str,+ ) -> list[SteeringInput]:+ """Return pending inputs without transferring ownership."""+ pending = self._pending.get((session_id, reply_id), {})+ return [item for item, _ in pending.values()]++ async def acknowledge(+ self,+ session_id: str,+ reply_id: str,+ inputs: list[SteeringInput],+ ) -> None:+ """Settle the specified inputs after context injection."""+ pending = self._pending.get((session_id, reply_id), {})+ if any(item.id not in pending for item in inputs):+ raise LookupError("The steering inputs are no longer pending.")+ for item in inputs:+ _, receipt = pending.pop(item.id)+ receipt._finish("injected")++ async def reject(+ self,+ session_id: str,+ reply_id: str,+ item: SteeringInput,+ error: str,+ ) -> None:+ """Settle one invalid input without affecting other pending inputs."""+ pending = self._pending.get((session_id, reply_id), {})+ entry = pending.pop(item.id, None)+ if entry is not None:+ entry[1]._finish("failed", error)diff --git a/tests/service_steering_middleware_test.py b/tests/service_steering_middleware_test.pynew file mode 100644index 000000000..e258e2062--- /dev/null+++ b/tests/service_steering_middleware_test.py@@ -0,0 +1,1014 @@+# -*- coding: utf-8 -*-+"""Tests for queued-message steering state and reasoning boundaries."""+import asyncio+import json+from contextlib import asynccontextmanager+from types import SimpleNamespace+from typing import Any, AsyncGenerator+from unittest import IsolatedAsyncioTestCase+from unittest.mock import AsyncMock, patch++import fakeredis.aioredis++from agentscope.app import _bus_ops+from agentscope.app._bus_ops import (+ ChatSteeringUnavailableError,+ acknowledge_steering_chat_inputs,+ enqueue_chat_input,+ fail_steering_chat_input,+ finish_active_chat_reply,+ list_chat_inputs,+ register_active_chat_reply,+ steer_chat_input,+)+from agentscope.app.message_bus import (+ InMemoryMessageBus,+ MessageBus,+ MessageBusKeys,+ RedisMessageBus,+)+from agentscope.app.middleware import SteeringMiddleware+from agentscope.app.middleware import _steering_middleware as _steering_adapter+from agentscope.event import HintBlockEvent+from agentscope.message import (+ AssistantMsg,+ HintBlock,+ Msg,+ ToolCallBlock,+ UserMsg,+)++_STEERING_HINT_SOURCE = "chat_input_steering"+++def _make_agent() -> SimpleNamespace:+ """Build the state shape used by SteeringMiddleware."""+ return SimpleNamespace(+ name="agent",+ state=SimpleNamespace(+ session_id="session",+ reply_id="reply",+ cur_iter=0,+ context=[UserMsg(name="user", content="initial")],+ ),+ react_config=SimpleNamespace(max_iters=10),+ compress_context=AsyncMock(),+ )+++async def _collect(generator: AsyncGenerator) -> list:+ """Collect one asynchronous event generator."""+ return [event async for event in generator]+++def _without_timestamps(value: Any) -> Any:+ """Remove volatile timestamps while retaining the complete structure."""+ if isinstance(value, dict):+ return {+ key: _without_timestamps(item)+ for key, item in value.items()+ if key not in {"created_at", "finished_at"}+ }+ if isinstance(value, list):+ return [_without_timestamps(item) for item in value]+ return value+++def _message_structures(messages: list[Msg]) -> list[dict]:+ """Serialize complete messages without volatile timestamps."""+ return [+ _without_timestamps(message.model_dump(mode="json"))+ for message in messages+ ]+++def _hint_event_structure(event: HintBlockEvent) -> dict:+ """Serialize a complete hint event without generated identity fields."""+ payload = _without_timestamps(event.model_dump(mode="json"))+ payload.pop("id")+ return payload+++def _expected_hint_message(item_id: str, message: Msg) -> Msg:+ """Build the current-reply context message for one steered input."""+ return AssistantMsg(+ id="reply",+ name="agent",+ content=[+ HintBlock(+ id=f"{item_id}:0",+ source=_STEERING_HINT_SOURCE,+ hint=list(message.content),+ ),+ ],+ )+++def _expected_hint_event(item_id: str, message: Msg) -> dict:+ """Build the stable complete event structure for one steering hint."""+ return _hint_event_structure(+ HintBlockEvent(+ reply_id="reply",+ block_id=f"{item_id}:0",+ source=_STEERING_HINT_SOURCE,+ hint=list(message.content),+ ),+ )+++async def _custom_events(bus: MessageBus) -> list[dict]:+ """Read complete custom events without generated identity fields."""+ entries = await bus.log_read(MessageBusKeys.session_events("session"))+ events: list[dict] = []+ for _entry_id, payload in entries:+ if payload.get("type") != "CUSTOM":+ continue+ stable = _without_timestamps(payload)+ stable.pop("id")+ events.append(stable)+ return events+++@asynccontextmanager+async def _cancellation_bus(backend: str) -> AsyncGenerator[MessageBus, None]:+ """Exercise the same cancellation boundaries with both bus backends."""+ if backend == "memory":+ async with InMemoryMessageBus() as bus:+ yield bus+ else:+ redis = fakeredis.aioredis.FakeRedis(decode_responses=True)+ try:+ redis_bus = RedisMessageBus()+ with patch.object(redis_bus, "_client", redis):+ yield redis_bus+ finally:+ await redis.aclose()+++class TestSteeringCancellation(IsolatedAsyncioTestCase):+ """Cancellation must not undo context after the queue commit."""++ async def test_cancellation_waits_for_acknowledgement_outcome(+ self,+ ) -> None:+ """Persist only after commit resolution, even on repeated Stop."""+ for backend in ("memory", "redis"):+ for boundary in (+ "before_commit",+ "before_commit_failure",+ "commit_response",+ "payload_cleanup",+ "queue_notification",+ "injection_notification",+ ):+ for cancellations in (1, 3):+ with self.subTest(+ backend=backend,+ boundary=boundary,+ cancellations=cancellations,+ ):+ async with _cancellation_bus(backend) as bus:+ await self._check_cancellation(+ bus,+ boundary,+ cancellations,+ )++ async def _check_cancellation(+ self,+ bus: MessageBus,+ boundary: str,+ cancellations: int,+ ) -> None:+ """Cancel at a controlled await, then release its actual outcome."""+ agent = _make_agent()+ initial = agent.state.context[0]+ messages = [+ UserMsg("user", text) for text in ("first", "guide", "last")+ ]+ items = [+ await enqueue_chat_input(bus, "user", "session", "agent", msg)+ for msg in messages+ ]+ entered = asyncio.Event()+ release = asyncio.Event()+ ack_cancelled = asyncio.Event()+ finished = asyncio.Event()+ persisted: list = []+ restored: list = []+ model_calls: list = []++ async def model_call(**_kwargs: object) -> AsyncGenerator:+ model_calls.append("called")+ yield AssistantMsg(id="reply", name="agent", content="unused")++ async def run() -> None:+ try:+ await _collect(+ SteeringMiddleware(bus).on_reasoning(+ agent,+ {},+ model_call,+ ),+ )+ finally:+ persisted.extend(_message_structures(agent.state.context))+ restored.extend(+ await finish_active_chat_reply(bus, "session", "reply"),+ )+ finished.set()++ target: Any+ if boundary in (+ "before_commit",+ "before_commit_failure",+ "commit_response",+ ):+ target, operation = bus, "queue_replace"+ elif boundary == "payload_cleanup":+ target, operation = _bus_ops, "discard_input"+ elif boundary == "queue_notification":+ target, operation = _bus_ops, "_notify_chat_queue_changed"+ else:+ target, operation = _steering_adapter, "publish_session_event"++ original = getattr(target, operation)+ async with bus.acquire_lock(MessageBusKeys.session_lock("session")):+ await register_active_chat_reply(bus, "session", "reply")+ await steer_chat_input(+ bus,+ "user",+ "session",+ "agent",+ items[1]["id"],+ "reply",+ )+ with patch.object(target, operation) as mocked:++ async def blocked(*args: Any, **kwargs: Any) -> Any:+ if entered.is_set():+ return await original(*args, **kwargs)+ result = None+ if boundary == "commit_response":+ result = await original(*args, **kwargs)+ entered.set()+ try:+ await release.wait()+ except asyncio.CancelledError:+ ack_cancelled.set()+ raise+ if boundary == "before_commit_failure":+ raise RuntimeError("commit rejected")+ if boundary == "commit_response":+ return result+ return await original(*args, **kwargs)++ mocked.side_effect = blocked+ task = asyncio.create_task(run())+ try:+ await asyncio.wait_for(entered.wait(), timeout=2)+ for _ in range(cancellations):+ task.cancel("stop")+ await asyncio.sleep(0)+ self.assertFalse(ack_cancelled.is_set())+ self.assertFalse(finished.is_set())+ finally:+ release.set()+ with self.assertRaises(asyncio.CancelledError) as raised:+ await asyncio.wait_for(task, timeout=2)+ self.assertEqual(raised.exception.args, ("stop",))++ rejected = boundary == "before_commit_failure"+ expected_context = [initial]+ if not rejected:+ expected_context.append(+ _expected_hint_message(items[1]["id"], messages[1]),+ )+ self.assertEqual(persisted, _message_structures(expected_context))+ self.assertEqual(_message_structures(agent.state.context), persisted)+ self.assertEqual(model_calls, [])+ self.assertEqual(restored, [items[1]["id"]] if rejected else [])+ self.assertEqual(+ await list_chat_inputs(bus, "session"),+ items if rejected else [items[0], items[2]],+ )+ remaining = items if rejected else [items[0], items[2]]+ self.assertEqual(+ await bus.registry_getall(+ MessageBusKeys.chat_input_payloads("session"),+ ),+ {item["id"]: json.dumps(item["input"]) for item in remaining},+ )+ self.assertEqual(+ await _custom_events(bus),+ []+ if rejected+ else [+ {+ "metadata": {},+ "type": "CUSTOM",+ "name": "chat_input_injected",+ "value": {+ "queue_item_id": items[1]["id"],+ "message_ids": [messages[1].id],+ },+ },+ ],+ )+++class TestSteeringQueueState(IsolatedAsyncioTestCase):+ """Queue reservations remain durable until injection or fallback."""++ async def test_steering_preserves_reference_storage(self) -> None:+ """Steer, failure and fallback keep payloads out of the FIFO."""+ bus = InMemoryMessageBus()+ message = UserMsg(name="user", content="guide")+ item = await enqueue_chat_input(+ bus,+ "user",+ "session",+ "agent",+ message,+ )+ expected = {+ "id": item["id"],+ "user_id": "user",+ "session_id": "session",+ "agent_id": "agent",+ "created_at": item["created_at"],+ "input_ref": item["id"],+ "state": "queued",+ }+ async with bus.acquire_lock(MessageBusKeys.session_lock("session")):+ await register_active_chat_reply(bus, "session", "reply")+ for transition in ("steer", "fail", "steer", "finish"):+ with self.subTest(transition=transition):+ if transition == "steer":+ await steer_chat_input(+ bus,+ "user",+ "session",+ "agent",+ item["id"],+ "reply",+ )+ expected["state"] = "steering"+ expected["target_reply_id"] = "reply"+ expected.pop("error", None)+ elif transition == "fail":+ await fail_steering_chat_input(+ bus,+ "session",+ "reply",+ item["id"],+ "invalid",+ )+ expected["state"] = "failed"+ expected["error"] = "invalid"+ expected.pop("target_reply_id")+ else:+ await finish_active_chat_reply(bus, "session", "reply")+ expected["state"] = "queued"+ expected.pop("target_reply_id")+ entries = await bus.queue_read(+ MessageBusKeys.chat_inputs("session"),+ )+ self.assertEqual(+ [entry for _, entry in entries],+ [expected],+ )+ self.assertEqual(+ await bus.registry_getall(+ MessageBusKeys.chat_input_payloads("session"),+ ),+ {+ item["id"]: json.dumps(+ message.model_dump(mode="json"),+ ),+ },+ )++ async def test_notification_failure_keeps_steering_committed(self) -> None:+ """A failed broadcast cannot reject reservation or acknowledgement."""+ bus = InMemoryMessageBus()+ item = await enqueue_chat_input(+ bus,+ "user",+ "session",+ "agent",+ UserMsg("user", "guide"),+ )+ async with bus.acquire_lock(MessageBusKeys.session_lock("session")):+ await register_active_chat_reply(bus, "session", "reply")+ with patch.object(+ _bus_ops,+ "_publish_chat_queue_changed",+ side_effect=ConnectionError("offline"),+ ):+ reserved = await steer_chat_input(+ bus,+ "user",+ "session",+ "agent",+ item["id"],+ "reply",+ )+ self.assertEqual(reserved, [{**item, "state": "steering"}])+ removed = await acknowledge_steering_chat_inputs(+ bus,+ "session",+ "reply",+ [item["id"]],+ )+ self.assertEqual(removed, reserved)+ self.assertEqual(await list_chat_inputs(bus, "session"), [])+ self.assertEqual(+ await bus.registry_getall(+ MessageBusKeys.chat_input_payloads("session"),+ ),+ {},+ )++ async def test_reserve_is_idempotent_and_finish_restores(self) -> None:+ """Repeated Steer targets once and ReplyEnd restores deferred send."""+ bus = InMemoryMessageBus()+ item = await enqueue_chat_input(+ bus,+ "user",+ "session",+ "agent",+ UserMsg(name="user", content="guide"),+ )++ async with bus.acquire_lock(+ MessageBusKeys.session_lock("session"),+ ttl_secs=60,+ ):+ await register_active_chat_reply(bus, "session", "reply")+ first = await steer_chat_input(+ bus,+ "user",+ "session",+ "agent",+ item["id"],+ "reply",+ )+ second = await steer_chat_input(+ bus,+ "user",+ "session",+ "agent",+ item["id"],+ "reply",+ )+ steering_item = {+ **item,+ "state": "steering",+ "error": None,+ }+ self.assertEqual(first, [steering_item])+ self.assertEqual(second, [steering_item])++ restored = await finish_active_chat_reply(+ bus,+ "session",+ "reply",+ )+ self.assertEqual(restored, [item["id"]])++ self.assertEqual(await list_chat_inputs(bus, "session"), [item])++ async def test_acknowledge_non_head_preserves_other_items(self) -> None:+ """Injecting one selected item never changes other FIFO entries."""+ bus = InMemoryMessageBus()+ first = await enqueue_chat_input(+ bus,+ "user",+ "session",+ "agent",+ UserMsg(name="user", content="first"),+ )+ selected = await enqueue_chat_input(+ bus,+ "user",+ "session",+ "agent",+ UserMsg(name="user", content="selected"),+ )+ third = await enqueue_chat_input(+ bus,+ "user",+ "session",+ "agent",+ UserMsg(name="user", content="third"),+ )++ async with bus.acquire_lock(+ MessageBusKeys.session_lock("session"),+ ttl_secs=60,+ ):+ await register_active_chat_reply(bus, "session", "reply")+ await steer_chat_input(+ bus,+ "user",+ "session",+ "agent",+ selected["id"],+ "reply",+ )+ removed = await acknowledge_steering_chat_inputs(+ bus,+ "session",+ "reply",+ [selected["id"]],+ )+ self.assertEqual(+ removed,+ [+ {+ **selected,+ "state": "steering",+ "error": None,+ },+ ],+ )++ self.assertEqual(+ await list_chat_inputs(bus, "session"),+ [first, third],+ )+ self.assertEqual(+ await bus.registry_getall(+ MessageBusKeys.chat_input_payloads("session"),+ ),+ {+ first["id"]: json.dumps(first["input"]),+ third["id"]: json.dumps(third["input"]),+ },+ )++ async def test_stale_reply_is_rejected_without_changing_item(self) -> None:+ """A client reply id must match the server-side active registry."""+ bus = InMemoryMessageBus()+ item = await enqueue_chat_input(+ bus,+ "user",+ "session",+ "agent",+ UserMsg(name="user", content="guide"),+ )++ async with bus.acquire_lock(+ MessageBusKeys.session_lock("session"),+ ttl_secs=60,+ ):+ await register_active_chat_reply(bus, "session", "current")+ with self.assertRaises(ChatSteeringUnavailableError):+ await steer_chat_input(+ bus,+ "user",+ "session",+ "agent",+ item["id"],+ "stale",+ )++ self.assertEqual(await list_chat_inputs(bus, "session"), [item])+++class TestSteeringMiddleware(IsolatedAsyncioTestCase):+ """Steering is consumed before or after a model call as needed."""++ async def test_injection_notification_failure_keeps_committed_hint(+ self,+ ) -> None:+ """A failed terminal event cannot roll back an acknowledged hint."""+ bus = InMemoryMessageBus()+ agent = _make_agent()+ message = UserMsg("user", "guide")+ item = await enqueue_chat_input(+ bus,+ "user",+ "session",+ "agent",+ message,+ )++ async def model_call(**_kwargs: object) -> AsyncGenerator:+ yield AssistantMsg(id="reply", name="agent", content="done")++ async with bus.acquire_lock(MessageBusKeys.session_lock("session")):+ await register_active_chat_reply(bus, "session", "reply")+ await steer_chat_input(+ bus,+ "user",+ "session",+ "agent",+ item["id"],+ "reply",+ )+ with patch(+ "agentscope.app.middleware._steering_middleware."+ "publish_session_event",+ side_effect=ConnectionError("offline"),+ ):+ events = await _collect(+ SteeringMiddleware(bus).on_reasoning(+ agent,+ {},+ model_call,+ ),+ )+ self.assertEqual(await list_chat_inputs(bus, "session"), [])+ self.assertEqual(+ _message_structures(agent.state.context[1:]),+ _message_structures([_expected_hint_message(item["id"], message)]),+ )+ self.assertEqual(+ [+ _hint_event_structure(event)+ for event in events+ if isinstance(event, HintBlockEvent)+ ],+ [_expected_hint_event(item["id"], message)],+ )++ async def test_pre_call_steering_reaches_one_model_call(self) -> None:+ """An already reserved item is visible to the immediate model call."""+ bus = InMemoryMessageBus()+ agent = _make_agent()+ initial = agent.state.context[0]+ guide = UserMsg(name="user", content="guide")+ item = await enqueue_chat_input(+ bus,+ "user",+ "session",+ "agent",+ guide,+ )+ calls = 0+ response = AssistantMsg(+ id="reply",+ name="agent",+ content="done",+ )++ async def model_call(**_kwargs: object) -> AsyncGenerator:+ nonlocal calls+ calls += 1+ self.assertEqual(+ _message_structures(agent.state.context),+ _message_structures(+ [initial, _expected_hint_message(item["id"], guide)],+ ),+ )+ agent.state.context.append(response)+ yield response++ async with bus.acquire_lock(+ MessageBusKeys.session_lock("session"),+ ttl_secs=60,+ ):+ await register_active_chat_reply(bus, "session", "reply")+ await steer_chat_input(+ bus,+ "user",+ "session",+ "agent",+ item["id"],+ "reply",+ )+ events = await _collect(+ SteeringMiddleware(bus).on_reasoning(+ agent,+ {},+ model_call,+ ),+ )++ self.assertEqual(calls, 1)+ self.assertEqual(+ [+ _hint_event_structure(event)+ if isinstance(event, HintBlockEvent)+ else event+ for event in events+ ],+ [_expected_hint_event(item["id"], guide), response],+ )+ self.assertEqual(await list_chat_inputs(bus, "session"), [])++ async def test_hint_does_not_attach_to_previous_reply(self) -> None:+ """A same-agent tail from an older reply remains unchanged."""+ bus = InMemoryMessageBus()+ agent = _make_agent()+ previous = AssistantMsg(+ id="previous-reply",+ name="agent",+ content="previous response",+ )+ agent.state.context = [previous]+ guide = UserMsg(name="user", content="guide current reply")+ item = await enqueue_chat_input(+ bus,+ "user",+ "session",+ "agent",+ guide,+ )++ async def model_call(**_kwargs: object) -> AsyncGenerator:+ self.assertEqual(+ _message_structures(agent.state.context),+ _message_structures(+ [+ previous,+ _expected_hint_message(item["id"], guide),+ ],+ ),+ )+ yield AssistantMsg(id="reply", name="agent", content="done")++ async with bus.acquire_lock(+ MessageBusKeys.session_lock("session"),+ ttl_secs=60,+ ):+ await register_active_chat_reply(bus, "session", "reply")+ await steer_chat_input(+ bus,+ "user",+ "session",+ "agent",+ item["id"],+ "reply",+ )+ await _collect(+ SteeringMiddleware(bus).on_reasoning(+ agent,+ {},+ model_call,+ ),+ )++ self.assertEqual(+ _message_structures(agent.state.context),+ _message_structures(+ [previous, _expected_hint_message(item["id"], guide)],+ ),+ )++ async def test_post_call_steering_continues_model_only_reply(self) -> None:+ """A mid-stream steer yields continuation to the Agent's next round."""+ bus = InMemoryMessageBus()+ agent = _make_agent()+ guide = UserMsg(name="user", content="new direction")+ item = await enqueue_chat_input(+ bus,+ "user",+ "session",+ "agent",+ guide,+ )+ calls = 0+ responses: list[Msg] = []++ async def model_call(**_kwargs: object) -> AsyncGenerator:+ nonlocal calls+ calls += 1+ response = AssistantMsg(+ id="reply",+ name="agent",+ content=f"response {calls}",+ )+ responses.append(response)+ agent.state.context.append(response)+ if calls == 1:+ await steer_chat_input(+ bus,+ "user",+ "session",+ "agent",+ item["id"],+ "reply",+ )+ yield response++ async with bus.acquire_lock(+ MessageBusKeys.session_lock("session"),+ ttl_secs=60,+ ):+ await register_active_chat_reply(bus, "session", "reply")+ events = await _collect(+ SteeringMiddleware(bus).on_reasoning(+ agent,+ {},+ model_call,+ ),+ )+ self.assertEqual(calls, 1)+ self.assertEqual(+ [event for event in events if isinstance(event, Msg)],+ [],+ )+ events.extend(+ await _collect(+ SteeringMiddleware(bus).on_reasoning(+ agent,+ {},+ model_call,+ ),+ ),+ )++ self.assertEqual(calls, 2)+ self.assertEqual(+ [+ _hint_event_structure(event)+ if isinstance(event, HintBlockEvent)+ else event+ for event in events+ ],+ [_expected_hint_event(item["id"], guide), responses[1]],+ )+ self.assertEqual(+ await _custom_events(bus),+ [+ {+ "metadata": {},+ "type": "CUSTOM",+ "name": "chat_input_injected",+ "value": {+ "queue_item_id": item["id"],+ "message_ids": [guide.id],+ },+ },+ ],+ )++ async def test_post_call_tool_path_does_not_repeat_reasoning(self) -> None:+ """A tool-bound response leaves steering for the next reasoning."""+ bus = InMemoryMessageBus()+ agent = _make_agent()+ initial = agent.state.context[0]+ guide = UserMsg(name="user", content="guide after tool")+ item = await enqueue_chat_input(+ bus,+ "user",+ "session",+ "agent",+ guide,+ )+ calls = 0++ async def tool_model_call(**_kwargs: object) -> AsyncGenerator:+ nonlocal calls+ calls += 1+ agent.state.context.append(+ AssistantMsg(+ id="reply",+ name="agent",+ content=[+ ToolCallBlock(+ id="tool",+ name="work",+ input="{}",+ ),+ ],+ ),+ )+ await steer_chat_input(+ bus,+ "user",+ "session",+ "agent",+ item["id"],+ "reply",+ )+ return+ yield # pragma: no cover++ async with bus.acquire_lock(+ MessageBusKeys.session_lock("session"),+ ttl_secs=60,+ ):+ await register_active_chat_reply(bus, "session", "reply")+ events = await _collect(+ SteeringMiddleware(bus).on_reasoning(+ agent,+ {},+ tool_model_call,+ ),+ )+ self.assertEqual(events, [])++ async def after_tool(**_kwargs: object) -> AsyncGenerator:+ yield AssistantMsg(id="reply", name="agent", content="done")++ events = await _collect(+ SteeringMiddleware(bus).on_reasoning(agent, {}, after_tool),+ )++ self.assertEqual(calls, 1)+ self.assertEqual(+ [+ _hint_event_structure(event)+ for event in events+ if isinstance(event, HintBlockEvent)+ ],+ [_expected_hint_event(item["id"], guide)],+ )+ expected_tool_message = AssistantMsg(+ id="reply",+ name="agent",+ content=[+ ToolCallBlock(id="tool", name="work", input="{}"),+ _expected_hint_message(item["id"], guide).content[0],+ ],+ )+ self.assertEqual(+ _message_structures(agent.state.context),+ _message_structures([initial, expected_tool_message]),+ )++ async def test_unsupported_content_stays_failed_in_queue(self) -> None:+ """Preparation failures remain visible and never discard the item."""+ bus = InMemoryMessageBus()+ agent = _make_agent()+ original = UserMsg(name="user", content="will be corrupted")+ item = await enqueue_chat_input(+ bus,+ "user",+ "session",+ "agent",+ original,+ )+ await bus.registry_set(+ MessageBusKeys.chat_input_payloads("session"),+ item["id"],+ json.dumps({"invalid": "message"}),+ )++ async def model_call(**_kwargs: object) -> AsyncGenerator:+ response = AssistantMsg(+ id="reply",+ name="agent",+ content="done",+ )+ agent.state.context.append(response)+ yield response++ async with bus.acquire_lock(+ MessageBusKeys.session_lock("session"),+ ttl_secs=60,+ ):+ await register_active_chat_reply(bus, "session", "reply")+ await steer_chat_input(+ bus,+ "user",+ "session",+ "agent",+ item["id"],+ "reply",+ )+ events = await _collect(+ SteeringMiddleware(bus).on_reasoning(+ agent,+ {},+ model_call,+ ),+ )++ queued = await list_chat_inputs(bus, "session")+ error = queued[0]["error"]+ self.assertIsInstance(error, str)+ self.assertEqual(+ queued,+ [+ {+ **item,+ "input": {"invalid": "message"},+ "state": "failed",+ "error": error,+ },+ ],+ )+ self.assertEqual(+ [event for event in events if isinstance(event, Msg)],+ [agent.state.context[-1]],+ )+ self.assertEqual(+ await _custom_events(bus),+ [+ {+ "metadata": {},+ "type": "CUSTOM",+ "name": "chat_input_steer_failed",+ "value": {+ "queue_item_id": item["id"],+ "message_ids": [],+ "message": error,+ },+ },+ ],+ )diff --git a/tests/service_wakeup_dispatcher_test.py b/tests/service_wakeup_dispatcher_test.pyindex 1b39fe374..3e9a08926 100644--- a/tests/service_wakeup_dispatcher_test.py+++ b/tests/service_wakeup_dispatcher_test.py@@ -1771,6 +1771,8 @@ class TestChatEndpointQueue(IsolatedAsyncioTestCase):"id": response.queue_item_id,"created_at": items[0]["created_at"],"input": message.model_dump(mode="json"),+ "state": "queued",+ "error": None,},],)@@ -1820,6 +1822,8 @@ class TestChatEndpointQueue(IsolatedAsyncioTestCase):"id": response.queue_item_id,"created_at": items[0]["created_at"],"input": message.model_dump(mode="json"),+ "state": "queued",+ "error": None,},],)